API로 크레딧 사용량과 대기열을 읽어요

API 키로 엔진별, 키별로 쓴 크레딧과 새 태스크를 넣을 여유를 바로 확인해요.

받는 결과

• GET /v1/usage: UTC 날짜 기간 동안 차감된 크레딧과 태스크 수를 날짜, 엔진, API 키별로 나눠 받습니다.
• GET /v1/async/status: 대기 중인 태스크와 실행 중인 태스크, 우선순위별 대기 수, 동시 실행 한도를 받습니다.
• 두 요청 모두 태스크를 보낼 때 쓰는 vt_ 키로 읽습니다.

동작 방식

사용량은 태스크에 차감된 크레딧을 더한 값입니다. 크레딧은 태스크가 완료될 때 차감되고, 실패한 태스크는 0입니다. 맨 위의 credits와 tasks는 모든 행의 합이고, 차감이 없는 조합은 행으로 나오지 않습니다.

key로 나누면 누가 크레딧을 썼는지 보입니다. 하위 계정의 태스크도 내 사용량에 들어가고, apiKey.subAccountId가 그 키를 가진 하위 계정을 알려 줍니다.

대기열은 QUEUED와 PROCESSING 태스크를 함께 셉니다. 플랜의 동시 실행 한도도 같은 방식으로 셉니다. 한도를 넘는 요청은 429 PLAN_CONCURRENCY_LIMIT를 받으므로, concurrency를 먼저 읽으면 배치를 한도 안에서 보냅니다.

이렇게 활용하세요

• 내 고객에게 사용량대로 청구합니다. 고객마다 키나 하위 계정을 주고 월말에 groupBy=key로 읽습니다.
• 큰 배치의 속도를 맞춥니다. max - used만큼만 태스크를 보냅니다.
• 엔진별 일일 사용량을 내 대시보드나 알림에 그립니다.

시작하기

이번 달 사용량을 엔진별로 읽습니다.

curl "https://api.querying.ai/v1/usage?groupBy=engine" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

{
  "success": true,
  "data": {
    "from": "2026-10-01",
    "to": "2026-10-20",
    "groupBy": ["engine"],
    "credits": 66.25,
    "tasks": 65,
    "rows": [
      { "taskType": "CHATGPT", "credits": 49, "tasks": 49 },
      { "taskType": "GEMINI", "credits": 6.25, "tasks": 5 },
      { "taskType": "PERPLEXITY", "credits": 11, "tasks": 11 }
    ]
  }
}

from, tostring

YYYY-MM-DD 형식의 UTC 날짜이고 두 날짜를 모두 포함합니다. 기본값은 이번 UTC 달의 첫날과 오늘입니다. 기간은 366일까지입니다.

groupBystring

day, engine, key 중 원하는 것을 쉼표로 이어 씁니다. 기본값은 day,engine입니다. 각 행에는 고른 기준의 필드가 담깁니다.

rows[].apiKeyobject

groupBy=key일 때 크레딧을 쓴 키입니다(id, keyPrefix, name, subAccountId). 모니터, Playground, 대시보드에서 쓴 크레딧은 source가 monitor, playground, dashboard입니다.

대기열을 읽습니다.

curl "https://api.querying.ai/v1/async/status" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

{
  "success": true,
  "queuedTasks": 19,
  "processingTasks": 6,
  "priorityBreakdown": [
    { "priority": 8, "count": 3 },
    { "priority": 1, "count": 16 }
  ],
  "concurrency": { "used": 25, "max": 200 }
}

queuedTasks, processingTasksnumber

대기열에서 기다리는 태스크와 지금 실행 중인 태스크 수입니다. 하위 계정의 태스크도 함께 셉니다.

priorityBreakdownarray

대기 중인 태스크를 보낼 때 정한 priority별로 셉니다. 높은 순서로 나옵니다.

concurrencyobject

used는 대기 중과 실행 중 태스크를 더한 값으로, 플랜 한도가 세는 방식과 같습니다. max는 동시 실행 한도이므로 max - used가 새 태스크를 넣을 여유입니다.

오류

VALIDATION_ERRORHTTP 400

필드가 빠졌거나 허용 범위를 벗어났습니다. details에 해당 필드가 나옵니다.

MISSING_API_KEYHTTP 401

Authorization 헤더가 빠졌거나, 키가 잘못됐거나 만료 또는 폐기됐습니다.

SUB_ACCOUNT_FORBIDDENHTTP 403

하위 계정의 키입니다. 상위 계정의 키로 두 계정의 사용량과 대기열을 함께 읽습니다.

요금

사용량과 대기열 조회는 0크레딧입니다.