Help guides

Query historical usage by gateway header snapshots (x-trace-id / x-user-id / x-agent-name). Base URL: https://51kik.com. Auth: Access tokens.

See Request correlation for header semantics.

Filter rule

Exactly one of trace_id, user_id, or agent_name is required. Values are the original strings sent in the corresponding request headers.

Aggregate

GET /openapi/trace-usage/aggregate

curl -sS "https://51kik.com/openapi/trace-usage/aggregate?trace_id=order-2024-0001" \
  -H "X-Access-Token: $ACCESS_TOKEN"

Query (pick one):

Param	Maps to header
`trace_id`	`x-trace-id`
`user_id`	`x-user-id`
`agent_name`	`x-agent-name`

Example data:

{
  "totalTokens": 123456,
  "promptTokens": 80000,
  "completionTokens": 40000,
  "reasoningTokens": 3456,
  "cachedInputTokens": 12000,
  "totalRequests": 500,
  "okRequests": 480,
  "errorRequests": 20,
  "successRate": 96.00,
  "revenueCredit": 1234,
  "giftCostCredit": 200,
  "paidCostCredit": 1034,
  "avgLatencyMs": 850,
  "avgStreamFirstTokenMs": 120,
  "distinctModels": 5,
  "distinctApiKeys": 3
}

data fields:

Field	Type	Description
`totalTokens`	number	Total tokens (prompt + completion)
`promptTokens`	number	Input tokens
`completionTokens`	number	Output tokens
`reasoningTokens`	number	Reasoning tokens
`cachedInputTokens`	number	Cache-hit input tokens
`totalRequests`	number	Total request count
`okRequests`	number	Successful requests (`status = ok`)
`errorRequests`	number	Failed requests (`status = error`)
`successRate`	number	Success rate (0–100, 2 decimal places)
`revenueCredit`	number	Total billed credits (revenue side)
`giftCostCredit`	number	Gift-quota billed credits
`paidCostCredit`	number	Paid-quota billed credits
`avgLatencyMs`	number \| null	Mean end-to-end latency (ms), or `null` if no data
`avgStreamFirstTokenMs`	number \| null	Mean streaming first-token latency (ms); non-streaming rows excluded
`distinctModels`	number	Distinct models involved
`distinctApiKeys`	number	Distinct API keys involved

Paginated list

GET /openapi/trace-usage/list

curl -sS "https://51kik.com/openapi/trace-usage/list?user_id=user-123&page=1&page_size=20" \
  -H "X-Access-Token: $ACCESS_TOKEN"

Additional query params:

Param	Description
`page`	Default `1`
`page_size`	Default `20`, max `100`

Results are ordered by createdAt descending. Example data:

{
  "items": [
    {
      "requestId": "chatcmpl-abc123",
      "createdAt": "2026-06-10T08:30:00.000Z",
      "modelCode": "gpt-4o",
      "protocolSource": "openai",
      "status": "ok",
      "errorCode": null,
      "errorMessage": null,
      "finishReason": "stop",
      "promptTokens": 500,
      "completionTokens": 200,
      "totalTokens": 700,
      "reasoningTokens": 0,
      "cachedInputTokens": 0,
      "revenueCredit": 7,
      "giftCostCredit": 5,
      "paidCostCredit": 2,
      "latencyMs": 850,
      "streamLlmFirstTokenMs": null,
      "userId": "user-123",
      "agentName": "my-agent",
      "traceId": "trace-abc",
      "referer": "https://example.com",
      "clientIp": "1.2.3.4",
      "userAgent": "curl/8.0"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

data.items[] fields:

Field	Type	Description
`requestId`	string \| null	Upstream request ID (OpenAI-compatible `id`)
`createdAt`	string	Record creation time (UTC ISO 8601)
`modelCode`	string	Requested model code
`protocolSource`	string	Protocol source: `openai` / `anthropic`
`status`	string	Call status: `ok` / `error`
`errorCode`	string \| null	Error code; `null` on success
`errorMessage`	string \| null	Error message; `null` on success
`finishReason`	string \| null	Upstream `finish_reason` (`stop`, `length`, etc.)
`promptTokens`	number	Input tokens
`completionTokens`	number	Output tokens
`totalTokens`	number	Total tokens
`reasoningTokens`	number	Reasoning tokens
`cachedInputTokens`	number	Cache-hit input tokens
`revenueCredit`	number	Total billed credits (revenue side)
`giftCostCredit`	number	Gift-quota billed credits
`paidCostCredit`	number	Paid-quota billed credits
`latencyMs`	number \| null	End-to-end latency (ms)
`streamLlmFirstTokenMs`	number \| null	Streaming first-token latency (ms); `null` for non-streaming
`userId`	string \| null	Original `x-user-id` header value
`agentName`	string \| null	Original `x-agent-name` header value
`traceId`	string \| null	Original `x-trace-id` header value
`referer`	string \| null	`Referer` header
`clientIp`	string \| null	Client IP
`userAgent`	string \| null	`User-Agent` header

Pagination fields:

Field	Type	Description
`items`	array	Current page of records
`total`	number	Total matching record count
`page`	number	Current page number
`pageSize`	number	Page size

Errors

HTTP	`code`	Scenario
401	401	Missing `X-Access-Token`, or token invalid / disabled / expired
400	40001	Invalid filter (exactly one of the three params required)

Invalid filter body:

{
  "code": 40001,
  "message": "必须且只能提供 trace_id、user_id、agent_name 中的一个",
  "data": null
}

Filter rule

Aggregate

Paginated list

Errors

Related