Quota and token usage
This resource reports what the project may still spend. Runs are metered in tokens, counted over a billing cycle, and the figures here are the exact ones the run endpoint checks before it accepts new work. Read it before launching a batch, and after a 402, to find out when the allowance resets.
Endpoints
| Method | Path | Scope |
|---|---|---|
| GET | /v1/run-usage/summary | usage:read |
The endpoint takes no parameters.
Read the summary
curl https://api.thinkhx.com/v1/run-usage/summary \
-H "Authorization: Bearer sk-project-YOUR_KEY"{
"code": 200,
"title": "OK",
"response": {
"object": "usage",
"plan": {
"id": "plan_0664fc57b92acb9124be",
"name": "Starter",
"priority": "low",
"model": "thinkhx-reason 8B",
"parallel": 1
},
"cycle": {
"start": 1752537600,
"end": 1755216000
},
"tokens": {
"bucket_included": 1000000,
"used": 148320,
"input": 141908,
"output": 6412,
"bucket_remaining": 851680,
"purchased_active": 0,
"purchased_remaining": 0,
"available": 851680
},
"runs": {
"total": 217,
"finished": 203,
"failed": 6,
"pending": 8
}
}
}The usage object
| Field | Type | Description |
|---|---|---|
object | string | Always usage. |
plan | object | The plan the project runs on. |
cycle | object | The billing cycle the token figures are measured over. |
tokens | object | Token allowance and consumption. |
runs | object | Lifetime run counts, by status. |
plan
| Field | Type | Description |
|---|---|---|
id | string | The plan identifier, prefixed plan_. |
name | string | The plan's name. |
priority | string | How the project's work is queued: low, medium or high. |
model | string | The best model the plan unlocks. |
parallel | integer | How many runs the project may have in flight at once. |
cycle
| Field | Type | Description |
|---|---|---|
start | integer | When the current cycle began, in Unix seconds. |
end | integer | When it resets, in Unix seconds. |
The cycle is a rolling month anchored to the date the plan was activated, so it does not usually align with a calendar month. end is when used returns to zero.
tokens
| Field | Type | Description |
|---|---|---|
bucket_included | integer | Tokens the plan includes per cycle. |
used | integer | Tokens consumed this cycle, input plus output. |
input | integer | The input half of used. |
output | integer | The output half of used. |
bucket_remaining | integer | What is left of the plan's own allowance, never below zero. |
purchased_active | integer | Tokens held in one-off packs currently valid. |
purchased_remaining | integer | What is left of those packs. |
available | integer | What the project may actually still spend. |
available is the figure that matters: it combines the plan allowance and any purchased credit, and it is what the run endpoint tests. When it reaches zero, POST /v1/run/create is refused with 402 and Your reasoning quota is exhausted. Please wait until it resets or upgrade your plan.
Tip — Compare
availableagainst your batch's expected size before you start, rather than discovering the limit halfway through. A run that is refused is never queued, so nothing is partially spent.
runs
| Field | Type | Description |
|---|---|---|
total | integer | Every run the project has ever launched. |
finished | integer | Runs that completed. |
failed | integer | Runs that ended in an error. |
pending | integer | Runs still queued or in flight. |
These four are lifetime totals for the project, not figures for the current cycle, and they count runs from every origin — the workspace as well as the API.
Note —
pendingis the count to watch againstplan.parallel. If it sits at the parallel limit, new runs are accepted but wait their turn.
For the project's other totals — team members, keys, files and events — see Project usage.