API 키 사용량 조회

개요

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

쿼리 파라미터

파라미터	타입	기본값 / 제한	설명
`page`	integer	기본값 `1`, 최소 `1`	1부터 시작하는 페이지 번호
`limit`	integer	기본값 `50`, 최소 `1`, 최대 `100`	페이지 크기
`model`	string	최대 길이 `100`	요청된 모델 이름
`modelVendor`	string	최대 길이 `100`	공개 모델 공급자
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	포함되는 시작 경계값. 타임존이 포함된 RFC3339 또는 `YYYY-MM-DD` 지원
`endDate`	string	-	포함되는 종료 경계값. 타임존이 포함된 RFC3339 또는 `YYYY-MM-DD` 지원

startDate 와 endDate 를 함께 보내는 경우 startDate 는 endDate 보다 빠르거나 같아야 합니다.

참고 사항

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

예시

요청

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-31" \
  -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-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",
    "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

공개 요청 시나리오입니다.

items[].usage_unitstring

per_token 등의 청구 사용 단위입니다.

items[].usage_quantitynumber

표시용 JSON 숫자로 반환되는 사용량입니다.

items[].usage_quantity_decimalstring

10진 문자열로 반환되는 정확한 사용량입니다.

items[].prompt_tokensnumber

프롬프트 token 수입니다.

items[].completion_tokensnumber

완성 token 수입니다.

items[].total_tokensnumber

전체 token 수입니다.

items[].cache_read_tokensnumber

캐시 읽기 token 수입니다.

items[].cache_write_tokensnumber

전체 캐시 쓰기 token 수입니다.

items[].cache_write_tokens_5mnumber

5분 캐시 쓰기 token 수입니다.

items[].cache_write_tokens_1hnumber

1시간 캐시 쓰기 token 수입니다.

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

기록된 적용 가격과 청구 사용량입니다.

items[].created_atstring

사용 내역의 ISO 타임스탬프입니다.

summary.total_requestsnumber

전체 요청 수입니다.

summary.total_costnumber

표시용 JSON 숫자로 반환되는 USD 총비용입니다.

summary.total_cost_decimalstring

10진 문자열로 반환되는 정확한 USD 총비용입니다.

summary.total_prompt_tokensnumber

전체 프롬프트 token 수입니다.

summary.total_completion_tokensnumber

전체 완성 token 수입니다.

summary.total_tokensnumber

전체 token 수입니다.

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 형식을 허용합니다.

endDate?string

포괄적 날짜 필터. 시간대가 포함된 RFC3339(예: 2026-03-28T00:00:00+08:00) 또는 YYYY-MM-DD 형식을 허용합니다.

API 키 사용량 조회

개요

쿼리 파라미터

참고 사항

예시

요청 / 응답

응답 예시

주요 필드

인증

경로 매개변수

쿼리 매개변수

응답

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

API 키 사용량 조회

개요Copy Anchor Link

쿼리 파라미터Copy Anchor Link

참고 사항Copy Anchor Link

예시Copy Anchor Link

요청 / 응답Copy Anchor Link

응답 예시Copy Anchor Link

주요 필드Copy Anchor Link

인증Copy Anchor Link

경로 매개변수Copy Anchor Link

쿼리 매개변수Copy Anchor Link

응답Copy Anchor Link

200application/json

400application/json

401application/json

403application/json

404application/json

개요

쿼리 파라미터

참고 사항

예시

요청 / 응답

응답 예시

주요 필드

인증

경로 매개변수

쿼리 매개변수

응답

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`