Account API: usage, CSV export, wallet and keys
Everything the dashboard shows about usage and the wallet is readable over the API with the same 1xai-* key: the call log with each call's cost, one call by its id, a CSV export of a date range, daily roll-ups, the wallet and the keys. These routes are read-only and free, and they count toward that key's rate limit. A personal key and a company workspace key each read their own data only.
Last updated:
The endpoints
| Endpoint | Returns |
|---|---|
GET /v1/usage | Returns:The call log, newest first; with request_id=, one call |
GET /v1/usage/export | Returns:The calls of a date range as a CSV file |
GET /v1/usage/summary | Returns:A summary of a window: totals and a daily series, by model, vendor and key |
GET /v1/wallet/transactions | Returns:Wallet transactions: top-ups, charges, refunds |
GET /v1/wallet/summary | Returns:A wallet summary and the balance spendable right now |
GET /v1/keys | Returns:The keys |
GET /v1/keys/{id} | Returns:One key and its usage totals |
GET /v1/keys/current | Returns:The key the request was sent with |
GETonly. Any other method or path under/v1/usage,/v1/walletand/v1/keysanswers404with codepath_not_found, and never reaches a model vendor.- On the usage routes (
/v1/usage,/v1/usage/summaryand/v1/usage/export) and on/v1/wallet/transactions, afromorto(on the usage routes alsorequest_id) that cannot be read answers400with codeinvalid_request, andparamnames that parameter. Any other malformed parameter is ignored and its default applies. - Responses carry
Cache-Control: no-store. - What each kind of key reads is in the next section.
What each key reads
| Endpoint | A personal key | A company workspace key |
|---|---|---|
GET /v1/usage, /v1/usage/summary, /v1/usage/export | A personal key:The account's calls outside company workspaces | A company workspace key:The calls of its own workspace (every member's, from the API and from the chat product) |
GET /v1/keys, /v1/keys/{id}, /v1/keys/current | A personal key:The account's keys outside company workspaces | A company workspace key:The keys of its own workspace |
GET /v1/wallet/summary | A personal key:The whole summary | A company workspace key:Only scope and spendable_toman |
GET /v1/wallet/transactions | A personal key:The wallet ledger | A company workspace key:403 with code forbidden |
GET /v1/sla/credits | A personal key:The account's service credits | A company workspace key:403 with code forbidden |
- Through an API key, the logged request and response text (
request_bodyandresponse_body) is returned only for calls made with an API key. For what was written in the chat product both fields arenull. The dashboard shows each person their own text as before. - A company's wallet belongs to the whole company: a workspace key reads the spendable balance only, and the ledger is on the company dashboard.
- The calls a person made in a company workspace are read with that workspace's key or on the company dashboard, not with the person's personal key (teams and budgets).
- No key reads anything of another account or company.
The call log: GET /v1/usage
curl "https://1xai.ir/v1/usage?limit=50&status=ok&from=2026-11-01&to=2026-11-18" \ -H "Authorization: Bearer 1xai-..." # one call by its id (the X-Request-Id of its answer) curl "https://1xai.ir/v1/usage?request_id=gw_01JD3Z5T8Q0V6W4M2K9R7N1PXA" \ -H "Authorization: Bearer 1xai-..."
| Parameter | Meaning |
|---|---|
limit | Meaning:Rows to return; default 50, at most 500 |
offset | Meaning:Rows to skip, for paging |
from, to | Meaning:A time window: an RFC-3339 time with an offset (2026-11-01T00:00:00Z or 2026-11-01T08:30:00+03:30), or a plain date YYYY-MM-DD read as a Tehran day: as from its first instant, as to its last. So from=2026-06-01&to=2026-06-01 is exactly that Tehran day. Any other format answers 400. |
request_id | Meaning:An exact match on a call's id (the X-Request-Id of its answer); at most 128 characters of letters, digits and _ - . :. Returns the rows of that call (normally one) when this key may read it; another account's id, an unknown id or a vendor's id returns an empty list. It combines with the other filters. |
model | Meaning:The exact model id |
provider | Meaning:openai, anthropic, gemini, deepseek, xai, moonshot, zhipu, alibaba, minimax, tencent |
status | Meaning:ok for successful calls, error for failed ones |
key_id | Meaning:The id of one key |
q | Meaning:A search over the model, the route, the key's name, the call's id and the logged request and response text. A search that runs longer than 8 seconds stops with 503 and code usage_search_timeout: narrow the window with from and to, and use request_id to find one call. |
{
"usage": [
{
"created_at": "2026-11-18T08:12:45Z",
"model": "gpt-5.5",
"provider": "openai",
"endpoint": "/v1/chat/completions",
"prompt_tokens": 812,
"completion_tokens": 240,
"total_tokens": 1052,
"cached_tokens": 0,
"base_cost_usd": 0.004432,
"cost_toman": 1375,
"status_code": 200,
"request_id": "gw_01JD3Z5T8Q0V6W4M2K9R7N1PXA",
"request_body": "{…}",
"response_body": "{…}",
"request_body_truncated": false,
"response_body_truncated": false,
"key_name": "production",
"workspace": null
}
],
"total": 18234,
"filtered_total": 412
}cost_tomanis the full amount of that call, markup included;base_cost_usdis the vendor's list price in dollars, before the markup.cached_tokensis the part ofprompt_tokensthat was read from a cache.request_idis 1xAi's id of the call, theX-Request-Idof its answer (response metadata). It isnullonly for old rows that have none.request_bodyandresponse_bodyare the logged text of the call and becomenullafter 30 days (what is logged). Through an API key they are returned only for calls made with an API key.- On routes not billed by tokens,
total_tokensis that route's unit: seconds of audio for transcription, characters for speech, images for image generation. totalcounts every row this key may read,filtered_totalthe rows matching this filter. Withrequest_id, both are the number of rows returned.- A refund row has
endpoint: "refund"and a negative amount.
Usage summary: GET /v1/usage/summary
curl "https://1xai.ir/v1/usage/summary?days=30" \ -H "Authorization: Bearer 1xai-..."
days: how many past days; default 30, at most 365.fromandtotake precedence when sent, under the rule of/v1/usage. The filters of/v1/usagework here too, exceptrequest_id, which is ignored.- Totals:
total_calls,ok_calls,error_calls,total_tokens,prompt_tokens,completion_tokens,total_cost_toman,total_cost_usd,average_cost_toman. daily: one row per day (Tehran time) withday,calls,tokens,cost_tomanand each vendor's share.by_model,by_provider,by_keyandby_status: the same window by model, vendor, key and HTTP status.
CSV export: GET /v1/usage/export
curl -o usage.csv "https://1xai.ir/v1/usage/export?from=2026-11-01&to=2026-11-30" \ -H "Authorization: Bearer 1xai-..."
| Parameter | Meaning |
|---|---|
from | Meaning:The start, inclusive. An RFC-3339 time or a plain date (a Tehran day). Default: 31 days before to. |
to | Meaning:The end, inclusive. An RFC-3339 time or a plain date (the end of that Tehran day). Default: now. |
cursor | Meaning:Continues a truncated export: the second cell of the previous file's #truncated line, with the same from and to. |
- The span from
fromtotois at most 31 days. A longer span,fromafterto, an unreadable value or a badcursoranswers400with codeinvalid_requestandparam. A span is never shortened silently. - The answer is
200withContent-Type: text/csv; charset=utf-8,Content-Disposition: attachment; filename="1xai-usage-<from>-<to>.csv"(dates in Tehran time),Cache-Control: no-storeandX-1xai-Export-Row-Limit(the row limit of one file). - The file is UTF-8 with a byte order mark (BOM), so Excel shows Persian names correctly; lines end in CRLF and cells are quoted as RFC-4180 requires. Rows are newest first.
- A text cell that starts with
=,+,-,@, a tab or a carriage return (also after leading spaces) is written with a leading', so no spreadsheet reads it as a formula. - One file holds at most 100,000 rows. When more exist, the last line is
#truncated,<cursor>: ask again withcursor=<cursor>and the samefromandtofor the rest, with no row repeated or skipped. A file without that line is complete. - When an export fails after rows were written, or is still running after 10 minutes, the last line is
#error,<cursor>: the file is incomplete; continue from thatcursor. - One export at a time per account (per workspace for a company workspace key): a second one answers
429with codeexport_in_progressandRetry-After: 5. At most 6 exports a minute: beyond that,429with coderate_limitedandRetry-After. The key's own rate limit applies as on any route. - The file holds the rows
GET /v1/usageshows the same key, and never a request or response text. In the dashboard, the download-CSV button of the call log (a Persian screen) gives the same file for the chosen range.
| Column | Content |
|---|---|
time | Content:The time of the call in UTC, such as 2026-11-18T09:30:15.123Z |
request_id | Content:1xAi's id of the call (the X-Request-Id of its answer) |
key_name | Content:The key's name; __chat__ for the chat product's own calls, empty when the key was deleted |
model | Content:The model billed |
provider | Content:The model's vendor, as in the usage report |
endpoint | Content:The route, such as /v1/chat/completions |
status | Content:The HTTP status of the answer |
prompt_tokens | Content:As in the usage report |
completion_tokens | Content:As in the usage report |
cached_tokens | Content:As in the usage report |
total_tokens | Content:As in the usage report (on audio and image routes, that route's unit) |
base_cost_usd | Content:The vendor's list price of the call in USD, to eight decimal places |
markup_percent | Content:The markup applied, in percent |
toman_per_usd | Content:The dollar rate applied |
cost_toman | Content:What was billed, in Toman |
Wallet: GET /v1/wallet/summary and /v1/wallet/transactions
curl "https://1xai.ir/v1/wallet/summary?days=30" \ -H "Authorization: Bearer 1xai-..." curl "https://1xai.ir/v1/wallet/transactions?limit=20&kind=topup,refund" \ -H "Authorization: Bearer 1xai-..."
/v1/wallet/summary:balance_toman(the current balance),spendable_toman(what can be spent right now: the balance less the amount held for requests in flight, plus gift credit usable on any model), and the window's totals of top-ups, charges, refunds and net change, with a daily series.spendable_tomanis the figure the low-balance alert is compared against./v1/wallet/transactions:limit(default 50, at most 500),offset,from,toandkind(a list oftopup,charge,refund,adjustment,gift).fromandtoare read as on the usage routes: an RFC-3339 time with an offset, or a plain dateYYYY-MM-DDread as a Tehran day (asfromits first instant, astoits last); any other format answers400with codeinvalid_requestandparam.- Each transaction has
id,created_at,kind,amount_toman(charges are negative) andreference. Thereferenceof a charge is the call's id (X-Request-Id). - The part of a call paid from a plan's credit is not among the wallet's transactions; the full amount is the
cost_tomanof the usage row.
{
"scope": "workspace",
"spendable_toman": 4820000
}Keys: GET /v1/keys and /v1/keys/current
{
"keys": [
{
"id": 4821,
"prefix": "1xai-AbCdEfGh",
"name": "production",
"last_used_at": "2026-11-18T08:12:45Z",
"revoked_at": null,
"expires_at": null,
"cap_toman": 5000000,
"spent_toman": 1284350,
"created_at": "2026-10-02T11:30:00Z"
}
]
}- The key itself is never returned; only its prefix.
- Revoked and expired keys are listed too.
GET /v1/keys/{id}returns that key withstats:total_calls,ok_calls,total_tokens,total_cost_toman,first_used_at,last_used_atandmost_used_model.GET /v1/keys/currentreturns the key this very request was sent with:{"key":{…}}with the fields of one key ofGET /v1/keys, withoutstats. For a script that needs to know which key it runs with, what its spend cap is and how much of it is left.- Keys are created and revoked in the dashboard (API keys and security).
1xAi is an independent gateway. It is not affiliated with, endorsed by, or a reseller for OpenAI, Anthropic, Google, DeepSeek, xAI, Moonshot AI, Z.ai, Alibaba Qwen, MiniMax or Tencent Hunyuan. Requests are relayed upstream rather than answered by models of our own, so each provider's own usage policies apply to what their models will and will not do, and their model availability is theirs to change. Current reachability is published on the status page.