TokenLab

관리

API 키 사용량 조회

사용자 API 키에 대한 페이지네이션된 사용량 세부 정보를 반환합니다.

GEThttps://api.tokenlab.sh/v1/management/api-keys/{keyId}/usage

개요

단일 API 키에 대한 페이지네이션된 사용량 기록을 반환합니다.

쿼리 매개변수

매개변수타입기본값 / 제한설명
pageinteger기본값 1, 최소 11부터 시작하는 페이지 번호
limitinteger기본값 50, 최소 1, 최대 100페이지 크기
modelstring최대 길이 100요청된 모델 이름
modelVendorstring최대 길이 100공개 모델 공급업체
sceneenum-chat, image, audio, video, embedding, rerank, translation, music, 3d, realtime, systemone
startDatestring-포함 범위의 시작점; 시간대가 포함된 RFC3339 또는 YYYY-MM-DD (00:00 UTC) 형식 허용
endDatestring-포함 범위의 종료점; RFC3339 또는 YYYY-MM-DD 형식 허용. 날짜만 입력할 경우 해당 날짜의 00:00 UTC를 의미하므로, 하루 전체를 포함하려면 다음 날짜를 사용하거나 RFC3339 시간을 사용하십시오

startDate와 endDate가 모두 제공되는 경우, startDate는 endDate보다 이전이거나 같아야 합니다.

참고 사항

  • 통화 관련 필드는 USD 기준입니다.

  • 응답은 페이지네이션 처리됩니다.

  • 정산된 기록에는 billing_transaction_id가 포함될 수 있습니다. 청구 내역과 요청을 대조해야 할 경우 request_id와 함께 저장해 두십시오.

  • 기록은 created_at을 기준으로 최신순으로 정렬됩니다.

  • report_busy 코드가 포함된 429 응답은 보고서 대기열이 가득 찼음을 의미합니다. Retry-After 초 이후에 다시 시도하십시오.

예시

요청

cURL
curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=chat&startDate=2026-07-01&endDate=2026-07-31T23:59:59Z" \
  -H "Authorization: Bearer mt-your-management-token"

요청 / 응답

이 페이지는 OpenAPI 스키마와 복사 가능한 요청 예시를 제공합니다. 관리 요청은 터미널이나 클라이언트에서 Management Token을 사용하여 전송하십시오. 이 페이지에서는 직접 전송을 지원하지 않습니다.

응답 예시

응답

200 OK
{
  "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.6-luna",
      "claude-sonnet-4-6"
    ],
    "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",
    "delivery_policy": null
  },
  "items": [
    {
      "request_id": "req_abc123",
      "billing_transaction_id": "billtxn_abc123",
      "model": "gpt-5.6-luna",
      "logical_model": "gpt-5.6-luna",
      "model_vendor": "OpenAI",
      "scene": "chat",
      "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",
      "requested_policy": null,
      "resolved_tier": null,
      "charged_price_basis": null
    }
  ],
  "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.6-luna",
        "logical_model": "gpt-5.6-luna",
        "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.6-luna",
        "logical_model": "gpt-5.6-luna",
        "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"
      }
    ],
    "daily_cost": [
      {
        "date": "2026-07-08T00:00:00.000Z",
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ]
  }
}

주요 필드

api_keyobject
목록/생성/수정 응답과 동일한 필드를 사용하는 API 키 요약 정보입니다.
itemsarray
페이지네이션된 사용량 행입니다.
paginationobject
page, limit, total, totalPages를 포함한 페이지네이션 메타데이터입니다.
summaryobject
선택한 필터에 대한 집계된 총계입니다.
breakdownsobject
선택한 필터에 대한 집계된 분석 데이터입니다.
items[].request_idstring | null
지원 및 대조를 위한 공개 요청 식별자입니다.
items[].billing_transaction_idstring | null
사용 가능한 경우의 정산된 결제 트랜잭션 ID입니다.
items[].modelstring
요청된 공개 모델 이름입니다.
items[].logical_modelstring
보고용으로 사용된 논리적 공개 모델입니다.
items[].model_vendorstring | null
공개 모델 공급업체입니다.
items[].scenestring | null
공개 요청 장면(scene)입니다.
items[].usage_unitstring
per_token과 같은 청구 사용량 단위입니다.
items[].usage_quantitynumber
표시용 JSON 숫자로 된 사용량입니다.
items[].usage_quantity_decimalstring
10진수 문자열로 된 정확한 사용량입니다.
items[].prompt_tokensnumber
프롬프트 토큰 수입니다.
items[].completion_tokensnumber
완성(completion) 토큰 수입니다.
items[].total_tokensnumber
총 토큰 수입니다.
items[].cache_read_tokensnumber
캐시 읽기 토큰 수입니다.
items[].cache_write_tokensnumber
총 캐시 쓰기 토큰 수입니다.
items[].cache_write_tokens_5mnumber
5분 캐시 쓰기 토큰 수입니다.
items[].cache_write_tokens_1hnumber
1시간 캐시 쓰기 토큰 수입니다.
items[].costnumber
표시용 JSON 숫자로 된 USD 비용입니다.
items[].cost_decimalstring
10진수 문자열로 된 정확한 USD 비용입니다.
items[].requested_policystring | null
auto, verified, official, null. 기록된 경우 요청된 전달 정책입니다.
items[].resolved_tierstring | null
verified, official, null. 기록된 경우 사용된 전달 계층입니다.
items[].charged_price_basisobject | null
기록된 경우 적용된 가격 및 청구 가능 수량입니다. 도구 비용이 포함된 요청의 경우, measure.dimensions에 webSearchCalls 또는 groundedPrompts가 포함되며, effectiveUnitPrices에는 각 호출의 가격이 webSearch 또는 groundedPrompt로 포함됩니다.
items[].created_atstring
ISO 형식의 사용량 행 타임스탬프입니다.
summary.total_requestsnumber
총 요청 수입니다.
summary.total_costnumber
표시용 JSON 숫자로 된 총 USD 비용입니다.
summary.total_cost_decimalstring
10진수 문자열로 된 정확한 총 USD 비용입니다.
summary.total_prompt_tokensnumber
총 프롬프트 토큰 수입니다.
summary.total_completion_tokensnumber
총 완성 토큰 수입니다.
summary.total_tokensnumber
총 토큰 수입니다.
summary.usage_unit_breakdownarray
사용량 단위별로 그룹화된 사용량입니다.
breakdowns.by_modelarray
요청된 공개 모델별 분석입니다.
breakdowns.by_logical_modelarray
논리적 공개 모델별 분석입니다.
breakdowns.by_model_vendorarray
공개 모델 공급업체별 분석입니다.
breakdowns.by_scenearray
공개 요청 장면별 분석입니다.
breakdowns.daily_costarray
일일 비용 추이입니다.

인증

ManagementTokenAuth
AuthorizationBearer <token>

관리 토큰 인증입니다. Dashboard > API > Management Tokens에서 관리 토큰을 생성하거나 관리하십시오.

위치: header

경로 매개변수

keyId*string

쿼리 매개변수

page?integer

1부터 시작하는 페이지 번호. 기본값은 1입니다.

범위1 <= value
기본값1
limit?integer

페이지 크기. 기본값은 50이며 최대값은 100입니다.

범위1 <= value <= 100
기본값50
model?string

요청된 모델 이름으로 필터링. 최대 길이 100.

길이length <= 100
modelVendor?string

공개 모델 제공자로 필터링. 최대 길이 100.

길이length <= 100
scene?string

공개 요청 장면(scene)으로 필터링.

허용 값

  • "chat"
  • "image"
  • "audio"
  • "video"
  • "embedding"
  • "rerank"
  • "translation"
  • "music"
  • "3d"
  • "realtime"
  • "systemone"
startDate?string

하한값(포함)입니다. RFC3339 형식(예: 2026-03-28T00:00:00+08:00) 또는 YYYY-MM-DD(UTC 00:00 기준)를 허용합니다.

endDate?string

상한값(포함)입니다. RFC3339 형식(예: 2026-03-28T23:59:59+08:00) 또는 YYYY-MM-DD(해당 날짜 시작 시 UTC 00:00 기준)를 허용합니다. 하루 전체를 포함하려면 다음 날짜를 전달하거나 해당 날짜의 마지막 시간인 RFC3339 시간을 전달하십시오.

응답

application/json

application/json

application/json

application/json

application/json

application/json