Orders, account and usage
Everything about a request after it is sent, and the two objects that stand behind every request: your account and its usage.
List orders
curl "https://api.openfill.ai/v1/orders?status=queued,executing&include=usage" -H "Authorization: Bearer $OPENFILL_API_KEY"| Field | Type | Default | Meaning |
|---|---|---|---|
| status | list | none | Comma-separated statuses. An unknown one is 400. |
| model | string | none | One served model id. |
| kind | string | none | chat or completion. |
| batch | string | none | A batch id for its lines, or none for requests sent outside any batch. |
| id | string | none | A full id, or a prefix of at least four characters. |
| from, to | date | none | Inclusive bounds on created_at. |
| include | list | none | usage, totals, counts, storage, batch, pricing. The orders page says what each adds. |
| limit | integer | 100 | Up to 500. |
| cursor | string | none | next_cursor from the previous page. |
{"object": "list", "data": [ ...orders... ], "has_more": true, "next_cursor": "...", "total_orders": 123, "total_failed": 4, "total_charged_usd": 1.23, "total_at_bid_usd": 5.0, "total_saved_usd": 3.77, "counts": {"queued": 2, "executing": 1, "oldest_queued_at": "..."}}The total_* fields arrive with include=totals on the first page only and are null on later pages; counts arrives with include=counts on every page. Newest first, by cursor.
The order object
| Field | Meaning |
|---|---|
| id | The order id. |
| status | queued, executing, done, error, canceled or expired. |
| bid | What the order rests at: your max price, or the quote when locked. |
| kind | chat or completion. |
| model | The model it runs on. |
| created_at | Submission, ISO 8601. |
| admitted_at | When it was admitted to run. Null while queued, and reset if it went back to the book. |
| finished_at | When it reached a terminal status. |
| expires_at | When it leaves the book unexecuted: your timeout, or the lock window. |
| level_at_execution | The level at admission, then the level it was charged against. Null until admitted. |
| queue_position | Its place in the book, from 1, while queued. Null otherwise. |
| error | The terminal reason on error, canceled and expired. Null otherwise. |
With include=usage each order also carries usage: prompt_tokens, cached_tokens, output_tokens and charged_usd, or null for an order that never ran.
Get an order
curl https://api.openfill.ai/v1/orders/<order_id> -H "Authorization: Bearer $OPENFILL_API_KEY"One order object. include takes usage, storage, batch and pricing. An id that is malformed or belongs to someone else answers 404.
Get and delete a result
curl https://api.openfill.ai/v1/orders/<order_id>/result -H "Authorization: Bearer $OPENFILL_API_KEY"The stored response body of an order, or its state on the way there. Every answer carries id, status, created_at, expires_at and result_expires_at; the shapes per status are on the detached orders page. A body read counts against the hourly download allowance.
curl -X DELETE https://api.openfill.ai/v1/orders/<order_id>/result -H "Authorization: Bearer $OPENFILL_API_KEY"{"id": "<order_id>", "object": "order.result", "deleted": true}Idempotent. 409 result_write_pending while the body is still being written, and 409 batch_in_progress for a line of a running batch.
Reprice queued orders
curl https://api.openfill.ai/v1/orders/price -H "Authorization: Bearer $OPENFILL_API_KEY" -H "Content-Type: application/json" \ -d '{"ids": ["<order_id>"], "max_price": 0.05}'| Field | Type | Default | Meaning |
|---|---|---|---|
| ids | array | required | 1 to 500 order ids. Duplicates are folded. |
| max_price | number | required | The new limit, for every id. 0 is legal. |
{"object": "list", "max_price": 0.05, "changed": 1, "data": [{"id": "...", "changed": true, "reason": null}, {"id": "...", "changed": false, "reason": "price-locked, so its bid follows the quote and is not yours to set"}]}A repriced order rejoins the book at its new price behind the orders already resting there. 503 with Retry-After if the market did not confirm the change in time; the change still lands on the next tick.
Cancel an order
curl -X POST https://api.openfill.ai/v1/orders/<order_id>/cancel -H "Authorization: Bearer $OPENFILL_API_KEY"{"id": "<order_id>", "status": "canceled"}Queued orders only. 409 order_not_cancelable once it is executing or finished. Never charged.
Your account
curl https://api.openfill.ai/v1/account -H "Authorization: Bearer $OPENFILL_API_KEY"{"object": "account", "account_id": "...", "balance_usd": 12.34, "default_max_price": {"<model_id>": 0.10}, "price_lock": false, "order_timeout_seconds": 10, "storage": {"retention_days": 0, "log_payloads": false}, "orders": {"queued": 0, "executing": 0}}curl -X PATCH https://api.openfill.ai/v1/account -H "Authorization: Bearer $OPENFILL_API_KEY" -H "Content-Type: application/json" \ -d '{"default_max_price": {"<model_id>": 0.10}}'| Field | Type | Default | Meaning |
|---|---|---|---|
| default_max_price | object | none | Model id to max price. Merged: a number sets that model's default, null clears it, models not named are untouched. An unknown model is 400. |
| price_lock | boolean | none | The default for price_lock on every request. |
| order_timeout_seconds | integer | none | The default for max_wait, 10 seconds to 30 days. |
The response is the account as stored after the change. storage is read-only here and is changed in Settings, as are billing and API keys.
Usage
curl "https://api.openfill.ai/v1/usage?limit=50" -H "Authorization: Bearer $OPENFILL_API_KEY"| Field | Type | Default | Meaning |
|---|---|---|---|
| model | string | none | One served model id. |
| from, to | date | none | Inclusive bounds on the settlement time. |
| limit | integer | 50 | Up to 200. |
| cursor | string | none | next_cursor from the previous page. |
{"object": "list", "balance_usd": 12.34, "total_charged_usd": 1.23, "total_requests": 42, "has_more": false, "next_cursor": null, "data": [{"id": "...", "order_id": "...", "created_at": "...", "model": "...", "prompt_tokens": 12, "cached_tokens": 8, "output_tokens": 40, "level_at_execution": 0.0143, "charged_usd": 0.0000174}]}One record per settled order, newest first. The totals cover the whole filtered set and are null on pages after the first. The rows sum to the charges on your balance.