빌링 API

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

빌링 키 만들기

1. 열기: Console → Billing API keys (워크스페이스 소유자만 가능). 이름을 지정하고 필요하면 IP 허용 목록으로 제한하거나 만료일을 설정한 다음 키를 복사하세요 - 키는 sk-syn-bill- 로 시작하며 한 번만 표시됩니다.
2. 이를 Bearer 토큰으로 사용해 아래 엔드포인트를 호출하세요. 같은 페이지에서 언제든지 폐기할 수 있습니다 - 폐기하면 즉시 무효화되며 워크스페이스의 다른 것에는 영향이 없습니다.
3. 키는 생성자에게 연결되어 있습니다. 생성자가 더 이상 워크스페이스 소유자가 아니게 되면 작동을 멈추고 403 key_owner_not_authorized.

인증

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

Authorization: Bearer sk-syn-bill-...

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-bill-..."

응답 예시

{
  "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-bill-..."

응답 예시

{
  "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-bill-..."

응답 예시

{"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-bill-..."

응답 예시

{
  "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-bill-..."

응답 예시

{
  "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-bill-..."

응답 예시

{
  "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 키를 프로그래밍 방식으로 발급하거나 관리해야 하나요? Provisioning Keys를 참고하세요.