Credit Usage API
The Credit Usage API returns credit usage history for a project, broken down by profile, integration, or platform. Use it to check monthly history, per-platform counts, and the current balance before deciding whether more credits are needed.
Credit Usage API overview and when to use it
The Credit Usage API returns monthly credit history and the current balance for a project. Without filters it returns project-level totals, including a balance field showing how many credits remain. You can scope the same endpoint to a profile or a specific connected account, and each monthly entry includes the total credit count for that month plus a per-platform breakdown. Choose the mode that matches the question you are answering: project-level totals for overall balance, profileId for one end-user profile, integrationId for one connected social account, or from and to for a specific month window.
Endpoint: GET {{API_BASE_URL}}/v1/usage
The endpoint is GET {{API_BASE_URL}}/v1/usage. Send the request with your API key in the x-access-key header, as shown in the cURL examples titled Mode 1 through Mode 4. All query parameters are optional, but profileId and integrationId are mutually exclusive, so pass at most one of them in a single request. The from and to parameters use the YYYY-MM format and are inclusive at both ends.
Query parameters input contract
The input contract has four optional string parameters. profileId scopes the result to a specific profile and is mutually exclusive with integrationId. integrationId scopes the result to a specific connected account, also called an integration, and is mutually exclusive with profileId. from is an inclusive start month in YYYY-MM format and filters the usage history array. to is an inclusive end month in YYYY-MM format and also filters the usage history array. The full parameter map, with types and requiredness, is in the table titled Query parameters.
Mode 1: Project-level totals
Mode 1, project-level totals, sends no filters and returns the full credit history for the project plus the current balance. In the example response, totalUsage is the all-time total, usage is the monthly history ordered oldest first, platform shows how many credits went to each platform that month, and balance reflects real-time credit state. For the monthly figure, the stored billing-cycle amount is combined with usage recorded today in cache, keeping the number current. The cycleEnd value marks the moment that monthly allowance resets. Purchased credits never expire, and the system automatically uses them after monthly credits are exhausted. Use this mode when you need the balance object, because balance is only present on project-level calls.
Mode 2: Scoped to a profile
Mode 2 passes profileId to see usage for one end-user profile. The example response shows monthly counts with a per-platform breakdown for that profile only, and no balance object. A profile with no credit use returns totalUsage of 0 with an empty usage array. Use this mode to attribute usage to a single profile without mixing in other profiles in the project.
Mode 3: Scoped to an integration
Mode 3 passes integrationId to see usage for a specific connected social account. The example response shows the monthly history for that one integration, with its platform breakdown. Use this mode when you need to isolate the cost of a single connected account. If the integrationId does not identify a found integration, the request returns a 404 status, as described in the status codes section.
Mode 4: Date range filter
Mode 4 uses from and to, both in YYYY-MM format, to slice the history to a specific window. It works with or without profileId or integrationId. Note the distinction that matters for reporting: totalUsage is always the all-time total regardless of the date filter, while usage is what gets sliced. So a filtered response can show a smaller usage array while totalUsage still reports the unfiltered all-time figure. Use this mode for month-over-month comparisons or for auditing a specific period.
Response shape field map
The response contains totalUsage as an integer for all-time credits used, unfiltered. The usage array holds monthly history, oldest first, with each entry carrying a year integer, a month integer from 1 to 12, a count integer for credits used that month, and a platform object with credits per platform name for that month. The balance object is real-time credit balance and is only present on project-level calls. Within balance, monthly limit is the Monthly credits included in your plan, monthly used is credits used so far this billing cycle, monthly remaining is credits still available, cycleStart is the ISO 8601 start of the current billing cycle, and cycleEnd is the ISO 8601 time when the monthly counter resets. The purchased fields report total one-time credits purchased, which never expire, how many have been consumed, and how many remain. The complete field map is in the table titled Response shape.
Status codes and failure matrix
A 200 status means success and the response body follows the response shape described above. A 400 status means invalid parameters or conflicting filters, for example passing both profileId and integrationId together, so correct the parameters and retry. A 404 status means the integration was not found when using integrationId, so verify the integrationId value before retrying. The failure matrix mapping each code to its cause and corrective action is in the table titled Status codes and failure matrix.
| Parameter | Type | Required | Description |
|---|---|---|---|
| profileId | string | No | Scope to a specific profile. Mutually exclusive with integrationId. |
| integrationId | string | No | Scope to a specific connected account (integration). Mutually exclusive with profileId. |
| from | string | No | Inclusive start month (YYYY-MM). Filters the usage history array. |
| to | string | No | Inclusive end month (YYYY-MM). Filters the usage history array. |
Exact source contract; origin modularized as {{API_BASE_URL}}.
| Field | Type | Description |
|---|---|---|
| totalUsage | integer | All-time credits used (unfiltered) |
| usage | array | Monthly history, oldest first |
| usage[].year | integer | Calendar year |
| usage[].month | integer | Calendar month (1–12) |
| usage[].count | integer | Credits used this month |
| usage[].platform | object | Credits per platform name this month |
| balance | object | Real-time credit balance. Only present on project-level calls |
| balance.monthly.limit | integer | Monthly credits included in your plan |
| balance.monthly.used | integer | Monthly credits used so far this billing cycle |
| balance.monthly.remaining | integer | Monthly credits still available |
| balance.monthly.cycleStart | string | ISO 8601 — start of current billing cycle |
| balance.monthly.cycleEnd | string | ISO 8601 — when the monthly counter resets |
| balance.purchased.total | integer | Total one-time credits purchased (never expire) |
| balance.purchased.used | integer | One-time credits consumed so far |
| balance.purchased.remaining | integer | One-time credits still available |
Exact source contract; balance only present on project-level calls.
| Code | Meaning | Cause | Corrective action |
|---|---|---|---|
| 200 | Success | Request accepted and response returned | Read totalUsage, usage, and balance where present |
| 400 | Invalid parameters or conflicting filters | For example profileId and integrationId passed together | Send at most one of profileId or integrationId, then retry |
| 404 | Integration not found (when using integrationId) | The integrationId does not identify a found integration | Verify the integrationId value and retry |
Meanings preserved exactly from source; cause/action columns are implementation guidance only.
GET {{API_BASE_URL}}/v1/usagecurl "{{API_BASE_URL}}/v1/usage" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"totalUsage": 1374,
"usage": [
{ "year": 2026, "month": 5, "count": 257, "platform": {} },
{ "year": 2026, "month": 6, "count": 414, "platform": {} },
{
"year": 2026,
"month": 7,
"count": 280,
"platform": { "pinterest": 12, "twitter": 268 }
}
],
"balance": {
"monthly": {
"limit": 10000,
"used": 280,
"remaining": 9720,
"cycleStart": "2026-07-02T00:00:00.000Z",
"cycleEnd": "2026-08-02T00:00:00.000Z"
},
"purchased": {
"total": 1000,
"used": 0,
"remaining": 1000
}
}
}curl "{{API_BASE_URL}}/v1/usage?profileId=69f76379ce885e092dfa375e" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"totalUsage": 45,
"usage": [
{
"year": 2026,
"month": 6,
"count": 20,
"platform": { "twitter": 15, "instagram": 5 }
},
{
"year": 2026,
"month": 7,
"count": 25,
"platform": { "twitter": 18, "pinterest": 7 }
}
]
}curl "{{API_BASE_URL}}/v1/usage?integrationId=69da6882322e75b602ad2916" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"totalUsage": 18,
"usage": [
{ "year": 2026, "month": 7, "count": 18, "platform": { "twitter": 18 } }
]
}curl "{{API_BASE_URL}}/v1/usage?from=2026-06&to=2026-07" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"totalUsage": 1374,
"usage": [
{ "year": 2026, "month": 6, "count": 414, "platform": {} },
{
"year": 2026,
"month": 7,
"count": 280,
"platform": { "pinterest": 12, "twitter": 268 }
}
]
}