Get Credit Usage API
Get Credit Usage API: use GET {{API_BASE_URL}}/v1/usage/ to get credit usage and retrieve credit usage history for a project. Without filters, the endpoint returns project-level totals. Add profileId to scope the result to a specific profile, or integrationId to scope it to a specific connected account. Use from and to in YYYY-MM format to slice the history by month. Each entry in the returned history contains a monthly credit count and a per-platform breakdown.
Get Credit Usage API — GET {{API_BASE_URL}}/v1/usage/
Get credit usage by calling GET {{API_BASE_URL}}/v1/usage/ with the trailing slash preserved exactly as shown. Send the access key in the x-access-key header. The endpoint returns credit usage history for the project, and the shape of the response depends on whether you scope the request to a profile, an integration, or neither. Without any scope filter, the response contains project-level totals and, when present, the current balance. With a profileId or integrationId filter, the history is scoped to that profile or connected account instead.
Authorization
Authorization uses the accessKey scheme named x-access-key, sent in the header as x-access-key: <token>. Keep the token out of URLs and logs, and send it only in the header. The captured contract specifies this header as the authentication mechanism for the endpoint; it does not specify additional authorization status codes, so client code should not assume a particular status for a missing or invalid key beyond what the response returns.
Query Parameters
All four query parameters are optional strings. profileId returns usage for this profile only and is mutually exclusive with integrationId. integrationId returns usage for this integration only and is mutually exclusive with profileId. from is an inclusive start month in YYYY-MM format matching ^\d{4}-(0[1-9]|1[0-2])$ and filters the usage history array. to is an inclusive end month in the same YYYY-MM format and pattern, and also filters the usage history array. Send at most one of profileId and integrationId in a single request, and format from and to as four-digit year, hyphen, and two-digit month.
Scoping decision guide
Choose the scope that matches the question you are answering. Omit both profileId and integrationId when you need project-level totals and the current balance. Use profileId when usage must be attributed to one profile, and use integrationId when usage must be attributed to one connected account. Add from and to when you need a slice of the monthly history rather than the full history. A common failure is sending both profileId and integrationId together, which violates their mutual exclusivity, and another is sending a date such as 2026-1 or 2026/01 instead of the required YYYY-MM form. When a scoped request returns history without a balance, that is consistent with the contract: balance is only present on project-level requests with no profileId or integrationId filter.
200 application/json
A 200 response returns application/json with success as a required boolean, totalUsage as a required integer representing all-time credits used with a minimum of 0, and usage as a required array of monthly entries ordered oldest first. Each usage entry contains year as a required integer calendar year, month as a required integer from 1 to 12, count as a required integer of subscription monthly plan credits used that month with a minimum of 0, purchasedCount as a required integer of one-time or credit-pack credits used that month with a minimum of 0, and platform as a required object breaking credits down by platform name, where each platform value is an integer with a minimum of 0. The optional balance object is only present on project-level requests. Its monthly object contains limit, used, and remaining as required integers, plus cycleStart and cycleEnd as required date-time strings marking the start and end of the current billing cycle. Its purchased object contains total, used, and remaining as required integers for one-time credits, where total is described as never expiring in the captured field description. Read count and purchasedCount separately when reconciling a month, because they track different credit sources, and read platform values to see which platforms consumed credits in that month.
400 and 404 application/json
A 400 response returns application/json with success as a required boolean and message as a required string. A 404 response returns the same captured shape: success as a required boolean and message as a required string. The captured contract does not specify additional error codes or message text for these statuses, so client code should branch on the status code and surface the message field without assuming specific wording. When you receive a 400, recheck the query parameters, especially the profileId and integrationId mutual exclusivity and the YYYY-MM format of from and to. When you receive a 404, recheck the identifiers you supplied and the exact path, including the trailing slash on /v1/usage/.
| Parameter | Type | Required | Description |
|---|---|---|---|
| profileId | string | No | Return usage for this profile only. Mutually exclusive with integrationId. |
| integrationId | string | No | Return usage for this integration only. Mutually exclusive with profileId. |
| from | string | No | Inclusive start month (YYYY-MM). Filters the usage history array. Match ^\d{4}-(0[1-9]|1[0-2])$. |
| to | string | No | Inclusive end month (YYYY-MM). Filters the usage history array. Match ^\d{4}-(0[1-9]|1[0-2])$. |
Captured contract; illustrative_unexecuted
| Field | Type | Required | Description |
|---|---|---|---|
| success | boolean | Yes | Response success flag. |
| totalUsage | integer | Yes | All-time credits used. Minimum 0. |
| usage | array<object> | Yes | Monthly credit history, oldest first. |
| usage[].year | integer | Yes | Calendar year. |
| usage[].month | integer | Yes | Calendar month (1-12). |
| usage[].count | integer | Yes | Subscription (monthly plan) credits used this month. Minimum 0. |
| usage[].purchasedCount | integer | Yes | One-time / credit-pack credits used this month. Minimum 0. |
| usage[].platform | object | Yes | Credits broken down by platform name; each value is an integer with minimum 0. |
| balance | object | No | Current credit balance. Only present on project-level requests (no profileId or integrationId filter). |
| balance.monthly.limit | integer | Yes | Total monthly credits included in your plan. |
| balance.monthly.used | integer | Yes | Monthly credits used so far this billing cycle. |
| balance.monthly.remaining | integer | Yes | Monthly credits still available this cycle. |
| balance.monthly.cycleStart | string (date-time) | Yes | Start of the current billing cycle. |
| balance.monthly.cycleEnd | string (date-time) | Yes | End of the current billing cycle — resets here. |
| balance.purchased.total | integer | Yes | Total one-time credits purchased (never expire). |
| balance.purchased.used | integer | Yes | One-time credits consumed so far. |
| balance.purchased.remaining | integer | Yes | One-time credits still available. |
Captured contract; illustrative_unexecuted
| Status | Content type | Fields |
|---|---|---|
| 400 | application/json | success (boolean, required), message (string, required) |
| 404 | application/json | success (boolean, required), message (string, required) |
Captured contract; illustrative_unexecuted
| Goal | Request shape | What to read |
|---|---|---|
| Project totals and current balance | No profileId or integrationId | totalUsage, usage, and balance (monthly and purchased) |
| Usage for one profile | profileId only | Scoped usage history; balance is not present on scoped requests |
| Usage for one connected account | integrationId only | Scoped usage history; balance is not present on scoped requests |
| History for a month range | from and/or to in YYYY-MM | Filtered usage array, oldest first |
| Monthly vs purchased consumption in a month | Any scope, then inspect an entry | count for subscription credits and purchasedCount for one-time credits, plus platform breakdown |
Guidance derived from captured contract; illustrative_unexecuted
curl -X GET "{{API_BASE_URL}}/v1/usage/" \
-H "x-access-key: <token>"curl -X GET "{{API_BASE_URL}}/v1/usage/?profileId=<profileId>&from=2026-01&to=2026-03" \
-H "x-access-key: <token>"curl -X GET "{{API_BASE_URL}}/v1/usage/?integrationId=<integrationId>" \
-H "x-access-key: <token>"{
"success": true,
"totalUsage": 0,
"usage": [
{
"year": 0,
"month": 1,
"count": 0,
"purchasedCount": 0,
"platform": {
"property1": 0,
"property2": 0
}
}
],
"balance": {
"monthly": {
"limit": 0,
"used": 0,
"remaining": 0,
"cycleStart": "2019-08-24T14:15:22Z",
"cycleEnd": "2019-08-24T14:15:22Z"
},
"purchased": {
"total": 0,
"used": 0,
"remaining": 0
}
}
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| response#1 | response | object | __0 | |||
| response#1 | response.success | boolean | __1 | Yes | ||
| response#1 | response.totalUsage | integer | __2 | Yes | All-time credits used | kind: schemaRange; value: 0 <= value |
| response#1 | response.usage | array<object> | __3 | Yes | Monthly credit history, oldest first | |
| response#1 | response.usage[] | object | __4 | |||
| response#1 | response.usage[].year | integer | __5 | Yes | Calendar year | |
| response#1 | response.usage[].month | integer | __6 | Yes | Calendar month (1–12) | kind: schemaRange; value: 1 <= value <= 12 |
| response#1 | response.usage[].count | integer | __7 | Yes | Subscription (monthly plan) credits used this month | kind: schemaRange; value: 0 <= value |
| response#1 | response.usage[].purchasedCount | integer | __8 | Yes | One-time / credit-pack credits used this month | kind: schemaRange; value: 0 <= value |
| response#1 | response.usage[].platform | object | __9 | Yes | Credits broken down by platform name | |
| response#1 | response.usage[].platform.[key: string] | integer | __10 | No | kind: schemaRange; value: 0 <= value | |
| response#1 | response.balance | object | __11 | No | Current credit balance. Only present on project-level requests (no profileId or integrationId filter). | |
| response#1 | response.balance.monthly | object | __12 | Yes | ||
| response#1 | response.balance.monthly.limit | integer | __13 | Yes | Total monthly credits included in your plan | |
| response#1 | response.balance.monthly.used | integer | __14 | Yes | Monthly credits used so far this billing cycle | |
| response#1 | response.balance.monthly.remaining | integer | __15 | Yes | Monthly credits still available this cycle | |
| response#1 | response.balance.monthly.cycleStart | string | __16 | Yes | Start of the current billing cycle | kind: schemaFormat; value: date-time |
| response#1 | response.balance.monthly.cycleEnd | string | __17 | Yes | End of the current billing cycle — resets here | kind: schemaFormat; value: date-time |
| response#1 | response.balance.purchased | object | __18 | Yes | ||
| response#1 | response.balance.purchased.total | integer | __19 | Yes | Total one-time credits purchased (never expire) | |
| response#1 | response.balance.purchased.used | integer | __20 | Yes | One-time credits consumed so far | |
| response#1 | response.balance.purchased.remaining | integer | __21 | Yes | One-time credits still available | |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.message | string | __2 | Yes |