Sign-up and API keys are open. Paid top-ups open soon.What changed
thinQit Dex
NL
Docs menu

API reference, Account

Usage for one API key over a date range

View as Markdown

GET/v1/usageoperation id getUsage

Returns usage buckets for the calling key, or for another key of the same account when key_id is given. Dates are UTC; end is exclusive. Day granularity allows up to 93 days, hour granularity up to 7 days.

Authentication. API key as authorization: Bearer <key>, scope usage:read.

Parameters

startquery · stringrequired
First UTC date included.
  • format date
endquery · stringrequired
First UTC date not included.
  • format date
granularityquery · string
  • one of "day", "hour"
  • default "day"
key_idquery · KeyId
Another key of the same account. Defaults to the calling key.
  • pattern ^key_[0-9A-HJKMNP-TV-Z]{26}$
x-client-request-idheader · string
Your own correlation id, accepted on every public operation. Logged with the request metadata and echoed in the response. A malformed value answers 400 invalid_header.
  • 1 to 128 characters
  • pattern ^[\x21-\x7E]+$

Responses

200Usage buckets and totals.

Headers: x-request-id, x-client-request-id, ratelimit-policy, ratelimit

objectstringrequired
  • always "usage_report"
key_idKeyIdrequired
  • pattern ^key_[0-9A-HJKMNP-TV-Z]{26}$
startstringrequired
  • format date
endstringrequired
  • format date
granularitystringrequired
  • one of "day", "hour"
bucketsarray of UsageBucketrequired
buckets[].startstringrequired
  • format date-time
buckets[].endstringrequired
  • format date-time
buckets[].requestsintegerrequired
Successful (billed or test) decide calls.
buckets[].input_tokensintegerrequired
  • format int64
buckets[].charge_micro_centsintegerrequired
  • format int64
buckets[].gpu_requestsintegerrequired
buckets[].fallback_requestsintegerrequired
buckets[].error_requestsintegerrequired
Calls that ended in an error. Never charged.
totalsobjectrequired
totals.requestsintegerrequired
totals.input_tokensintegerrequired
  • format int64
totals.charge_micro_centsintegerrequired
  • format int64
400The request could not be read. Codes: invalid_json (not JSON, not UTF-8, or a \u escape that is half of a surrogate pair, such as "\ud800" without its low half), duplicate_key (a JSON object repeats a key; param is the JSON pointer of the repeated member, such as /questions/q1/options/a), unsupported_media_type (not application/json) and invalid_header (a malformed idempotency-key or x-client-request-id; param names the header).

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

401Missing, unknown, revoked or expired credentials.

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

403The credentials are valid but not allowed to do this (missing scope, suspended account or failed CSRF check).

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

404The model, key or route does not exist, or the model version is retired.

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

422The request is well-formed JSON but breaks a validation rule. param names the field as a dotted path. Codes: unknown_field, missing_field, invalid_type (wrong JSON type), invalid_value (right type, value out of range: an empty or over-long string, a state, instructions, criteria string or option description of only whitespace, an empty questions or options object, an empty state object or array, a pattern or allowed-value mismatch such as a label or level with outer whitespace, a state nested deeper than 32 levels, a bad date or date range), field_not_allowed (options or levels on the wrong question type), invalid_question_id, too_many_questions, too_many_options, invalid_levels (including two levels equal after Unicode NFC normalisation and lower-casing), invalid_min_confidence, duplicate_label (two option labels equal after Unicode NFC normalisation and lower-casing, such as Billing and billing), state_path_not_found, state_not_json and, on the console, top_up_limit_exceeded.

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

429A rate limit or quota is exhausted. Retry after the given number of seconds. For test_daily_quota that is the time until 00:00 UTC; clients should not retry it automatically.

Headers: x-request-id, x-client-request-id, retry-after, ratelimit-policy, ratelimit

Error envelope. See Errors for every type and code.

500An unexpected error. Any charge was refunded. Retry with the same idempotency key.

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

503No serving path could answer in time, or a dependency is down. Any charge was refunded.

Headers: x-request-id, x-client-request-id, retry-after

Error envelope. See Errors for every type and code.

Example request

curl "https://api.thinqit.ai/v1/usage?start=2026-10-19&end=2026-10-21&key_id=key_01M54VQCG06CQ643DZVMXXQKFB" \
  -H "authorization: Bearer $DEX_API_KEY"

Examples

Illustrative values. Examples show the shape of requests and responses; the numbers in them are not measured results.

Response: Two days of usage for one key

{
  "object": "usage_report",
  "key_id": "key_01M54VQCG06CQ643DZVMXXQKFB",
  "start": "2026-10-19",
  "end": "2026-10-21",
  "granularity": "day",
  "buckets": [
    {
      "start": "2026-10-19T00:00:00Z",
      "end": "2026-10-20T00:00:00Z",
      "requests": 18422,
      "input_tokens": 6120334,
      "charge_micro_cents": 30601670,
      "gpu_requests": 18390,
      "fallback_requests": 32,
      "error_requests": 41
    },
    {
      "start": "2026-10-20T00:00:00Z",
      "end": "2026-10-21T00:00:00Z",
      "requests": 20107,
      "input_tokens": 6874812,
      "charge_micro_cents": 34374060,
      "gpu_requests": 19650,
      "fallback_requests": 457,
      "error_requests": 12
    }
  ],
  "totals": {
    "requests": 38529,
    "input_tokens": 12995146,
    "charge_micro_cents": 64975730
  }
}