History and spending

Methods, request fields, and responses.

Full guide

This section contains 11 methods. Open a method to view access requirements, request fields, and the response.

Method and path	Description	Access
`GET /api/v1/usage`	Request history	Dashboard token
`GET /api/v1/usage/:id`	One request from your history	Dashboard token
`POST /api/v1/usage/dashboard/api-keys-usage`	Usage statistics for your API keys	Dashboard token
`GET /api/v1/usage/dashboard/models`	Usage by model	Dashboard token
`GET /api/v1/usage/dashboard/snapshot-v2`	Combined chart snapshot	Dashboard token
`GET /api/v1/usage/dashboard/stats`	Usage totals	Dashboard token
`GET /api/v1/usage/dashboard/trend`	Usage trends	Dashboard token
`GET /api/v1/usage/errors`	Error history	Dashboard token
`GET /api/v1/usage/errors/:id`	Details of your own error	Dashboard token
`GET /api/v1/usage/stats`	Usage statistics	Dashboard token
`GET /api/v1/user/api-keys/:id/usage/daily`	Daily usage for your API key	Dashboard token

GET /api/v1/usage — Request history

Access: Dashboard token

GET/api/v1/usage

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/usage" \
  -H "Authorization: Bearer $TOKEN"

Query parameters

The field	Type	Required	Validation / description
`sort_by`	`string`	no	; default: created_at
`sort_order`	`string`	no	; default: desc
`api_key_id`	`integer`	no
`request_type`	`string`	no
`stream`	`boolean`	no
`timezone`	`string`	no
`start_date`	`string`	no
`end_date`	`string`	no
`period`	`string`	no
`model`	`string`	no
`page`	`integer`	no	; default: 1; positive; page_size/limit <=1000
`page_size`	`integer`	no	; default: 20; positive; page_size/limit <=1000
`limit`	`integer`	no	; default: 20; positive; page_size/limit <=1000

No request body is required. Send the parameters listed above in the URL.

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response data schemas: UsageLog. See the Data schemas pages for fields and types.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "user_id": "PLACEHOLDER_USER_ID (integer)",
        "api_key_id": "PLACEHOLDER_API_KEY_ID (integer)",
        "request_id": "PLACEHOLDER_REQUEST_ID (string)",
        "model": "PLACEHOLDER_MODEL (string)",
        "service_tier": "PLACEHOLDER_SERVICE_TIER (string)",
        "reasoning_effort": "PLACEHOLDER_REASONING_EFFORT (string)",
        "input_tokens": "PLACEHOLDER_INPUT_TOKENS (integer)",
        "output_tokens": "PLACEHOLDER_OUTPUT_TOKENS (integer)",
        "cache_creation_tokens": "PLACEHOLDER_CACHE_CREATION_TOKENS (integer)",
        "cache_read_tokens": "PLACEHOLDER_CACHE_READ_TOKENS (integer)",
        "cache_creation_5m_tokens": "PLACEHOLDER_CACHE_CREATION_5M_TOKENS (integer)",
        "cache_creation_1h_tokens": "PLACEHOLDER_CACHE_CREATION_1H_TOKENS (integer)",
        "input_cost": "PLACEHOLDER_INPUT_COST (number)",
        "output_cost": "PLACEHOLDER_OUTPUT_COST (number)",
        "cache_creation_cost": "PLACEHOLDER_CACHE_CREATION_COST (number)",
        "cache_read_cost": "PLACEHOLDER_CACHE_READ_COST (number)",
        "total_cost": "PLACEHOLDER_TOTAL_COST (number)",
        "actual_cost": "PLACEHOLDER_ACTUAL_COST (number)",
        "long_context_billing_applied": "PLACEHOLDER_LONG_CONTEXT_BILLING_APPLIED (boolean)",
        "request_type": "PLACEHOLDER_REQUEST_TYPE (string)",
        "stream": "PLACEHOLDER_STREAM (boolean)",
        "duration_ms": "PLACEHOLDER_DURATION_MS (integer)",
        "first_token_ms": "PLACEHOLDER_FIRST_TOKEN_MS (integer)",
        "image_count": "PLACEHOLDER_IMAGE_COUNT (integer)",
        "image_size": "PLACEHOLDER_IMAGE_SIZE (string)",
        "image_input_size": "PLACEHOLDER_IMAGE_INPUT_SIZE (string)",
        "image_output_size": "PLACEHOLDER_IMAGE_OUTPUT_SIZE (string)",
        "image_input_tokens": "PLACEHOLDER_IMAGE_INPUT_TOKENS (integer)",
        "image_input_cost": "PLACEHOLDER_IMAGE_INPUT_COST (number)",
        "image_output_tokens": "PLACEHOLDER_IMAGE_OUTPUT_TOKENS (integer)",
        "image_output_cost": "PLACEHOLDER_IMAGE_OUTPUT_COST (number)",
        "image_size_breakdown": "PLACEHOLDER_IMAGE_SIZE_BREAKDOWN (object)",
        "media_type": "PLACEHOLDER_MEDIA_TYPE (string)",
        "ip_address": "PLACEHOLDER_IP_ADDRESS (string)",
        "session_id": "PLACEHOLDER_SESSION_ID (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "user": "PLACEHOLDER_USER (object)",
        "api_key": "PLACEHOLDER_API_KEY (object)"
      }
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}

Note: all personal data and objects are scoped to the JWT subject.

GET /api/v1/usage/:id — One request from your history

Access: Dashboard token

GET/api/v1/usage/:id

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/usage/$ID" \
  -H "Authorization: Bearer $TOKEN"

Path parameters

The field	Type	Required	Validation / description
`id`	`integer`	yes

No request body is required. Send the parameters listed above in the URL.

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response data schemas: UsageLog. See the Data schemas pages for fields and types.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "api_key_id": "PLACEHOLDER_API_KEY_ID (integer)",
    "request_id": "PLACEHOLDER_REQUEST_ID (string)",
    "model": "PLACEHOLDER_MODEL (string)",
    "service_tier": "PLACEHOLDER_SERVICE_TIER (string)",
    "reasoning_effort": "PLACEHOLDER_REASONING_EFFORT (string)",
    "input_tokens": "PLACEHOLDER_INPUT_TOKENS (integer)",
    "output_tokens": "PLACEHOLDER_OUTPUT_TOKENS (integer)",
    "cache_creation_tokens": "PLACEHOLDER_CACHE_CREATION_TOKENS (integer)",
    "cache_read_tokens": "PLACEHOLDER_CACHE_READ_TOKENS (integer)",
    "cache_creation_5m_tokens": "PLACEHOLDER_CACHE_CREATION_5M_TOKENS (integer)",
    "cache_creation_1h_tokens": "PLACEHOLDER_CACHE_CREATION_1H_TOKENS (integer)",
    "input_cost": "PLACEHOLDER_INPUT_COST (number)",
    "output_cost": "PLACEHOLDER_OUTPUT_COST (number)",
    "cache_creation_cost": "PLACEHOLDER_CACHE_CREATION_COST (number)",
    "cache_read_cost": "PLACEHOLDER_CACHE_READ_COST (number)",
    "total_cost": "PLACEHOLDER_TOTAL_COST (number)",
    "actual_cost": "PLACEHOLDER_ACTUAL_COST (number)",
    "long_context_billing_applied": "PLACEHOLDER_LONG_CONTEXT_BILLING_APPLIED (boolean)",
    "request_type": "PLACEHOLDER_REQUEST_TYPE (string)",
    "stream": "PLACEHOLDER_STREAM (boolean)",
    "duration_ms": "PLACEHOLDER_DURATION_MS (integer)",
    "first_token_ms": "PLACEHOLDER_FIRST_TOKEN_MS (integer)",
    "image_count": "PLACEHOLDER_IMAGE_COUNT (integer)",
    "image_size": "PLACEHOLDER_IMAGE_SIZE (string)",
    "image_input_size": "PLACEHOLDER_IMAGE_INPUT_SIZE (string)",
    "image_output_size": "PLACEHOLDER_IMAGE_OUTPUT_SIZE (string)",
    "image_input_tokens": "PLACEHOLDER_IMAGE_INPUT_TOKENS (integer)",
    "image_input_cost": "PLACEHOLDER_IMAGE_INPUT_COST (number)",
    "image_output_tokens": "PLACEHOLDER_IMAGE_OUTPUT_TOKENS (integer)",
    "image_output_cost": "PLACEHOLDER_IMAGE_OUTPUT_COST (number)",
    "image_size_breakdown": "PLACEHOLDER_IMAGE_SIZE_BREAKDOWN (object)",
    "media_type": "PLACEHOLDER_MEDIA_TYPE (string)",
    "ip_address": "PLACEHOLDER_IP_ADDRESS (string)",
    "session_id": "PLACEHOLDER_SESSION_ID (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "user": "PLACEHOLDER_USER (object)",
    "api_key": "PLACEHOLDER_API_KEY (object)"
  }
}

Note: all personal data and objects are scoped to the JWT subject.

POST /api/v1/usage/dashboard/api-keys-usage — Usage statistics for your API keys

Access: Dashboard token

POST/api/v1/usage/dashboard/api-keys-usage

JSON / form fields

The field	Type	Required	Validation / description
`api_key_ids`	`array`	yes	required

Request body template

{
  "api_key_ids": "PLACEHOLDER_API_KEY_IDS (array)"
}

PLACEHOLDER represents your input and its type. Replace the values and keep only the optional fields you need. Do not send string placeholders in place of numbers, booleans, objects, or arrays.

Request schema: BatchAPIKeysUsageRequest

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response data schemas: BatchAPIKeyUsageStats. See the Data schemas pages for fields and types.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "api_key_id": "PLACEHOLDER_API_KEY_ID (integer)",
    "today_actual_cost": "PLACEHOLDER_TODAY_ACTUAL_COST (number)",
    "total_actual_cost": "PLACEHOLDER_TOTAL_ACTUAL_COST (number)"
  }
}

Note: all personal data and objects are scoped to the JWT subject.

Notes: This method reads statistics for your own API keys; the example describes the contract and is not executed.

GET /api/v1/usage/dashboard/models — Usage by model

Access: Dashboard token

GET/api/v1/usage/dashboard/models

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/models" \
  -H "Authorization: Bearer $TOKEN"

Query parameters

The field	Type	Required
`api_key_id`	`integer`	no
`request_type`	`string`	no
`stream`	`boolean`	no
`timezone`	`string`	no
`start_date`	`string`	no
`end_date`	`string`	no
`period`	`string`	no
`model`	`string`	no

No request body is required. Send the parameters listed above in the URL.

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "end_date": "VALUE_FROM_RESPONSE",
    "models": "VALUE_FROM_RESPONSE",
    "month": "VALUE_FROM_RESPONSE",
    "start_date": "VALUE_FROM_RESPONSE",
    "today": "VALUE_FROM_RESPONSE",
    "week": "VALUE_FROM_RESPONSE"
  }
}

Note: all personal data and objects are scoped to the JWT subject.

GET /api/v1/usage/dashboard/snapshot-v2 — Combined chart snapshot

Access: Dashboard token

GET/api/v1/usage/dashboard/snapshot-v2

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/snapshot-v2" \
  -H "Authorization: Bearer $TOKEN"

Query parameters

The field	Type	Required	Validation / description
`granularity`	`string`	no	; default: day
`include_trend`	`boolean`	no	; default: true
`include_model_stats`	`boolean`	no	; default: true
`api_key_id`	`integer`	no
`request_type`	`string`	no
`stream`	`boolean`	no
`timezone`	`string`	no
`start_date`	`string`	no
`end_date`	`string`	no
`period`	`string`	no
`model`	`string`	no

No request body is required. Send the parameters listed above in the URL.

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "end_date": "VALUE_FROM_RESPONSE",
    "generated_at": "VALUE_FROM_RESPONSE",
    "granularity": "VALUE_FROM_RESPONSE",
    "month": "VALUE_FROM_RESPONSE",
    "start_date": "VALUE_FROM_RESPONSE",
    "today": "VALUE_FROM_RESPONSE",
    "week": "VALUE_FROM_RESPONSE"
  }
}

Note: all personal data and objects are scoped to the JWT subject.

GET /api/v1/usage/dashboard/stats — Usage totals

Access: Dashboard token

GET/api/v1/usage/dashboard/stats

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/stats" \
  -H "Authorization: Bearer $TOKEN"

No request body is required. Send the parameters listed above in the URL.

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response data schemas: UserDashboardStats. See the Data schemas pages for fields and types.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "total_api_keys": "PLACEHOLDER_TOTAL_API_KEYS (integer)",
    "active_api_keys": "PLACEHOLDER_ACTIVE_API_KEYS (integer)",
    "total_requests": "PLACEHOLDER_TOTAL_REQUESTS (integer)",
    "total_input_tokens": "PLACEHOLDER_TOTAL_INPUT_TOKENS (integer)",
    "total_output_tokens": "PLACEHOLDER_TOTAL_OUTPUT_TOKENS (integer)",
    "total_cache_creation_tokens": "PLACEHOLDER_TOTAL_CACHE_CREATION_TOKENS (integer)",
    "total_cache_read_tokens": "PLACEHOLDER_TOTAL_CACHE_READ_TOKENS (integer)",
    "total_tokens": "PLACEHOLDER_TOTAL_TOKENS (integer)",
    "total_cost": "PLACEHOLDER_TOTAL_COST (number)",
    "total_actual_cost": "PLACEHOLDER_TOTAL_ACTUAL_COST (number)",
    "today_requests": "PLACEHOLDER_TODAY_REQUESTS (integer)",
    "today_input_tokens": "PLACEHOLDER_TODAY_INPUT_TOKENS (integer)",
    "today_output_tokens": "PLACEHOLDER_TODAY_OUTPUT_TOKENS (integer)",
    "today_cache_creation_tokens": "PLACEHOLDER_TODAY_CACHE_CREATION_TOKENS (integer)",
    "today_cache_read_tokens": "PLACEHOLDER_TODAY_CACHE_READ_TOKENS (integer)",
    "today_tokens": "PLACEHOLDER_TODAY_TOKENS (integer)",
    "today_cost": "PLACEHOLDER_TODAY_COST (number)",
    "today_actual_cost": "PLACEHOLDER_TODAY_ACTUAL_COST (number)",
    "average_duration_ms": "PLACEHOLDER_AVERAGE_DURATION_MS (number)",
    "rpm": "PLACEHOLDER_RPM (integer)",
    "tpm": "PLACEHOLDER_TPM (integer)"
  }
}

Note: all personal data and objects are scoped to the JWT subject.

GET /api/v1/usage/dashboard/trend — Usage trends

Access: Dashboard token

GET/api/v1/usage/dashboard/trend

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/usage/dashboard/trend" \
  -H "Authorization: Bearer $TOKEN"

Query parameters

The field	Type	Required	Validation / description
`granularity`	`string`	no	; default: day
`api_key_id`	`integer`	no
`request_type`	`string`	no
`stream`	`boolean`	no
`timezone`	`string`	no
`start_date`	`string`	no
`end_date`	`string`	no
`period`	`string`	no
`model`	`string`	no

No request body is required. Send the parameters listed above in the URL.

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "end_date": "VALUE_FROM_RESPONSE",
    "granularity": "VALUE_FROM_RESPONSE",
    "month": "VALUE_FROM_RESPONSE",
    "start_date": "VALUE_FROM_RESPONSE",
    "today": "VALUE_FROM_RESPONSE",
    "trend": "VALUE_FROM_RESPONSE",
    "week": "VALUE_FROM_RESPONSE"
  }
}

Note: all personal data and objects are scoped to the JWT subject.

GET /api/v1/usage/errors — Error history

Access: Dashboard token

GET/api/v1/usage/errors

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/usage/errors" \
  -H "Authorization: Bearer $TOKEN"

Query parameters

The field	Type	Required	Validation / description
`timezone`	`string`	no
`start_date`	`string`	no
`end_date`	`string`	no
`model`	`string`	no
`api_key_id`	`integer`	no
`status_code`	`integer`	no
`category`	`string`	no
`sort_by`	`string`	no
`sort_order`	`string`	no
`page`	`integer`	no	; default: 1; positive; page_size/limit <=1000
`page_size`	`integer`	no	; default: 20; positive; page_size/limit <=1000
`limit`	`integer`	no	; default: 20; positive; page_size/limit <=1000

No request body is required. Send the parameters listed above in the URL.

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      "PLACEHOLDER_DATA (object, description on the «Data Schemas» page)"
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}

Note: all personal data and objects are scoped to the JWT subject.

GET /api/v1/usage/errors/:id — Details of your own error

Access: Dashboard token

GET/api/v1/usage/errors/:id

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/usage/errors/$ID" \
  -H "Authorization: Bearer $TOKEN"

Path parameters

The field	Type	Required	Validation / description
`id`	`integer`	yes

No request body is required. Send the parameters listed above in the URL.

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": "PLACEHOLDER_DATA (object, description on the «Data Schemas» page)"
}

Note: all personal data and objects are scoped to the JWT subject.

GET /api/v1/usage/stats — Usage statistics

Access: Dashboard token

GET/api/v1/usage/stats

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/usage/stats" \
  -H "Authorization: Bearer $TOKEN"

Query parameters

The field	Type	Required
`api_key_id`	`integer`	no
`request_type`	`string`	no
`stream`	`boolean`	no
`timezone`	`string`	no
`start_date`	`string`	no
`end_date`	`string`	no
`period`	`string`	no
`model`	`string`	no

No request body is required. Send the parameters listed above in the URL.

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response data schemas: UsageStats. See the Data schemas pages for fields and types.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "total_requests": "PLACEHOLDER_TOTAL_REQUESTS (integer)",
    "total_input_tokens": "PLACEHOLDER_TOTAL_INPUT_TOKENS (integer)",
    "total_output_tokens": "PLACEHOLDER_TOTAL_OUTPUT_TOKENS (integer)",
    "total_cache_tokens": "PLACEHOLDER_TOTAL_CACHE_TOKENS (integer)",
    "total_cache_creation_tokens": "PLACEHOLDER_TOTAL_CACHE_CREATION_TOKENS (integer)",
    "total_cache_read_tokens": "PLACEHOLDER_TOTAL_CACHE_READ_TOKENS (integer)",
    "total_tokens": "PLACEHOLDER_TOTAL_TOKENS (integer)",
    "total_cost": "PLACEHOLDER_TOTAL_COST (number)",
    "total_actual_cost": "PLACEHOLDER_TOTAL_ACTUAL_COST (number)",
    "average_duration_ms": "PLACEHOLDER_AVERAGE_DURATION_MS (number)",
    "endpoints": "PLACEHOLDER_ENDPOINTS (array)"
  }
}

Note: all personal data and objects are scoped to the JWT subject.

GET /api/v1/user/api-keys/:id/usage/daily — Daily usage for your API key

Access: Dashboard token

GET/api/v1/user/api-keys/:id/usage/daily

Read operation; use an ID from your previous response

curl --fail-with-body "https://ailoot.ai/api/v1/user/api-keys/$ID/usage/daily" \
  -H "Authorization: Bearer $TOKEN"

Path parameters

The field	Type	Required	Validation / description
`id`	`integer`	yes

Query parameters

The field	Type	Required	Validation / description
`days`	`integer`	no	; default: 30
`timezone`	`string`	no

No request body is required. Send the parameters listed above in the URL.

Response

The JSON response contains code, message, and data. The data contents are described in the schemas below.

Response data schemas: APIKeyDailyUsagePoint. See the Data schemas pages for fields and types.

Response schema with illustrative values

{
  "code": 0,
  "message": "success",
  "data": {
    "date": "PLACEHOLDER_DATE (string)",
    "requests": "PLACEHOLDER_REQUESTS (integer)",
    "input_tokens": "PLACEHOLDER_INPUT_TOKENS (integer)",
    "output_tokens": "PLACEHOLDER_OUTPUT_TOKENS (integer)",
    "cache_read_tokens": "PLACEHOLDER_CACHE_READ_TOKENS (integer)",
    "cache_write_tokens": "PLACEHOLDER_CACHE_WRITE_TOKENS (integer)",
    "total_tokens": "PLACEHOLDER_TOTAL_TOKENS (integer)",
    "cost": "PLACEHOLDER_COST (number)",
    "actual_cost": "PLACEHOLDER_ACTUAL_COST (number)"
  }
}

Note: all personal data and objects are scoped to the JWT subject.

History and spending · USD

total_cost is the calculated tariff cost; actual_cost is the recorded charge, in USD.

Calculation example

{
  "total_cost": 0.1,
  "actual_cost": 0.08
}

period ∈ {today, week, month}; start_date, end_date: YYYY-MM-DD; timezone: IANA · timezone=UTC. end_date: [00:00, +1 day 00:00). display: actual_cost.toFixed(8); JSON: number.

Still have questions? Send your Request ID and a description — we'll help you troubleshoot.Contact support