메인 콘텐츠로 건너뛰기

​
개요

이 엔드포인트는 물리 라우팅 메타데이터를 노출하지 않고 API 키 단위 사용 내역을 반환합니다.

​
쿼리 파라미터

파라미터타입기본값 / 제한설명
pageinteger기본값 1, 최소 11부터 시작하는 페이지 번호
limitinteger기본값 50, 최소 1, 최대 100페이지 크기
modelstring최대 길이 100요청된 모델 이름
modelVendorstring최대 길이 100공개 모델 공급자
sceneenum-chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime
accessChannelenum-platform 또는 byok
startDatestring-포함되는 시작 경계값. 타임존이 포함된 RFC3339 또는 YYYY-MM-DD 지원
endDatestring-포함되는 종료 경계값. 타임존이 포함된 RFC3339 또는 YYYY-MM-DD 지원
startDate 와 endDate 를 함께 보내는 경우 startDate 는 endDate 보다 빠르거나 같아야 합니다.

​
참고 사항

  • 응답은 페이지네이션됩니다.
  • 응답에는 공개 가능한 과금 및 리포팅 필드만 포함됩니다.
  • 기본 요청의 정산이 완료되면 각 usage 항목에 billing_transaction_id 가 포함될 수 있습니다. 요청 단위 정산 대조에는 request_id 와 함께 사용하세요.
  • 내부 라우팅 및 물리 채널 메타데이터는 의도적으로 숨겨집니다.

​
예시

curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=video&accessChannel=platform&startDate=2026-03-01&endDate=2026-03-31" \
  -H "Authorization: Bearer mt-your-management-token"

​
요청 / 응답

정확한 스키마와 응답 필드는 상단의 인터랙티브 OpenAPI 패널을 참고하세요.

​
Response example

{
  "api_key": {
    "id": "key_abc123def456",
    "name": "Backend Worker",
    "key_prefix": "sk-live...",
    "status": "active",
    "limit_amount": 500,
    "limit_amount_decimal": "500",
    "used_amount": 148.25,
    "used_amount_decimal": "148.25",
    "models": [
      "gpt-5-mini",
      "claude-3-7-sonnet"
    ],
    "expires_at": "2026-12-31T23:59:59.000Z",
    "last_used_at": "2026-07-08T03:12:45.000Z",
    "created_at": "2026-07-01T10:00:00.000Z"
  },
  "items": [
    {
      "request_id": "req_abc123",
      "billing_transaction_id": "billtxn_abc123",
      "model": "gpt-5-mini",
      "logical_model": "gpt-5-mini",
      "model_vendor": "OpenAI",
      "scene": "chat",
      "access_channel": "platform",
      "usage_unit": "per_token",
      "usage_quantity": 1500,
      "usage_quantity_decimal": "1500",
      "prompt_tokens": 1000,
      "completion_tokens": 500,
      "total_tokens": 1500,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "cache_write_tokens_5m": 0,
      "cache_write_tokens_1h": 0,
      "cost": 0.0012,
      "cost_decimal": "0.0012",
      "created_at": "2026-07-08T03:15:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  },
  "summary": {
    "total_requests": 1,
    "total_cost": 0.0012,
    "total_cost_decimal": "0.0012",
    "total_prompt_tokens": 1000,
    "total_completion_tokens": 500,
    "total_tokens": 1500,
    "usage_unit_breakdown": [
      {
        "usage_unit": "per_token",
        "usage_quantity": 1500
      }
    ]
  },
  "breakdowns": {
    "by_model": [
      {
        "model": "gpt-5-mini",
        "logical_model": "gpt-5-mini",
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012",
        "usage_quantity": 1500,
        "usage_quantity_decimal": "1500"
      }
    ],
    "by_logical_model": [
      {
        "model": "gpt-5-mini",
        "logical_model": "gpt-5-mini",
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012",
        "usage_quantity": 1500,
        "usage_quantity_decimal": "1500"
      }
    ],
    "by_model_vendor": [
      {
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012
      }
    ],
    "by_scene": [
      {
        "scene": "chat",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ],
    "by_access_channel": [
      {
        "access_channel": "platform",
        "requests": 1,
        "cost": 0.0012
      }
    ],
    "daily_cost": [
      {
        "date": "2026-07-08T00:00:00.000Z",
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ]
  }
}

​
Important fields

​
api_key
object
API key summary using the same fields as list/create/update responses.
​
items
array
Paginated usage rows.
​
pagination
object
Pagination metadata with page, limit, total, and totalPages.
​
summary
object
Aggregated totals for the selected filters.
​
breakdowns
object
Aggregated breakdowns for the selected filters.
​
items[].request_id
string | null
Public request identifier for support and reconciliation.
​
items[].billing_transaction_id
string | null
Settled billing transaction id when available.
​
items[].model
string
Requested public model name.
​
items[].logical_model
string
Logical public model used for reporting.
​
items[].model_vendor
string | null
Public model vendor.
​
items[].scene
string | null
Public request scene.
​
items[].access_channel
string
platform or byok.
​
items[].usage_unit
string
Billing usage unit, such as per_token.
​
items[].usage_quantity
number
Usage quantity as a JSON number for display.
​
items[].usage_quantity_decimal
string
Exact usage quantity as a decimal string.
​
items[].prompt_tokens
number
Prompt token count.
​
items[].completion_tokens
number
Completion token count.
​
items[].total_tokens
number
Total token count.
​
items[].cache_read_tokens
number
Cache read token count.
​
items[].cache_write_tokens
number
Total cache write token count.
​
items[].cache_write_tokens_5m
number
Five-minute cache write token count.
​
items[].cache_write_tokens_1h
number
One-hour cache write token count.
​
items[].cost
number
Cost in USD as a JSON number for display.
​
items[].cost_decimal
string
Exact cost in USD as a decimal string.
​
items[].created_at
string
ISO usage row timestamp.
​
summary.total_requests
number
Total request count.
​
summary.total_cost
number
Total cost in USD as a JSON number for display.
​
summary.total_cost_decimal
string
Exact total cost in USD as a decimal string.
​
summary.total_prompt_tokens
number
Total prompt tokens.
​
summary.total_completion_tokens
number
Total completion tokens.
​
summary.total_tokens
number
Total tokens.
​
summary.usage_unit_breakdown
array
Usage quantity grouped by usage unit.
​
breakdowns.by_model
array
Breakdown by requested public model.
​
breakdowns.by_logical_model
array
Breakdown by logical public model.
​
breakdowns.by_model_vendor
array
Breakdown by public model vendor.
​
breakdowns.by_scene
array
Breakdown by public request scene.
​
breakdowns.by_access_channel
array
Breakdown by platform or byok access channel.
​
breakdowns.daily_cost
array
Daily cost trend.