API 레퍼런스
로그인
본문으로 건너뛰기

사용량 확인

잡 수, 과금 분, 금액을 콘솔, CLI, MCP, API에서 확인하고 CSV로 내려받기

사용량은 잡이 끝나 정산된 금액을 UTC 날짜 기준으로 묶은 것입니다. 콘솔, xenocast usage, MCP usage, GET /v1/usage가 모두 같은 원장을 읽습니다

어떻게 세나

  • 잡 하나가 행 하나입니다. billed_minutes = ceil(run_seconds / 60), 금액은 잡 시작 때 고정된 분당 요금에 과금 분을 곱한 값입니다
  • 날짜는 잡이 끝난(정산된) UTC 날짜입니다. 실행 중인 잡은 끝나기 전까지 사용량에 들어가지 않습니다
  • 금액은 정수 *_micro_usd(1 USD = 1,000,000)와 소수 6자리 문자열 *_usd로 함께 옵니다

콘솔

분석 → 사용량(/console/usage)

  • 기간과 워크스페이스, API 키로 거르고 일별, 워크스페이스별, 키별로 묶어 봅니다
  • 요약 카드(잡 수, 과금 분, 금액)와 일별 차트, 표
  • CSV 내려받기로 잡 단위 CSV를 받습니다

분석 → 비용(/console/cost)

  • 기간(이번 달, 지난달, 7일, 30일, 직접 지정)과 묶음(day, workspace, api_key, runner)으로 비용 추이를 봅니다
  • 여기서도 CSV를 받습니다

API 키(/console/keys) 표의 이번 달 비용 열에서 키별 이번 달 금액을 바로 볼 수 있습니다

에이전트 연결(/console/agents)은 MCP로 들어온 잡만 모아 잡 수, 쓰는 키 수, 지출, 일별 차트를 보여 줍니다

CLI

xenocast usage [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--by day|workspace|api_key]
xenocast usage --from 2026-10-01 --to 2026-10-31 --by api_key
xenocast usage --json

키로 부르면 키가 묶인 워크스페이스만 집계합니다. credits로 지금 잔액과 분당 요금을 함께 봅니다

xenocast credits

MCP

usage 도구(from, to, group_by)와 credits 도구가 같은 값을 돌려줍니다. 에이전트가 쓴 금액을 묻는 질문에 쓰입니다

API

GET /v1/usage

쿼리설명
from, toUTC 날짜 YYYY-MM-DD, 양끝 포함, 최대 366일. 비우면 이번 달 1일부터 오늘까지
group_byday(기본), workspace, api_key
workspace_id, api_key_id콘솔 세션에서 범위를 좁힐 때. 키로 부를 때는 키의 워크스페이스로 고정
curl -sS "https://xenoci.com/api/runner/v1/usage?from=2026-10-01&to=2026-10-31&group_by=day" \
  -H "Authorization: Bearer $XENOCI_API_KEY" -H 'XenoCI-Error-Format: 2'

응답

{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "group_by": "day",
  "rows": [
    { "key": "2026-10-11", "label": null, "jobs": 4, "billed_minutes": 7, "amount_micro_usd": 277200, "amount_usd": "0.277200" }
  ],
  "total": { "key": "total", "jobs": 4, "billed_minutes": 7, "amount_micro_usd": 277200, "amount_usd": "0.277200" }
}

group_by=day는 기간의 모든 날을 0 포함으로 냅니다. workspace와 api_key는 사용이 있는 묶음만 금액 큰 순으로 내고, 키 없이 들어온 잡은 키 none입니다

GET /v1/usage/export.csv

같은 from, to, workspace_id, api_key_id를 받고 잡 단위 CSV를 돌려줍니다. 파일 이름은 xenoci-usage-<from>-<to>.csv입니다

curl -sS -o usage.csv "https://xenoci.com/api/runner/v1/usage/export.csv?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $XENOCI_API_KEY"

열

date_utc, organization_id, workspace_id, workspace_name, api_key_id, api_key_name, source, job_id, repository,
started_at_utc, ended_at_utc, run_seconds, billed_minutes, rate_usd_per_min, amount_usd, end_reason

UTF-8(BOM 포함), CRLF, RFC 4180 따옴표이며 금액은 소수 6자리입니다. 사람이 입력한 이름이 =, +, -, @로 시작하면 수식 실행을 막기 위해 앞에 '가 붙습니다

알림 메일

조직의 소유자와 관리자에게 다음 상황에 메일이 갑니다. 알림(/console/notifications)에서 보낸 기록을 보고 종류별로 끌 수 있습니다(API 키 유출은 끌 수 없음)

종류언제
잔액 부족사용 가능 잔액이 기준(기본 30분 요금, US$1.188) 이하로 내려간 순간, 조직당 24시간에 한 번
잔액 소진실행 중 잡이 credit_exhausted로 멈췄을 때, 충전 주기마다 한 번
워크스페이스 한도워크스페이스 이번 달 지출이 월 한도의 75%, 90%, 100%에 이를 때
티어 한도조직 이번 달 지출이 티어 월 한도의 75%, 90%, 100%에 이를 때
API 키 유출공개 저장소에서 키가 발견돼 자동 폐기했을 때(키 만든 사람도 수신)
API 요청 급증키 하나의 10분 요청 수가 기준을 넘을 때, 키마다 24시간에 한 번

다음 단계