ClawOps APIUsage

사용량 집계 조회

View as Markdown
계정의 사용량을 **집계된 형태로** 돌려줍니다. 통화 목록을 받아 직접 합산하는 것과 다릅니다 — - **사후 정정이 반영됩니다.** 통화 시간은 종료 후에도 정정될 수 있고(`durationOverride`, 늦은 finalize, 운영 보정), 이 API 는 호출 시점에 원장을 다시 집계하므로 그 정정이 항상 반영됩니다. 목록을 긁어 직접 쌓으면 이미 받아간 건의 정정이 반영되지 않아 청구서와 계속 어긋납니다. - **청구 주기 경계가 맞습니다.** 주기 시작은 일 경계가 아니라 가입 순간의 시각입니다. 달력 월로 합산하면 어긋납니다. - **통화 목록에 없는 미터도 포함됩니다.** 문자·전사·요약은 `call_logs` 에 없습니다. ## 정산에 쓰는 축 `groupBy=linkId` 가 관리번호 파트너의 정산 단위입니다. 이 값은 `assignment.completed` webhook 의 `LinkId` 와 같아서 파트너가 자기 사용자와 바로 조인할 수 있습니다. 관리번호로 발급되지 않은 번호는 `linkId` 가 `null` 로 묶입니다. ⚠️ **번호(`groupBy=number`)를 정산 단위로 쓰지 마십시오.** 번호는 반납 후 재배정됩니다. 같은 번호에 이전 이용자의 사용량이 섞이지 않도록 이 API 는 배정 구간으로 잘라 집계하지만, 수신측에서 번호를 키로 누적하면 그 구분이 사라집니다. ## 단위 — 초로 돌려줍니다 통화·전사·요약은 **초**입니다. 청구는 계정 합계에 올림을 한 번만 겁니다 (`ceil((발신+전환)/60)`). 축을 쪼갠 값을 각각 올림해 더하면 합계가 청구서보다 커지므로, 올림한 분은 `totals[].billableMinutes` 에만 담습니다. ## 금액 `records` 에는 **수량만** 담깁니다. 단가가 누진 구간(발신 60 → 45 → 25원)이라 축별로 금액을 나눌 수 없습니다 — 합계에만 정의됩니다. ⚠️ **현재 `amount` 와 `totals[].unitPriceHint` 는 항상 `null` 입니다.** 금액 계산은 플랜 포함량·누진 구간·애드온을 함께 봐야 해서 청구 경로를 재사용하는 후속 작업으로 남았습니다. 지금은 **수량**에 자사 단가를 적용해 사용하십시오.

Authentication

AuthorizationBearer

API Key를 Bearer 토큰으로 전달

Path parameters

accountIdstringRequired

계정 ID

Query parameters

fromdatetimeOptional

집계 시작(UTC, 포함). to 와 함께 주어야 합니다 — 한쪽만 주면 400. 생략하면 현재 청구 주기 전체를 집계합니다.

todatetimeOptional

집계 끝(UTC, 미포함). 구간 최대 92일.

groupBylist of enumsOptional
쪼갤 축. 반복 지정으로 조합합니다(`?groupBy=day&groupBy=linkId`). ⚠️ 콤마 구분(`?groupBy=day,linkId`)은 받지 않습니다 — 값 검증을 유지하기 위한 선택이라, 오타는 조용히 무시되지 않고 400 이 됩니다. 생략하면 미터별 합계만 돌려줍니다.
Allowed values:
meterlist of enumsOptional

특정 미터만 조회. 반복 지정(?meter=a&meter=b). 생략 시 전체.

includeTodaybooleanOptionalDefaults to false

진행 중인 오늘(UTC) 구간을 포함할지. 오늘 구간은 다시 조회할 때마다 값이 달라지고 스캔 구간도 그만큼 늘어납니다. 정산은 확정 구간만 쓰는 것이 정상이므로 기본은 false 입니다.

pageSizeintegerOptional1-1000

페이지당 항목 수(기본 200, 최대 1000).

page_sizeintegerOptional1-1000Deprecated

pageSize 의 별칭(하위호환). 신규 연동은 pageSize 를 사용하세요.

limitintegerOptional1-1000Deprecated

pageSize 의 별칭(하위호환). 신규 연동은 pageSize 를 사용하세요.

pageintegerOptional>=1Defaults to 1

1-based 페이지 번호.

Response

집계 결과

metaobject

페이징 상태. 다른 목록 API 의 meta 와 같은 모양이다.

total 은 records 를 쪼갠 전체 행 수이며, 축을 지정할수록 커진다. totals(사용량 합계)와는 다른 것이다.

periodobject

집계 구간. from/to 를 주지 않으면 현재 청구 주기가 들어간다.

⚠️ 경계는 전부 UTC 다. 청구 주기 시작은 일 경계가 아니라 가입 순간의 시각이 그대로 쓰인다(실측: 03:56:49, 11:21:39). 달력 월로 직접 합산하면 우리 청구서와 어긋나므로 정산에는 이 응답의 from/to 를 그대로 쓸 것.

recordslist of objects

groupBy 축으로 쪼갠 사용량. 수량만 담는다.

  • 통화·전사·요약은 초다. 분 올림은 여기서 하지 않는다(축마다 올림하면 합계가 커진다).
  • 금액도 담지 않는다 — 단가가 누진 구간이라 축별로 나눌 수 없다.
totalslist of objects

축과 무관한 계정 전체 합계. records 를 미터별로 합한 값과 일치한다.

amountobject or nullOptional

이번 구간의 종량 예상액.

⚠️ 현재는 어떤 조회에서도 항상 null 이다 — 금액 계산은 플랜 포함량·누진 구간· 애드온을 함께 봐야 해서 청구 경로를 재사용하는 후속 작업으로 남았다. 아래는 채워졌을 때의 계약이다.

다음 두 경우에는 그때에도 null 이다.

  • groupBy 에 linkId·number·day 중 하나라도 지정한 조회 — 축별 금액은 제공하지 않는다.
  • from/to 로 청구 주기가 아닌 임의 구간을 조회한 경우.

⚠️ 확정 청구액이 아니다. 정기 결제 시점의 플랜료·애드온·일할 계산은 포함되지 않는다.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error