Generation Usage Logs

Query generation usage records associated with the current API Key.

GET/api/v1/generations/logs

Field	Value
Base URL	https://api.gate.ai
Auth	Authorization: Bearer <API_KEY>
Format	Gate.AI REST JSON
Rate limit	1 request per second per API Key

Query all records for a specific trace_id, or retrieve the 100 most recent records for the current API Key.

Query by Trace: Include a valid trace_id to return all exact matches owned by the current API Key, ordered by id DESC .
Query recent records: Omit the request body, send an empty body, or send {} to return the 100 most recent records for the current API Key, ordered by created_at DESC, id DESC .
If the Trace does not exist, its logs have not been generated, or it does not belong to the current API Key, the API returns HTTP 200 with an empty array.

Request Parameters

Name	In	Type	Required	Description
Authorization	header	string	Yes	API Key authentication in the format: Bearer <API_KEY>
Content-Type	header	string	Yes	Must be application/json

Request Body

Name	Type	Required	Description
trace_id	string	No	Exact, case-sensitive Trace ID. Must be 1 to 128 characters.

Example: query by Trace

bash

1curl -X POST 'https://api.gate.ai/api/v1/generations/logs' \2  -H 'Authorization: Bearer <API_KEY>' \3  -H 'Content-Type: application/json' \4  -d '{"trace_id":"Trace-AbC-123"}'

Example: query the 100 most recent records

bash

1curl -X POST 'https://api.gate.ai/api/v1/generations/logs' \2  -H 'Authorization: Bearer <API_KEY>' \3  -H 'Content-Type: application/json' \4  -d '{}'

Response Fields

Name	Type	Description
code	integer	Business status code. Success is always 200.
msg	string	Status description. Success is always success.
timestamp	string	Current server Unix timestamp in seconds.
data	array	Usage log array; an empty array when no records match.
data[].id	integer	Usage record ID.
data[].trace_id	string	Request Trace ID.
data[].span_id	string	Request Span ID.
data[].session_id	string	Session ID.
data[].api_key_id	string	ID of the API Key that generated the record.
data[].user_id	string	User ID.
data[].app	string	Calling application identifier.
data[].standard_model	string	Standard model name.
data[].usage_model	string	Model name actually used for metering.
data[].stream	boolean	Whether the original request used streaming.
data[].response_status	integer	HTTP response status of the original request.
data[].latency	integer	Original request latency in milliseconds.
data[].input_tokens	integer	Number of input tokens.
data[].output_tokens	integer	Number of output tokens.
data[].total_tokens	integer	Total token count.
data[].cache_read_tokens	integer	Number of cache-read tokens.
data[].cache_write_tokens	integer	Number of cache-write tokens.
data[].input_tokens_details	string	Input token details in the stored string format.
data[].output_tokens_details	string	Output token details in the stored string format.
data[].input_cost	string	Input cost as a decimal string.
data[].output_cost	string	Output cost as a decimal string.
data[].cache_read_cost	string	Cache-read cost as a decimal string.
data[].cache_write_cost	string	Cache-write cost as a decimal string.
data[].total_cost	string	Total cost as a decimal string.
data[].is_free	boolean	Whether this request was covered by free quota.
data[].timestamp	string	Usage time in ISO 8601 UTC.
data[].created_at	string	Record creation time in ISO 8601 UTC.
data[].metadata	string	Extended call information in the stored string format.

Response Example

json

1{2  "code": 200,3  "msg": "success",4  "timestamp": "1784633852",5  "data": [6    {7      "id": 42,8      "trace_id": "Trace-AbC-123",9      "span_id": "span-001",10      "session_id": "session-001",11      "api_key_id": "1001",12      "user_id": "2002",13      "app": "example-client",14      "standard_model": "openai/gpt-5",15      "usage_model": "gpt-5",16      "stream": false,17      "response_status": 200,18      "latency": 842,19      "input_tokens": 120,20      "output_tokens": 80,21      "total_tokens": 200,22      "cache_read_tokens": 20,23      "cache_write_tokens": 0,24      "input_tokens_details": "{"cached_tokens":20}",25      "output_tokens_details": "{"reasoning_tokens":10}",26      "input_cost": "0.00120000",27      "output_cost": "0.00160000",28      "cache_read_cost": "0.00002000",29      "cache_write_cost": "0.00000000",30      "total_cost": "0.00282000",31      "is_free": false,32      "timestamp": "2026-07-21T08:30:00Z",33      "created_at": "2026-07-21T08:30:01Z",34      "metadata": "{"request_type":"audio"}"35    }36  ]37}

No matching records

json

1{2  "code": 200,3  "msg": "success",4  "timestamp": "1784633852",5  "data": []6}

Response

Status	Meaning	Description	Schema
200	OK	Query succeeded; data is an empty array when no records match.	UsageLogResponse
400	Bad Request	Invalid JSON body, or invalid trace_id type or length.	ErrorResponse
401	Unauthorized	The API Key is missing, invalid, expired, revoked, disabled, or inactive.	ErrorResponse
403	Forbidden	Reserved for future API Key permission policies.	ErrorResponse
429	Too Many Requests	The API Key exceeded 1 request per second; the response includes Retry-After.	ErrorResponse
500	Internal Server Error	Database query failure or internal gateway error.	ErrorResponse

Error Response Example

json

1{2  "error": {3    "type": "invalid_request_error",4    "message": "invalid API key"5  }6}