AI quota and token usage
This resource reports what your AI project may still spend. Runs are measured in tokens, counted over a billing cycle, and the figures here are the 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/ai/run-usage/summary | usage:read |
The endpoint takes no parameters.
Read the summary
curl https://api.ultineo.com/v1/ai/run-usage/summary \
-H "Authorization: Bearer sk-project-YOUR_KEY"{
"code": 200,
"title": "OK",
"response": {
"object": "usage",
"plan": {
"id": "plan_a1d9ffa770449a65ce8a",
"name": "essential",
"priority": "medium",
"model": "7 to 25B parameters",
"parallel": 2
},
"cycle": {
"start": 1788220800,
"end": 1790812800
},
"tokens": {
"bucket_included": 5000000,
"used": 148320,
"input": 141908,
"output": 6412,
"bucket_remaining": 4851680,
"purchased_active": 0,
"purchased_remaining": 0,
"available": 4851680
},
"runs": {
"total": 217,
"finished": 203,
"failed": 6,
"pending": 8
}
}
}The usage object
| Field | Type | Description |
|---|---|---|
object | string | Always usage. |
plan | object | The plan your project runs on. |
cycle | object | The billing cycle the token figures are measured over. |
tokens | object | Token allowance and consumption. |
runs | object | Run counts, by status. |
plan
| Field | Type | Description |
|---|---|---|
id | string | The plan identifier, prefixed plan_. |
name | string | The plan's name. |
priority | string | How your project's work is queued: low, medium or high. |
model | string | The model sizes the plan unlocks, such as 7 to 25B parameters. |
parallel | integer | How many runs your project may have in progress at once: 1 for low, 2 for medium, 5 for high. |
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 that starts on the date your plan was activated, so it does not usually match a calendar month. A project with no activation date runs on the calendar month. At end, 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 part of used. |
output | integer | The output part of used. |
bucket_remaining | integer | What is left of the plan's own allowance, never below zero. |
purchased_active | integer | Tokens held in extra credit that is currently valid. |
purchased_remaining | integer | What is left of that credit. |
available | integer | What your project may actually still spend. |
available is the figure that matters: it adds what is left of the plan allowance to any remaining extra credit, and it is what the run endpoint tests. When it reaches zero, POST /v1/ai/run/create is refused with 402 and Your reasoning quota is exhausted. Please wait until it resets or upgrade your plan.
Tip — Compare
availablewith the expected size of your batch before you start, rather than finding the limit halfway through. A refused run is never queued, so nothing is partly spent.
runs
| Field | Type | Description |
|---|---|---|
total | integer | Every run your project has ever launched. |
finished | integer | Runs that completed. |
failed | integer | Runs that ended in an error. |
pending | integer | Runs still queued or in progress. |
These four are totals over your project's whole life, not figures for the current cycle.
Note —
pendingis the count to watch againstplan.parallel. When it sits at the parallel limit, new runs are still accepted but wait their turn.