IN ENGLISH · API DOCS

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:

[01]ACCOUNT API

The endpoints

Account API endpoints
EndpointReturns
GET /v1/usageReturns:The call log, newest first; with request_id=, one call
GET /v1/usage/exportReturns:The calls of a date range as a CSV file
GET /v1/usage/summaryReturns:A summary of a window: totals and a daily series, by model, vendor and key
GET /v1/wallet/transactionsReturns:Wallet transactions: top-ups, charges, refunds
GET /v1/wallet/summaryReturns:A wallet summary and the balance spendable right now
GET /v1/keysReturns:The keys
GET /v1/keys/{id}Returns:One key and its usage totals
GET /v1/keys/currentReturns:The key the request was sent with
  • GET only. Any other method or path under /v1/usage, /v1/wallet and /v1/keys answers 404 with code path_not_found, and never reaches a model vendor.
  • On the usage routes (/v1/usage, /v1/usage/summary and /v1/usage/export) and on /v1/wallet/transactions, a from or to (on the usage routes also request_id) that cannot be read answers 400 with code invalid_request, and param names 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.
[02]ACCOUNT API

What each key reads

What a personal key and a company workspace key read
EndpointA personal keyA company workspace key
GET /v1/usage, /v1/usage/summary, /v1/usage/exportA personal key:The account's calls outside company workspacesA 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/currentA personal key:The account's keys outside company workspacesA company workspace key:The keys of its own workspace
GET /v1/wallet/summaryA personal key:The whole summaryA company workspace key:Only scope and spendable_toman
GET /v1/wallet/transactionsA personal key:The wallet ledgerA company workspace key:403 with code forbidden
GET /v1/sla/creditsA personal key:The account's service creditsA company workspace key:403 with code forbidden
  • Through an API key, the logged request and response text (request_body and response_body) is returned only for calls made with an API key. For what was written in the chat product both fields are null. 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.
[03]ACCOUNT API

The call log: GET /v1/usage

GET /v1/usagecurl
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-..."
Parameters of /v1/usage
ParameterMeaning
limitMeaning:Rows to return; default 50, at most 500
offsetMeaning:Rows to skip, for paging
from, toMeaning: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_idMeaning: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.
modelMeaning:The exact model id
providerMeaning:openai, anthropic, gemini, deepseek, xai, moonshot, zhipu, alibaba, minimax, tencent
statusMeaning:ok for successful calls, error for failed ones
key_idMeaning:The id of one key
qMeaning: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.
The responsejson
{
  "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_toman is the full amount of that call, markup included; base_cost_usd is the vendor's list price in dollars, before the markup.
  • cached_tokens is the part of prompt_tokens that was read from a cache.
  • request_id is 1xAi's id of the call, the X-Request-Id of its answer (response metadata). It is null only for old rows that have none.
  • request_body and response_body are the logged text of the call and become null after 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_tokens is that route's unit: seconds of audio for transcription, characters for speech, images for image generation.
  • total counts every row this key may read, filtered_total the rows matching this filter. With request_id, both are the number of rows returned.
  • A refund row has endpoint: "refund" and a negative amount.
[04]ACCOUNT API

Usage summary: GET /v1/usage/summary

GET /v1/usage/summarycurl
curl "https://1xai.ir/v1/usage/summary?days=30" \
  -H "Authorization: Bearer 1xai-..."
  • days: how many past days; default 30, at most 365. from and to take precedence when sent, under the rule of /v1/usage. The filters of /v1/usage work here too, except request_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) with day, calls, tokens, cost_toman and each vendor's share.
  • by_model, by_provider, by_key and by_status: the same window by model, vendor, key and HTTP status.
[05]ACCOUNT API

CSV export: GET /v1/usage/export

GET /v1/usage/exportcurl
curl -o usage.csv "https://1xai.ir/v1/usage/export?from=2026-11-01&to=2026-11-30" \
  -H "Authorization: Bearer 1xai-..."
Export parameters
ParameterMeaning
fromMeaning:The start, inclusive. An RFC-3339 time or a plain date (a Tehran day). Default: 31 days before to.
toMeaning:The end, inclusive. An RFC-3339 time or a plain date (the end of that Tehran day). Default: now.
cursorMeaning:Continues a truncated export: the second cell of the previous file's #truncated line, with the same from and to.
  • The span from from to to is at most 31 days. A longer span, from after to, an unreadable value or a bad cursor answers 400 with code invalid_request and param. A span is never shortened silently.
  • The answer is 200 with Content-Type: text/csv; charset=utf-8, Content-Disposition: attachment; filename="1xai-usage-<from>-<to>.csv" (dates in Tehran time), Cache-Control: no-store and X-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 with cursor=<cursor> and the same from and to for 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 that cursor.
  • One export at a time per account (per workspace for a company workspace key): a second one answers 429 with code export_in_progress and Retry-After: 5. At most 6 exports a minute: beyond that, 429 with code rate_limited and Retry-After. The key's own rate limit applies as on any route.
  • The file holds the rows GET /v1/usage shows 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.
The CSV columns, in order
ColumnContent
timeContent:The time of the call in UTC, such as 2026-11-18T09:30:15.123Z
request_idContent:1xAi's id of the call (the X-Request-Id of its answer)
key_nameContent:The key's name; __chat__ for the chat product's own calls, empty when the key was deleted
modelContent:The model billed
providerContent:The model's vendor, as in the usage report
endpointContent:The route, such as /v1/chat/completions
statusContent:The HTTP status of the answer
prompt_tokensContent:As in the usage report
completion_tokensContent:As in the usage report
cached_tokensContent:As in the usage report
total_tokensContent:As in the usage report (on audio and image routes, that route's unit)
base_cost_usdContent:The vendor's list price of the call in USD, to eight decimal places
markup_percentContent:The markup applied, in percent
toman_per_usdContent:The dollar rate applied
cost_tomanContent:What was billed, in Toman
[06]ACCOUNT API

Wallet: GET /v1/wallet/summary and /v1/wallet/transactions

curlcurl
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_toman is the figure the low-balance alert is compared against.
  • /v1/wallet/transactions: limit (default 50, at most 500), offset, from, to and kind (a list of topup, charge, refund, adjustment, gift). from and to are read as on the usage routes: an RFC-3339 time with an offset, or a plain date YYYY-MM-DD read as a Tehran day (as from its first instant, as to its last); any other format answers 400 with code invalid_request and param.
  • Each transaction has id, created_at, kind, amount_toman (charges are negative) and reference. The reference of 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_toman of the usage row.
`GET /v1/wallet/summary` with a company workspace keyjson
{
  "scope": "workspace",
  "spendable_toman": 4820000
}
[07]ACCOUNT API

Keys: GET /v1/keys and /v1/keys/current

The response of `GET /v1/keys`json
{
  "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 with stats: total_calls, ok_calls, total_tokens, total_cost_toman, first_used_at, last_used_at and most_used_model.
  • GET /v1/keys/current returns the key this very request was sent with: {"key":{…}} with the fields of one key of GET /v1/keys, without stats. 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.