API reference
Net credit usage by month and platform, all-time total, and the remaining balance.
https://api.betterpost.dev/v1/usageSee Credit usage for how refunds are attributed.
| Name | Type | Description |
|---|---|---|
from | string | First month to include in usage, YYYY-MM. |
to | string | Last month to include in usage, YYYY-MM. |
profileId | string | Only usage of accounts in this profile. Omits balance. |
integrationId | string | Only usage of this account. Omits balance. |
profileId and integrationId are mutually exclusive.
curl -s "https://api.betterpost.dev/v1/usage?from=2026-10" \
-H "x-access-key: $BETTERPOST_API_KEY"200 OK
{
"success": true,
"totalUsage": 6,
"usage": [
{ "year": 2026, "month": 10, "count": 6, "purchasedCount": 0, "platform": { "twitter": 5, "linkedin": 1 } }
],
"balance": {
"monthly": {
"limit": 20,
"used": 6,
"remaining": 14,
"cycleStart": "2026-10-05T09:12:44.000Z",
"cycleEnd": "2026-11-05T09:12:44.000Z"
},
"purchased": { "total": 0, "used": 0, "remaining": 0 }
}
}| Field | Description |
|---|---|
totalUsage | Net credits used by this project, all time (not sliced by from/to). |
usage[] | Per UTC month, oldest first: year, month, count (net credits: charges minus refunds), purchasedCount (part of count paid from purchased credits), platform (net credits per platform). |
balance.monthly | Plan allowance for the current cycle: limit, used, remaining, cycleStart, cycleEnd. |
balance.purchased | Credits outside the plan: total, used, remaining. They never expire. |
The balance belongs to your account (shared by all its projects); usage and totalUsage cover this project.
| Status | Code | When |
|---|---|---|
200 | Success. | |
400 | validation_error | from or to is not YYYY-MM. |
400 | conflicting_filters | Both profileId and integrationId were given. |
401 | unauthorized | Missing or unknown API key. |
404 | not_found | profileId or integrationId does not exist in this project. |
429 | rate_limited | More than 120 requests per minute. |