> For the complete documentation index, see [llms.txt](https://developer.topazlabs.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.topazlabs.com/reference/account/credits.md). # 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 ## Get Credit Balance > Allows you to view your current API credit balance.
```json {"openapi":"3.1.2","info":{"title":"Account API","version":"1.0.0"},"tags":[{"name":"Credits","description":"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/\n"}],"servers":[{"url":"https://api.topazlabs.com/account/v1","description":"Production Base URL"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Authentication via the Topaz generated key in the `X-API-Key` header.\n"}},"schemas":{"CreditBalanceResponse":{"type":"object","properties":{"available_credits":{"type":"integer","description":"The number of credits available to you."},"reserved_credits":{"type":"integer","description":"The number of credits reserved by you (if applicable)."},"total_credits":{"type":"integer","description":"The total number of credits in your account (available credits + reserved credits)."}}}}},"paths":{"/credits/balance":{"get":{"tags":["Credits"],"summary":"Get Credit Balance","operationId":"getCreditBalance","description":"Allows you to view your current API credit balance.\n","responses":{"200":{"description":"Credit balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditBalanceResponse"}}}}}}}}} ``` ## Get Credit Usage > 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\`]\(#tag/Credits/operation/getCreditBalance) 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.
```json {"openapi":"3.1.2","info":{"title":"Account API","version":"1.0.0"},"tags":[{"name":"Credits","description":"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/\n"}],"servers":[{"url":"https://api.topazlabs.com/account/v1","description":"Production Base URL"}],"security":[{"apiKeyAuth":[]}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Authentication via the Topaz generated key in the `X-API-Key` header.\n"}},"schemas":{"CreditUsageResponse":{"type":"object","required":["period","granularity","start_date","end_date","group_by","total_credits","total_requests","usage"],"properties":{"period":{"type":["string","null"],"description":"Echo of the `period` you sent; `null` if you did not send one."},"granularity":{"type":"string","description":"Bucket width the `usage` entries represent."},"start_date":{"type":["string","null"],"format":"date","description":"Resolved start of the window. `null` when `period=1d`."},"end_date":{"type":["string","null"],"format":"date","description":"Resolved end of the window. `null` when `period=1d`."},"group_by":{"type":["string","null"],"description":"Echo of the `group_by` you sent."},"total_credits":{"type":"number","description":"Credits consumed over the whole window. May be fractional."},"total_requests":{"type":"number","description":"Number of requests over the whole window."},"usage":{"type":"array","description":"Buckets in ascending time order.","items":{"$ref":"#/components/schemas/CreditUsageBucket"}}}},"CreditUsageBucket":{"type":"object","required":["period_start","credits"],"properties":{"period_start":{"type":"string","format":"date-time","description":"UTC start of the bucket."},"credits":{"type":"number","description":"Credits consumed in this bucket. May be fractional."},"groups":{"type":"array","description":"Per-group breakdown. Present only when `group_by` was sent.","items":{"$ref":"#/components/schemas/CreditUsageGroup"}}}},"CreditUsageGroup":{"type":"object","required":["key","credits"],"properties":{"key":{"type":"string","description":"Model name or API key id, depending on `group_by`."},"credits":{"type":"number","description":"Credits consumed by this group within the bucket. May be fractional."}}},"CreditUsageError":{"type":"object","required":["message"],"properties":{"message":{"type":"string","description":"Human-readable error message."}}}}},"paths":{"/credit-usage":{"get":{"tags":["Credits"],"summary":"Get Credit Usage","operationId":"getCreditUsage","description":"Returns time-bucketed API credit consumption for the account that owns the API key. This endpoint\nreports **historical usage over time**; for your current balance use\n[`GET /credits/balance`](#tag/Credits/operation/getCreditBalance) instead.\n\n**Scope.** Results are always scoped to the account that owns the key — there is no parameter to\nrequest another account's usage. For a pro-mode (pooled) key, usage is reported against the credit\npool the key draws from, so every member of a pool sees the pool's consumption.\n\n**Time range.** A time range is required: send either `period`, or both `start_date` and `end_date`.\nIf you send both forms, the explicit date range wins. `granularity` is only honored with\n`start_date`/`end_date`; with `period`, `1d` is always hourly and `7d` / `30d` are always daily.\n\n| Field | Type | Description |\n| ---------------- | -------------- | ----------------------------------------------------------------- |\n| `period` | string \\| null | Echo of the `period` you sent; `null` if you did not send one. |\n| `granularity` | string | Bucket width the `usage` entries represent. |\n| `start_date` | string \\| null | Resolved start of the window. `null` when `period=1d`. |\n| `end_date` | string \\| null | Resolved end of the window. `null` when `period=1d`. |\n| `group_by` | string \\| null | Echo of the `group_by` you sent. |\n| `total_credits` | number | Credits consumed over the whole window. May be fractional. |\n| `total_requests` | number | Requests over the whole window. |\n| `usage` | array | `{period_start, credits}` buckets in ascending time order. |\n\n`period_start` is the bucket's UTC start; there is no `period_end`, so derive the width from\n`granularity`. Summing `usage[].credits` should equal `total_credits`.\n\n**Grouping.** With `group_by`, each bucket gains a `groups` array of `{key, credits}`. Groups that\ncontributed nothing to a bucket are omitted, so the array length varies between buckets. Rows whose\ngrouping field is empty are collected under the key `\"Unknown\"`.\n\n**Caveats**\n\n- **`usage` is sparse.** Buckets with no activity are omitted rather than returned as zero, so\n consecutive entries are not necessarily one bucket apart.\n- **`period=1d` returns 48 hours**, not 24. It is also the one form that leaves `start_date` and\n `end_date` as `null` in the response, so read the `period_start` values to learn which hours you\n received.\n- **`week` and `3day` buckets are not calendar-aligned.** They are fixed-width windows anchored to the\n first bucket that has data in the result, so the same date can land in a differently-labelled bucket\n depending on the range you request. `month` buckets snap to calendar-month starts; `hour` and `day`\n follow UTC boundaries.\n- **`granularity` and `group_by` are not validated.** An unrecognized `granularity` is accepted,\n bucketed as if it were `day`, and echoed back verbatim. An unrecognized `group_by` puts every bucket\n under `\"Unknown\"`. Stick to the documented values.\n- **No CORS headers.** Browser JavaScript on another origin will be blocked regardless of the key. Call\n this endpoint server-side.\n- **Not cacheable.** Responses are returned with `Cache-Control: private, no-store`.\n- **Errors carry only `message`.** Unlike the Video API, errors from this endpoint do not include an\n `errorCode` field, so do not branch on one.\n","parameters":[{"name":"period","in":"query","required":false,"description":"Relative window ending now. `1d` returns 48 hours, not 24 (see caveats).","schema":{"type":"string","enum":["1d","7d","30d"]}},{"name":"start_date","in":"query","required":false,"description":"Inclusive start of the window (UTC). Requires `end_date`.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","required":false,"description":"Inclusive end of the window (UTC). Must be on or after `start_date`.","schema":{"type":"string","format":"date"}},{"name":"granularity","in":"query","required":false,"description":"Bucket width. Ignored when `period` is used.","schema":{"type":"string","enum":["hour","day","3day","week","month"],"default":"day"}},{"name":"models","in":"query","required":false,"description":"Restrict usage to the given model. Repeat the parameter to filter on several models.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}}},{"name":"api_key_id","in":"query","required":false,"description":"Restrict usage to requests made with a single API key.","schema":{"type":"string"}},{"name":"group_by","in":"query","required":false,"description":"Adds a per-bucket `groups` breakdown by the given field.","schema":{"type":"string","enum":["models","api_key_id"]}}],"responses":{"200":{"description":"Credit usage for the requested window","headers":{"Cache-Control":{"description":"Always `private, no-store`.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditUsageResponse"}}}},"400":{"description":"The request did not specify a usable time range, the date range was malformed or inverted, or the\nupstream usage service returned an unusable payload.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditUsageError"}}}},"401":{"description":"The `X-API-Key` header is missing or the key was rejected. Both cases produce the identical response,\nso a `401` does not tell you which of the two happened.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditUsageError"}}}},"500":{"description":"Unhandled server fault.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditUsageError"}}}},"default":{"description":"The upstream usage service failed. Its HTTP status (4xx or 5xx) is passed through unchanged.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreditUsageError"}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developer.topazlabs.com/reference/account/credits.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.