Log Query & Export

Use log and usage endpoints to audit request history, build internal reporting, and review usage.

Fetch logs

GET /api/log/self?start_timestamp=1711929600&end_timestamp=1713830400

Export usage

GET /api/log/self/export?start_timestamp=1711929600&end_timestamp=1713830400

Log query and export are dashboard management APIs and require a signed-in user session. Admins can use /api/log/ and /api/log/export for all logs.

Daily usage

Use the daily usage endpoint for internal reporting, financial reconciliation, or customer-facing billing pages. The endpoint aggregates successful consumption and refunds by day, and returns request counts, token usage, raw quota, and the server-side converted billing amount.

Endpoint

GET /api/usage/daily
Authorization: Bearer YOUR_BILLING_READ_TOKEN

Authentication

For external billing integrations, use a billing read-only token with the bill-... prefix. Users can generate or reset it from Console > Personal Settings > Security Settings. Each user has one billing read-only token; resetting it immediately invalidates the previous token.

Billing read-only tokens can only query billing data. They cannot call model endpoints such as /v1/models or /v1/chat/completions.

You can also use a regular API key to query daily usage for that API key only:

GET /api/usage/daily?start_timestamp=1711929600&end_timestamp=1713830400&timezone_offset=28800
Authorization: Bearer YOUR_API_KEY

Query user-level daily usage with a billing read-only token:

GET /api/usage/daily?scope=user&start_timestamp=1711929600&end_timestamp=1713830400&timezone_offset=28800
Authorization: Bearer YOUR_BILLING_READ_TOKEN

Query daily usage for one API key owned by the user:

GET /api/usage/daily?scope=token&token_id=28&start_timestamp=1711929600&end_timestamp=1713830400&timezone_offset=28800
Authorization: Bearer YOUR_BILLING_READ_TOKEN

Query Parameters

Parameter	Type	Required	Description
start_timestamp	integer	No	Start time as a Unix timestamp in seconds. Defaults to the last 30 days.
end_timestamp	integer	No	End time as a Unix timestamp in seconds. Defaults to now.
timezone_offset	integer	No	Timezone offset in seconds for day buckets, for example 28800 for UTC+8. Allowed range: -50400 to 50400.
scope	string	No	user or token. Billing read-only tokens default to user; API keys can only use token.
token_id	integer	No	Query one API key. Required when using a billing read-only token with scope=token, and the token must belong to the current user.
model_name	string	No	Filter by model, for example gpt-4o-mini.
group_by_model	boolean	No	Set to true to split rows by both date and model. Also accepts 1 and yes.

The maximum time range is 366 days.

Response Example

{
  "success": true,
  "message": "",
  "data": {
    "object": "daily_usage",
    "scope": "user",
    "user_id": 1,
    "token_id": 0,
    "start_timestamp": 1711929600,
    "end_timestamp": 1713830400,
    "timezone_offset": 28800,
    "billing_currency": "USD",
    "quota_per_unit": 500000,
    "data": [
      {
        "date": "2024-04-01",
        "start_timestamp": 1711900800,
        "end_timestamp": 1711987199,
        "request_count": 10,
        "prompt_tokens": 269,
        "completion_tokens": 11645,
        "token_used": 11914,
        "quota": 657472,
        "billing_amount": 1.314944,
        "billing_currency": "USD"
      }
    ]
  }
}

When group_by_model=true, each row also includes model_name:

{
  "date": "2024-04-01",
  "model_name": "gpt-4o-mini",
  "request_count": 10,
  "prompt_tokens": 269,
  "completion_tokens": 11645,
  "token_used": 11914,
  "quota": 657472,
  "billing_amount": 1.314944,
  "billing_currency": "USD"
}

Fields

Field	Description
success	Whether the request succeeded.
data.object	Always daily_usage.
data.scope	Actual query scope: user for the whole user, or token for one API key.
data.user_id	Current user ID.
data.token_id	API key ID when querying one key; 0 for user-level queries.
data.billing_currency	Current display currency or unit, for example USD, CNY, or TOKENS.
data.quota_per_unit	Conversion base between raw quota and a standard currency unit. For example, with 500000, 657472 quota = 1.314944 USD.
data.data	Daily usage rows.
date	Billing date, bucketed by timezone_offset.
request_count	Successful consumed request count. Refund rows do not increase this value.
prompt_tokens	Total input tokens.
completion_tokens	Total output tokens.
token_used	prompt_tokens + completion_tokens.
quota	Raw net platform usage. Consumption is positive; refunds are negative.
billing_amount	Converted billing amount or display unit according to the current server configuration.
billing_currency	Currency or display unit for the row.

Amount Conversion

quota is the raw internal value used for precise billing and reconciliation. For customer-facing display, use the returned billing_amount and billing_currency directly instead of reimplementing exchange rates on the client.

When the site uses the default USD display:

billing_amount = quota / quota_per_unit

For example, with quota_per_unit = 500000, 21301158 quota = 42.602316 USD.

If the site is configured to display CNY, a custom currency, or tokens, the endpoint returns the converted billing_amount and billing_currency based on the current server configuration.

Error Response

{
  "success": false,
  "message": "token invalid"
}

Common errors:

HTTP Status	Scenario
401	Missing token, invalid token, expired token, or a billing read-only token that has been reset.
403	The user is disabled.
500	Server or database error.

Invalid query parameters also return success=false, such as start_timestamp being greater than end_timestamp, a range longer than 366 days, or timezone_offset outside the allowed range.

Integration Notes

• Use a billing read-only token for external billing systems instead of a regular API key.
• Store the token as a secret. Do not expose it in frontend source code, logs, or public documentation.
• For monthly billing, pass explicit start_timestamp, end_timestamp, and timezone_offset values to avoid month-boundary drift.
• Use quota for exact reconciliation, and use billing_amount with billing_currency for user-facing display.