사용량 조회

UTC 날짜, 워크스페이스 또는 API 키별 잡 수, 과금 분, 금액을 돌려줍니다

GET /v1/usage

인증

방식	허용	조건
API 키 (`Authorization: Bearer xci_live_…`)	가능	키 권한 `read` (run 키도 가능)
콘솔 세션 쿠키	가능	조직 역할 `owner`, `admin`, `developer`

API 키는 자기 워크스페이스만 봅니다, 콘솔 세션은 소유자와 관리자가 조직 전체를, 개발자는 배정된 워크스페이스만 봅니다
from과 to는 UTC 날짜이고 양끝을 포함합니다, 최대 366일이며 없으면 이번 달 1일부터 오늘까지입니다
group_by=day는 사용이 없는 날도 0으로 냅니다, workspace와 api_key는 사용이 있는 묶음만 금액이 큰 순으로 냅니다

참고 서버 구현(2026-10-12 dev 기준)이 계약 초안과 다른 점
호출자 인증이 없을 때 서버는 401 sessionrequired를 돌려줍니다(apikey_required가 아님)

매개변수

이름	위치	타입	설명
`org_id`	쿼리	string	콘솔 세션은 필수, API 키는 무시(키의 조직)
`from`	쿼리	date	UTC 날짜, 포함
`to`	쿼리	date	UTC 날짜, 포함
`group_by`	쿼리	`day` \| `workspace` \| `api_key`	day, workspace, api_key 중 하나, 기본 `"day"`
`workspace_id`	쿼리	string	콘솔 세션은 워크스페이스가 필요한 곳에서 필수, API 키는 생략하거나 키의 워크스페이스와 같아야 합니다
`api_key_id`	쿼리	string	이 키의 잡만

응답

200

필드	타입	항상	설명
`from`	date	항상	시작 날짜(UTC)
`to`	date	항상	끝 날짜(UTC)
`group_by`	string	항상	묶음 기준
`rows`	array<object>	항상	묶음별 행
`rows[].key`	string	항상	groupby에 따라 UTC 날짜(YYYY-MM-DD), workspaceid 또는 apikeyid
`rows[].label`	string		사람이 읽는 이름, null 가능
`rows[].jobs`	integer	항상	잡 수
`rows[].billed_minutes`	integer	항상	과금 분 합
`rows[].amount_micro_usd`	integer	항상	금액 합(µUSD), 최소 0
`rows[].amount_usd`	string	항상	같은 금액의 USD 문자열(소수 6자리), 형식 `^-?[0-9]+\.[0-9]{6}$`
`total`	object	항상	기간 합계
`total.key`	string	항상	groupby에 따라 UTC 날짜(YYYY-MM-DD), workspaceid 또는 apikeyid
`total.label`	string		사람이 읽는 이름, null 가능
`total.jobs`	integer	항상	잡 수
`total.billed_minutes`	integer	항상	과금 분 합
`total.amount_micro_usd`	integer	항상	금액 합(µUSD), 최소 0
`total.amount_usd`	string	항상	같은 금액의 USD 문자열(소수 6자리), 형식 `^-?[0-9]+\.[0-9]{6}$`

{
  "from": "2026-10-01",
  "to": "2026-10-12",
  "group_by": "day",
  "rows": [
    {
      "key": "2026-10-12",
      "label": "2026-10-12",
      "jobs": 4,
      "billed_minutes": 12,
      "amount_micro_usd": 475200,
      "amount_usd": "0.475200"
    }
  ],
  "total": {
    "key": "2026-10-12",
    "label": "2026-10-12",
    "jobs": 4,
    "billed_minutes": 12,
    "amount_micro_usd": 475200,
    "amount_usd": "0.475200"
  }
}

오류

HTTP	코드	다시 시도	뜻
400	`invalid_request`	아니오	본문이나 쿼리가 검증에 실패했습니다, error.details.fields에 문제 필드가 있습니다
401	`api_key_required`	아니오	API 키 엔드포인트에 Authorization: Bearer 헤더가 없습니다
401	`api_key_revoked_leaked`	아니오	공개 유출 신고로 자동 폐기된 키입니다, 새 키를 발급하세요
401	`invalid_api_key`	아니오	모르는 키이거나 폐기, 만료, 체크섬 불일치입니다(종료된 xeno_ 접두사 포함)
401	`session_required`	아니오	콘솔 엔드포인트를 유효한 콘솔 세션 쿠키 없이 불렀습니다
403	`insufficient_permission`	아니오	역할이나 키 권한(run/read)이 이 요청을 허용하지 않습니다
429	`rate_limited`	가능	이 키 또는 조직의 요청이 너무 많습니다, retryafters만큼 기다리세요
500	`internal_error`	가능	예상하지 못한 오류입니다, 다시 시도하고 반복되면 request_id와 함께 알려 주세요

오류 봉투 모양과 전체 코드 표는 오류 코드에 있습니다

예시

curl "https://xenoci.com/api/runner/v1/usage?from=2026-10-01&to=2026-10-12&group_by=day" \
  -H "Authorization: Bearer $XENOCI_API_KEY"

다음 단계

사용량 CSV GET /v1/usage/export.csv