빌링 API

콘솔을 열지 않고도 자신의 워크스페이스의 사용량과 비용 데이터를 자체 시스템으로 가져올 수 있습니다. 빌링 키는 읽기 전용 자격 증명이며 하나의 워크스페이스로 범위가 제한됩니다 - 청구 데이터를 읽을 수 있을 뿐, 그 외에는 아무것도 할 수 없습니다.

빌링 키 만들기

1. 열기: Console → API 키 → 관리 키 (워크스페이스 관리자와 소유자 가능). 이름을 지정하고 billing.read 스코프를 선택한 뒤, 필요하면 IP 허용 목록으로 제한하거나 만료일을 설정한 다음 키를 복사하세요 - 키는 sk-syn-admin- 로 시작하며 한 번만 표시됩니다.
2. 이를 Bearer 토큰으로 사용해 아래 엔드포인트를 호출하세요. 같은 페이지에서 언제든지 폐기할 수 있습니다 - 폐기하면 즉시 무효화되며 워크스페이스의 다른 것에는 영향이 없습니다.
3. 워크스페이스 소유 키가 아니라면 키는 만든 사람에게 묶여 있습니다. 만든 사람이 워크스페이스의 관리자나 소유자 역할을 잃으면 키는 작동을 멈추고 다음 오류를 반환합니다: 403 key_owner_not_authorized.

인증

모든 호출에는 Authorization: Bearer sk-syn-admin-... 를 아래 기본 URL에 대해 보내야 합니다. 빌링 키는 이 엔드포인트에서만 동작하며, 이 엔드포인트도 빌링 키만 허용합니다 - 그 외의 조합은 401 wrong_key_kind.

Authorization: Bearer sk-syn-admin-...

Base URL: https://synthorai.io/api/v1/billing

GET /usage - 집계 사용량

GET /usage

시간 또는 일 단위로 미리 집계된 행으로, 청구서와 대시보드용입니다. 시간별 롤업에 마지막 수집 이후 기록된 요청을 더하므로, 최근 버킷이 수집 주기 하나만큼 통째로 뒤처지지 않습니다.

각 행에서 api_key_id와 api_key_name은 group_by api_key를 포함할 때만 나타나며, model도 마찬가지로 model을 포함할 때만 나타납니다. 버킷에 지연 시간 샘플이 없으면 avg_latency_ms가 null일 수 있습니다.

요청 예시

curl "https://synthorai.io/api/v1/billing/usage?start=2026-09-01&end=2026-09-24&granularity=day" \
  -H "Authorization: Bearer sk-syn-admin-..."

응답 예시

{
  "data": [
    {
      "bucket_start": "2026-09-23T00:00:00Z",
      "bucket_end": "2026-09-24T00:00:00Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "requests": 1280,
      "success_requests": 1265,
      "error_requests": 15,
      "errors_4xx": 12,
      "errors_429": 2,
      "errors_5xx": 1,
      "prompt_tokens": 512000,
      "completion_tokens": 98000,
      "cached_tokens": 210000,
      "cache_write_tokens": 8000,
      "reasoning_tokens": 4000,
      "cost_usd": 4.1732,
      "byok_list_price_usd": 0,
      "byok_requests": 0,
      "avg_latency_ms": 812,
      "final": true
    }
  ],
  "meta": {
    "generated_at": "2026-09-24T08:00:00Z",
    "data_complete_until": "2026-09-24T06:00:00Z",
    "timezone": "UTC",
    "currency": "USD",
    "next_cursor": null,
    "has_more": false
  }
}

GET /records - 요청 단위 행

GET /records

요청마다 한 행이며, 자체 데이터베이스로의 증분 동기화를 위한 것입니다. cursor로 동기화하세요. 절대 시간으로 동기화하지 마세요. 수신한 행은 record_id로 중복 제거하세요 - 이유는 아래 "시간 공백 피하기"를 참고하세요.

요청 예시

curl "https://synthorai.io/api/v1/billing/records?start=2026-09-24T00:00:00Z&limit=500" \
  -H "Authorization: Bearer sk-syn-admin-..."

응답 예시

{
  "data": [
    {
      "record_id": "rec_8f2a91c4",
      "request_id": "req_9f3c2b1a",
      "recorded_at": "2026-09-24T05:58:31Z",
      "completed_at": "2026-09-24T05:58:29Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "status": "success",
      "status_code": 200,
      "prompt_tokens": 812,
      "completion_tokens": 194,
      "cached_tokens": 512,
      "cache_write_tokens": 64,
      "cache_write_5m_tokens": 64,
      "cache_write_1h_tokens": 0,
      "cost_usd": 0.00412,
      "byok_list_price_usd": 0,
      "is_byok": false,
      "is_stream": true,
      "duration_ms": 1340,
      "ttft_ms": 210
    }
  ],
  "meta": {
    "next_cursor": "eyJvIjoiODgxNDA5MCJ9",
    "has_more": false,
    "window_final": true,
    "safe_until": "2026-09-24T05:58:31Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "data_complete_until": "2026-09-24T05:58:00Z"
  }
}

GET /records/export - 스트리밍 내보내기

GET /records/export

/records와 동일한 필터를 사용하며, 줄바꿈으로 구분된 JSON(application/x-ndjson)으로 스트리밍됩니다 - 페이지가 나뉜 목록이 아니라 대규모 백필용으로 만들어졌습니다. 한 워크스페이스당 한 번에 하나의 내보내기만 스트리밍할 수 있으며, 두 번째는 429 too_many_concurrent_requests를 받습니다.

요청 예시

curl -N "https://synthorai.io/api/v1/billing/records/export?cursor=eyJvIjoiODgxNDAzMiJ9" \
  -H "Authorization: Bearer sk-syn-admin-..."

응답 예시

{"record_id":"rec_8f2a91c4","request_id":"req_9f3c2b1a","model":"claude-sonnet-5","status":"success","cost_usd":0.00412}
{"record_id":"rec_8f2a91c5","request_id":"req_9f3c2b1b","model":"claude-sonnet-5","status":"success","cost_usd":0.00398}
{"_meta":{"next_cursor":"eyJvIjoiODgxNDA5MSJ9","rows":2,"complete":true,"window_final":true,"generated_at":"2026-09-24T06:00:02Z"}}

스트림의 마지막 줄은 _meta 객체입니다:

GET /summary - 예비 통계 및 이상

GET /summary

총계, 비용 기준 상위 모델 및 상위 키, 해당 범위의 오류율, 그리고 anomalies 목록(high_error_rate, rate_limited, data_not_final, rollup_delayed)이 추가됩니다. 각각 info 또는 warning의 심각도와 사람이 읽을 수 있는 메시지를 포함합니다. 아직 확정되지 않은 범위의 숫자는 여전히 바뀔 수 있습니다 - 아래를 참고하세요.

models_count와 keys_count는 top_models와 top_keys의 배후 총계를 나타내며, 이 목록들은 비용 기준 상위 최대 20개까지만 나열합니다. end 이전 30일이, start 가 생략된 경우의 기본 범위입니다.

요청 예시

curl "https://synthorai.io/api/v1/billing/summary?start=2026-09-17&end=2026-09-24" \
  -H "Authorization: Bearer sk-syn-admin-..."

응답 예시

{
  "data": {
    "totals": { "requests": 48210, "cost_usd": 132.55, "error_rate": 0.021 },
    "models_count": 6,
    "keys_count": 3,
    "top_models": [ { "model": "claude-sonnet-5", "cost_usd": 88.10, "byok_list_price_usd": 0 } ],
    "top_keys": [ { "api_key_id": 42, "api_key_name": "prod-backend", "cost_usd": 61.30, "byok_list_price_usd": 0 } ],
    "anomalies": [
      { "type": "data_not_final", "severity": "info", "message": "The last 2 hours of this range are not yet final." }
    ]
  },
  "meta": {
    "generated_at": "2026-09-24T06:00:02Z",
    "data_complete_until": "2026-09-24T04:00:00Z"
  }
}

GET /freshness - 데이터 완전성

GET /freshness

반환되는 값은 data_complete_until, latest_recorded_at, safe_until 및 pipeline_lag_seconds - 방금 가져온 범위를 확정된 것으로 간주하기 전에 이를 폴링하세요. safe_until은 호출자가 완전하다고 신뢰할 수 있는 가장 최근의 recorded_at입니다. 그보다 최신인 행은 아직 도착 중일 수 있습니다.

요청 예시

curl "https://synthorai.io/api/v1/billing/freshness" \
  -H "Authorization: Bearer sk-syn-admin-..."

응답 예시

{
  "data": {
    "data_complete_until": "2026-09-24T04:00:00Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "safe_until": "2026-09-24T05:58:31Z",
    "pipeline_lag_seconds": 47
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z" }
}

GET /balance - 워크스페이스에서 지금 쓸 수 있는 잔액

GET /balance

워크스페이스의 현재 사용 가능 잔액을 반환하며, 콘솔에 표시되는 사용 가능 잔액과 같습니다. 폴링용으로 설계되어 30~60초마다 확인하면 충분합니다. 별도의 속도 제한을 사용하므로 폴링이 데이터 엔드포인트의 한도를 소모하지 않으며, 잔액이 0일 때도 응답합니다.

요청 예시

curl "https://synthorai.io/api/v1/billing/balance" \
  -H "Authorization: Bearer sk-syn-admin-..."

응답 예시

{
  "data": {
    "available_usd": 1284.37,
    "debt_usd": 0,
    "source": "live",
    "voucher": null,
    "scheduled_credits": [
      { "amount_usd": 250, "release_at": "2026-10-01T00:00:00Z" }
    ],
    "scheduled_credit_total_usd": 250
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z", "currency": "USD" }
}

오류

모든 오류는 {"error": {"type", "message", "hint"}}:

{
  "error": {
    "type": "range_too_large",
    "message": "the requested range exceeds this endpoint's cap",
    "hint": "narrow start/end to at most 31 days, or sync /records with a cursor instead"
  }
}

속도 제한 및 한도

절대 반환되지 않는 항목: channel_id, upstream_request_id, usage_raw, other, content, ip_address, user_agent, cost_detail.

시간 공백 피하기

요청은 완료된 후 비동기적으로 로그에 기록됩니다 (보통 몇 초, 백로그가 있으면 더 오래 걸립니다). /usage와 /summary가 읽어오는 시간별 롤업은 배치 단위로 적재됩니다. 가장 최근 몇 시간은 항상 약간 불완전합니다. /usage와 /summary는 마지막 수집 이후 기록된 요청도 더합니다(meta.live_tail이 true). 롤업이 너무 뒤처지면 더하지 않으며(meta.live_tail이 false), 최근 버킷은 불완전합니다.

data_complete_until은 다음 두 값 중 더 이른 값입니다: 시간별 롤업의 워터마크에서 현재 파이프라인 지연을 뺀 값, 또는 아직 롤업되지 않은 가장 오래된 요청 - 여기서 30분의 안전 마진을 뺀 뒤 시간 단위로 내림합니다.

모든 /usage 행에는 final 플래그가 있습니다: true 는 해당 버킷의 종료 시각이 data_complete_until (/freshness의 값) 이전이거나 같을 때 성립합니다. 확정된 버킷은 다시는 바뀌지 않습니다.

• 집계 데이터: (bucket_start, api_key_id, model)을 기준으로 각 행을 자체 저장소에 upsert하고, 여전히 final: false인 버킷은 다시 가져오세요. 새 합계에서 이전 합계를 빼서 델타를 구하는 방식은 절대 사용하지 마세요.
• 원시 행: cursor로 동기화하세요. 절대 시간으로 동기화하지 마세요. next_cursor를 보관하고 다음 호출에서 거기서부터 재개하며, 재전송된 페이지가 같은 행을 다시 전달할 경우를 대비해 수신한 행을 record_id(행마다 안정적인 불투명 id)로 중복 제거하세요. 기록된 지 약 5분이 안 된 행은 보류됩니다 - safe_until은 가장 최근에 기록된 행의 시각에서 5분을 뺀 값입니다 - 그래서 아직 커밋 중인 행이 이미 내준 커서 위치보다 앞서 나타나는 일이 없으며, 공백에 빠지는 데이터도 없습니다. 요청 수를 셀 때는 request_id 기준으로 중복을 제거해 세세요.
• 제한된 창: cursor로 동기화하는 대신 start/end 범위로 조회한다면, window_final이 true일 때만 완전하다고 신뢰하세요 (end를 지정했고 그것이 safe_until 이전이거나 같을 때만 true입니다). window_final이 false라면 같은 범위로 나중에 다시 호출하거나 cursor 동기화로 전환하세요. 기간의 시작은 safe_until 이전이어야 합니다. 그보다 늦은 시작은 Retry-After 헤더와 함께 400 start_too_recent를 반환합니다.

권장 연동 방법

• 야간 인보이스 처리: 하루에 한 번 granularity=day로 /usage를 호출하고, 지난번 실행에서 여전히 final: false였던 버킷은 다시 가져오세요.
• 요청 단위 상세: 한 시간마다 저장해 둔 마지막 next_cursor를 cursor로 설정해 /records를 호출하고, has_more가 true인 동안 계속 페이지네이션하며, 수신한 행은 record_id로 중복 제거하세요.
• 대시보드: 표시 중인 범위에는 /records를 직접 집계하지 말고 /summary를 호출하세요 - 이미 이상 목록을 포함하고 있습니다.

청구 데이터를 읽는 대신 일반 API 키를 프로그래밍 방식으로 발급하거나 관리해야 하나요? 관리 키를 참고하세요.