Read individual model requests for the account assigned to your key, including their outcomes, token usage, and costs. Requires usage:read; get a key in the console first if needed.
GET /open/v1/requestsRecords are returned newest first.
Request record parameters
All parameters are optional URL query parameters.
| Parameter | Type | Description |
|---|---|---|
limit |
integer | Records per page, from 1 to 100; defaults to 50 |
cursor |
string | The previous page’s nextCursor, passed back unchanged; omit for the first page |
startTime |
integer | Inclusive start time in Unix seconds; omitted means no lower bound |
endTime |
integer | Inclusive end time in Unix seconds; omitted means no upper bound |
model |
string | Exact model name |
keyName |
string | Exact name of the API key used for the model request |
outcome |
string | succeeded, interrupted, or failed |
requestId |
string | Request ID; substring matching is supported |
curl --fail-with-body --silent --show-error \
--connect-timeout 5 --max-time 15 --get \
https://api.xiu.ai/open/v1/requests \
-H "Authorization: Bearer $XIU_OPEN_API_KEY" \
--data-urlencode "startTime=1794355200" \
--data-urlencode "endTime=1794441599" \
--data-urlencode "limit=100"Request record fields
{
"items": [
{
"id": "18234",
"requestId": "20261111091502123456789abcdef",
"createdAt": 1794388502,
"model": "gpt-5",
"keyName": "production",
"outcome": "succeeded",
"stream": true,
"promptTokens": 1200,
"completionTokens": 350,
"cacheTokens": 1024,
"cacheCreationTokens": 0,
"cost": "0.004250",
"durationSeconds": 3,
"firstTokenMs": 850
}
],
"nextCursor": "18234",
"currency": "USD"
}| Field | Type | Description |
|---|---|---|
items |
array | This page’s request records, newest first |
nextCursor |
string or null | Cursor for the next page; null means there are no more pages |
currency |
string | Currency for all cost values, currently USD |
Each record in items contains:
| Field | Type | Description |
|---|---|---|
id |
string | Record ID for deduplication; store it as an opaque string, without arithmetic |
requestId |
string | Request ID to include when contacting support |
createdAt |
integer | Request time in Unix seconds |
model |
string | Requested model name |
keyName |
string | Name of the key used for the model request |
outcome |
string | Request outcome, as described below |
stream |
boolean | Whether the request used a streaming response |
promptTokens |
integer | Input tokens; 0 for failed requests |
completionTokens |
integer | Output tokens; 0 for failed requests |
cacheTokens |
integer | Input tokens read from cache; some models bill these at a cache rate |
cacheCreationTokens |
integer | Tokens written to cache; some models bill these separately |
cost |
string | Exact request cost with six decimal places |
durationSeconds |
integer | Total duration in seconds |
firstTokenMs |
integer or null | Time to first token in milliseconds; null when unavailable, such as non-streaming, failed, or older records |
outcome |
Meaning | Billing |
|---|---|---|
succeeded |
The request succeeded | Billed for actual usage |
interrupted |
The client disconnected during the request | Already billed for actual usage |
failed |
The request failed | Not billed |
Failed records do not include the upstream error text. Provide the requestId and request time when requesting help.
Pagination and incremental sync
Start without cursor, then pass each nextCursor back unchanged until it is null. Do not use page numbers or calculate cursor values. Keep time bounds and all filters unchanged while paging. If you change a filter, start again from the first page. New requests do not shift records into later pages.
For a scheduled sync, fix endTime for the run and update your sync checkpoint only after reading every page. On the next run, use the newest request time previously read as startTime and start from the first page again. Time bounds are inclusive, so deduplicate by id; when writing to a database, use id as a unique key for an upsert. Do not mark an interrupted run as complete.
See the Python synchronization example for cursor handling and retries. Use usage summaries to reconcile totals for the same time window and filters.