Skip to content

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/.

Query parameters
ParameterTypeRequiredDescription
profileIdstringNoReturn usage for this profile only. Mutually exclusive with integrationId.
integrationIdstringNoReturn usage for this integration only. Mutually exclusive with profileId.
fromstringNoInclusive start month (YYYY-MM). Filters the usage history array. Match ^\d{4}-(0[1-9]|1[0-2])$.
tostringNoInclusive end month (YYYY-MM). Filters the usage history array. Match ^\d{4}-(0[1-9]|1[0-2])$.

Captured contract; illustrative_unexecuted

200 response field map
FieldTypeRequiredDescription
successbooleanYesResponse success flag.
totalUsageintegerYesAll-time credits used. Minimum 0.
usagearray<object>YesMonthly credit history, oldest first.
usage[].yearintegerYesCalendar year.
usage[].monthintegerYesCalendar month (1-12).
usage[].countintegerYesSubscription (monthly plan) credits used this month. Minimum 0.
usage[].purchasedCountintegerYesOne-time / credit-pack credits used this month. Minimum 0.
usage[].platformobjectYesCredits broken down by platform name; each value is an integer with minimum 0.
balanceobjectNoCurrent credit balance. Only present on project-level requests (no profileId or integrationId filter).
balance.monthly.limitintegerYesTotal monthly credits included in your plan.
balance.monthly.usedintegerYesMonthly credits used so far this billing cycle.
balance.monthly.remainingintegerYesMonthly credits still available this cycle.
balance.monthly.cycleStartstring (date-time)YesStart of the current billing cycle.
balance.monthly.cycleEndstring (date-time)YesEnd of the current billing cycle — resets here.
balance.purchased.totalintegerYesTotal one-time credits purchased (never expire).
balance.purchased.usedintegerYesOne-time credits consumed so far.
balance.purchased.remainingintegerYesOne-time credits still available.

Captured contract; illustrative_unexecuted

Error responses
StatusContent typeFields
400application/jsonsuccess (boolean, required), message (string, required)
404application/jsonsuccess (boolean, required), message (string, required)

Captured contract; illustrative_unexecuted

Scoping and interpretation matrix
GoalRequest shapeWhat to read
Project totals and current balanceNo profileId or integrationIdtotalUsage, usage, and balance (monthly and purchased)
Usage for one profileprofileId onlyScoped usage history; balance is not present on scoped requests
Usage for one connected accountintegrationId onlyScoped usage history; balance is not present on scoped requests
History for a month rangefrom and/or to in YYYY-MMFiltered usage array, oldest first
Monthly vs purchased consumption in a monthAny scope, then inspect an entrycount for subscription credits and purchasedCount for one-time credits, plus platform breakdown

Guidance derived from captured contract; illustrative_unexecuted

Unfiltered project-level request
curl -X GET "{{API_BASE_URL}}/v1/usage/" \
  -H "x-access-key: <token>"
Profile-scoped request with YYYY-MM range
curl -X GET "{{API_BASE_URL}}/v1/usage/?profileId=<profileId>&from=2026-01&to=2026-03" \
  -H "x-access-key: <token>"
Integration-scoped request
curl -X GET "{{API_BASE_URL}}/v1/usage/?integrationId=<integrationId>" \
  -H "x-access-key: <token>"
200 application/json response body
{
  "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
    }
  }
}
400 and 404 application/json response body
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
response#1responseobject__0
response#1response.successboolean__1Yes
response#1response.totalUsageinteger__2YesAll-time credits usedkind: schemaRange; value: 0 <= value
response#1response.usagearray<object>__3YesMonthly credit history, oldest first
response#1response.usage[]object__4
response#1response.usage[].yearinteger__5YesCalendar year
response#1response.usage[].monthinteger__6YesCalendar month (1–12)kind: schemaRange; value: 1 <= value <= 12
response#1response.usage[].countinteger__7YesSubscription (monthly plan) credits used this monthkind: schemaRange; value: 0 <= value
response#1response.usage[].purchasedCountinteger__8YesOne-time / credit-pack credits used this monthkind: schemaRange; value: 0 <= value
response#1response.usage[].platformobject__9YesCredits broken down by platform name
response#1response.usage[].platform.[key: string]integer__10Nokind: schemaRange; value: 0 <= value
response#1response.balanceobject__11NoCurrent credit balance. Only present on project-level requests (no profileId or integrationId filter).
response#1response.balance.monthlyobject__12Yes
response#1response.balance.monthly.limitinteger__13YesTotal monthly credits included in your plan
response#1response.balance.monthly.usedinteger__14YesMonthly credits used so far this billing cycle
response#1response.balance.monthly.remaininginteger__15YesMonthly credits still available this cycle
response#1response.balance.monthly.cycleStartstring__16YesStart of the current billing cyclekind: schemaFormat; value: date-time
response#1response.balance.monthly.cycleEndstring__17YesEnd of the current billing cycle — resets herekind: schemaFormat; value: date-time
response#1response.balance.purchasedobject__18Yes
response#1response.balance.purchased.totalinteger__19YesTotal one-time credits purchased (never expire)
response#1response.balance.purchased.usedinteger__20YesOne-time credits consumed so far
response#1response.balance.purchased.remaininginteger__21YesOne-time credits still available
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.messagestring__2Yes