Credits

The following endpoints can be used to see your current credit balance with Topaz API and how your credits have been consumed over time. If you would like to add more credits to your account, please visit https://topazlabs.com/my-account/subscriptions/

Get Credit Balance

get

Allows you to view your current API credit balance.

Authorizations

X-API-KeystringRequired

Authentication via the Topaz generated key in the X-API-Key header.

Responses

200

Credit balance

application/json

available_creditsintegerOptional

The number of credits available to you.

Example: 100

reserved_creditsintegerOptional

The number of credits reserved by you (if applicable).

Example: 10

total_creditsintegerOptional

The total number of credits in your account (available credits + reserved credits).

Example: 110

get/credits/balance

GET /account/v1/credits/balance HTTP/1.1
Host: api.topazlabs.com
X-API-Key: YOUR_API_KEY
Accept: */*

200

Credit balance

{
  "available_credits": 100,
  "reserved_credits": 10,
  "total_credits": 110
}

Get Credit Usage

get

Returns time-bucketed API credit consumption for the account that owns the API key. This endpoint reports historical usage over time; for your current balance use GET /credits/balance instead.

Scope. Results are always scoped to the account that owns the key — there is no parameter to request another account's usage. For a pro-mode (pooled) key, usage is reported against the credit pool the key draws from, so every member of a pool sees the pool's consumption.

Time range. A time range is required: send either period, or both start_date and end_date. If you send both forms, the explicit date range wins. granularity is only honored with start_date/end_date; with period, 1d is always hourly and 7d / 30d are always daily.

Field	Type	Description
period	string | null	Echo of the period you sent; null if you did not send one.
granularity	string	Bucket width the usage entries represent.
start_date	string | null	Resolved start of the window. null when period=1d.
end_date	string | null	Resolved end of the window. null when period=1d.
group_by	string | null	Echo of the group_by you sent.
total_credits	number	Credits consumed over the whole window. May be fractional.
total_requests	number	Requests over the whole window.
usage	array	{period_start, credits} buckets in ascending time order.

period_start is the bucket's UTC start; there is no period_end, so derive the width from granularity. Summing usage[].credits should equal total_credits.

Grouping. With group_by, each bucket gains a groups array of {key, credits}. Groups that contributed nothing to a bucket are omitted, so the array length varies between buckets. Rows whose grouping field is empty are collected under the key "Unknown".

Caveats

• usage is sparse. Buckets with no activity are omitted rather than returned as zero, so consecutive entries are not necessarily one bucket apart.

• period=1d returns 48 hours, not 24. It is also the one form that leaves start_date and end_date as null in the response, so read the period_start values to learn which hours you received.

• week and 3day buckets are not calendar-aligned. They are fixed-width windows anchored to the first bucket that has data in the result, so the same date can land in a differently-labelled bucket depending on the range you request. month buckets snap to calendar-month starts; hour and day follow UTC boundaries.

• granularity and group_by are not validated. An unrecognized granularity is accepted, bucketed as if it were day, and echoed back verbatim. An unrecognized group_by puts every bucket under "Unknown". Stick to the documented values.

• No CORS headers. Browser JavaScript on another origin will be blocked regardless of the key. Call this endpoint server-side.

• Not cacheable. Responses are returned with Cache-Control: private, no-store.

• Errors carry only message. Unlike the Video API, errors from this endpoint do not include an errorCode field, so do not branch on one.

Authorizations

X-API-KeystringRequired

Authentication via the Topaz generated key in the X-API-Key header.

Query parameters

periodstring · enumOptional

Relative window ending now. 1d returns 48 hours, not 24 (see caveats).

Example: {"value":"7d"}Possible values:

start_datestring · dateOptional

Inclusive start of the window (UTC). Requires end_date.

Example: {"value":"2026-09-01"}

end_datestring · dateOptional

Inclusive end of the window (UTC). Must be on or after start_date.

Example: {"value":"2026-09-30"}

granularitystring · enumOptional

Bucket width. Ignored when period is used.

Default: dayPossible values:

modelsstring[]Optional

Restrict usage to the given model. Repeat the parameter to filter on several models.

Example: {"value":["gigapixel","proteus"]}

api_key_idstringOptional

Restrict usage to requests made with a single API key.

group_bystring · enumOptional

Adds a per-bucket groups breakdown by the given field.

Possible values:

Responses

200

Credit usage for the requested window

application/json

400

The request did not specify a usable time range, the date range was malformed or inverted, or the upstream usage service returned an unusable payload.

application/json

401

The X-API-Key header is missing or the key was rejected. Both cases produce the identical response, so a 401 does not tell you which of the two happened.

application/json

500

Unhandled server fault.

application/json

default

The upstream usage service failed. Its HTTP status (4xx or 5xx) is passed through unchanged.

application/json

get/credit-usage

GET /account/v1/credit-usage HTTP/1.1
Host: api.topazlabs.com
X-API-Key: YOUR_API_KEY
Accept: */*

{
  "period": "7d",
  "granularity": "day",
  "start_date": "2026-09-18",
  "end_date": "2026-09-24",
  "group_by": null,
  "total_credits": 1284.5,
  "total_requests": 96,
  "usage": [
    {
      "period_start": "2026-09-18T00:00:00.000Z",
      "credits": 412
    },
    {
      "period_start": "2026-09-19T00:00:00.000Z",
      "credits": 530.5
    },
    {
      "period_start": "2026-09-21T00:00:00.000Z",
      "credits": 342
    }
  ]
}