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.
Set shell variables such as ORDER_ID, FILE_ID and BATCH_ID to ids returned by the API before running the corresponding command.
List orders
curl "https://api.openfill.ai/v1/orders?status=queued,executing&include=usage,totals,counts" -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, completion, responses or messages. |
| 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. total_at_bid_usd and total_saved_usd cover the market orders in the set, and are null when it holds orders and none is a market order (a set with no orders answers 0); total_charged_usd covers every order.
The order object
| Field | Meaning |
|---|---|
| id | The order id. |
| status | queued, executing, done, error, canceled or expired. |
| bid | What the order rests at: your price limit, or the lower of the quote and your price limit when locked. On a fixed-price model, its prices at the reference mix, in the price limit's unit. |
| kind | chat, completion, responses or messages: the endpoint the request came in on. |
| 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 price it was charged at: the level at dispatch, or the bid where that was lower. On a fixed-price model, the same figure as bid. Null until admitted. |
| queue_position | Its place in the book, from 1, while queued on a market model. Null otherwise, and always null on a fixed-price model, where accounts take turns. |
| 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 when no usage record exists. Charges include refunds; a settlement failure needs the error message and usage record checked together.
With include=pricing each order carries price_lock and pricing, market or fixed. An order on a fixed-price model also carries usd_per_million: the three prices it was submitted at, per 1M tokens of cache-hit input, cache-miss input and output, which stay on the order after the model's prices change.
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 successful response carries id, status, created_at, expires_at and result_expires_at; the shapes per status are on the detached orders page. The body is rendered in the shape of the endpoint the request came in on; for a Responses or Messages order the fields that echo the request carry their defaults, since the request itself is gone by then. 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"'"], "price_limit": 0.05}'| Field | Type | Default | Meaning |
|---|---|---|---|
| ids | array | required | 1 to 500 order ids. Duplicates are folded. |
| price_limit | number | required | The new price limit, for every id. See the shared price bound below. |
{"object": "list", "price_limit": 0.05, "changed": 1, "data": [{"id": "...", "changed": true, "code": null, "reason": null}]}The new price_limit accepts 0 to 1000000000. A repriced order rejoins the book at its new price behind the orders already resting there. An item that changed carries a code of null. One that did not carries a reason and a code: not_queued, price_locked, too_large, fixed_price_model for an order on a fixed-price model, which is charged its published prices, or unavailable when the market could not apply the change just now, with the order still queued, so a retry can apply it. 503 with Retry-After if the market did not confirm the change in time: the request is still queued and the next tick applies it with whatever result it has by then, so read the order back rather than resending.
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_price_limit": {"market-preview": 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_price_limit": {"market-preview": 0.10}}'| Field | Type | Default | Meaning |
|---|---|---|---|
| default_price_limit | object | none | Model id to price limit. Merged: a number sets that model's default, null clears it, models not named are untouched. An unknown model is 400. A number for a fixed-price model is 400 fixed_price_model; null clears a value stored for one. The response lists market models only. |
| price_lock | boolean | none | The default for price_lock on every interactive request to a market model; on only for a caller who needs the price known before sending. Batch lines never lock. |
| 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; unknown PATCH fields are refused with 400. Storage 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": 0.000005272, "total_requests": 1, "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.000005272, "pricing": "market"}]}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. Each row carries pricing, market or fixed.