> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 크레딧과 한도: 가격, 보류, 동시 실행, 요청 속도 제한

> 태스크별 비용, 크레딧이 보류되고 차감되는 방식, 429나 503을 반환하는 한도를 설명합니다.

모든 태스크에는 크레딧 가격이 있습니다. 가격은 제출할 때 보류되고, 태스크가 완료되면 차감되고, 실패하면 해제됩니다. 동시에 대기하거나 실행할 수 있는 태스크 수는 요금제가 정합니다.

엔진과 가격의 실시간 목록은 공개 capabilities 엔드포인트를 호출하세요. API 키가 필요 없습니다.

```bash theme={"theme":"css-variables"}
curl https://api.querying.ai/v1/capabilities
```

엔진 하나만 보려면 `?taskType=GEMINI`를 붙이세요. `GOOGLE_AIO` 같은 별칭도 받습니다. [capabilities 조회](/ko/api-reference/capabilities.md)를 참고하세요.

## 태스크별 크레딧

| `taskType` | 크레딧 |
| - | - |
| `CHATGPT` | 답변당 1. `payload.followUps`의 각 항목도 답변 하나입니다. |
| `PERPLEXITY`, `BING_COPILOT`, `META_AI` | 1 |
| `GEMINI`, `GOOGLE` (`GOOGLE_AIO`), `AIMODE` (`GOOGLE_AIMODE`), `NAVER_AI_BRIEF`, `NAVER_AI_TAB`, `QWEN`, `DOUBAO` | 1.25 |
| `GOOGLE_SERP`, `NAVER_SERP`, `BING_SEARCH`, `REDDIT` | 1 |
| `COMMERCE_SERP` | 3 |
| `COMMERCE_PRODUCT` | 3 |
| `WEB_SCRAPE`, `WEB_MAP` | 1 |
| `WEB_CRAWL` | 반환된 페이지당 1. 제출 시 `maxPages` 크레딧을 보류하며, 읽지 못한 페이지는 과금하지 않습니다. |
| `KEYWORD_VOLUME` | 태스크당 3(키워드 최대 100개) |
| `PROMPT_RESEARCH` | 11 |
| `GEO_SCORE` | 페이지당 10, 글자를 읽은 이미지마다 5(`images.read`, 최대 12장). 제출 시 70을 보류하며, 읽지 못한 이미지는 과금하지 않고, 90일 안의 읽기를 다시 쓴 이미지(`images.reused`)는 2입니다. |
| `AI_RENDERING` ([AI Rendering](/ko/research/ai-rendering.md)) | 렌더당 5, 글자를 읽은 이미지마다 5, 90일 안의 읽기를 다시 쓴 이미지마다 2(최대 12장). 제출 시 65를 보류합니다. 갱신도 같은 가격입니다. |
| [Product Lookup](/ko/research/product-lookup.md#가격) 조회의 질문 | 상품(상품과 각 경쟁 상품)마다 10, 쇼핑 질문마다 5이며 어느 엔진에 묻든 같습니다. 각 질문은 엔진 태스크로, 위의 엔진 가격 대신 이 가격을 나눈 몫이 과금됩니다. |
| Place Lookup (`POST /v1/place-lookup`) | 국가 기본 엔진에 모두 묻는 조회 1건에 10. `KR`은 질문마다 1, 그 밖의 국가는 1.25입니다. 엔진을 일부만 고른 조회는 보낸 질문만큼만 냅니다. [Place Lookup](/ko/research/place-lookup.md)을 참고하세요. |
| `CITATION_ANALYSIS` | 사용량에 따라 보류액 이내에서 계량합니다. 아래를 참고하세요. |

| 추가 기능 | 크레딧 |
| - | - |
| `payload.include.analysis` | 엔진 가격에 2를 더하며, `analysis.status`가 `ok`일 때만 과금합니다 |
| `payload.include.html` | `CHATGPT`, `PERPLEXITY`, `META_AI`에서 0.25이며, `html.status`가 `ok`일 때만 과금합니다. `GEMINI`, `GOOGLE`, `AIMODE`에서는 무료입니다. |
| `payload.include.citationAnalysis` | 별도의 `CITATION_ANALYSIS` 태스크로, 사용량에 따라 과금합니다 |
| 모니터 경쟁사 분석 | 모니터당 30일에 80 크레딧이며 실행마다 나눠 차감합니다. [GEO 모니터링](/ko/monitors.md#비용과-일정)을 참고하세요. |

가격은 요금제와 관계없이 같고, 크레딧의 달러 가치가 요금제마다 다릅니다. 크레딧은 `1.25`처럼 소수점 둘째 자리까지 가질 수 있습니다.

### Citation Analysis 계량

`CITATION_ANALYSIS` 태스크는 제출 시 `20 + 12 × citations + 80 × ⌈answer characters ÷ 1,000⌉` 크레딧을 보류합니다. 완료되면 `1 + ⌈input tokens ÷ 500⌉ + ⌈output tokens ÷ 100⌉ + 2 × source fetches`를 차감하며 보류액을 넘지 않습니다. 나머지 보류액은 해제됩니다. [Citation Analysis](/ko/research/citation-analysis.md)를 참고하세요.

## 보류, 차감, 해제

**1. 제출: 보류**

태스크 가격(`WEB_CRAWL`, `GEO_SCORE`, `CITATION_ANALYSIS`는 최대값)이 사용 가능 잔액에서 보류액으로 옮겨집니다. 잔액이 부족하면 제출은 `402 INSUFFICIENT_CREDITS`를 반환합니다. 제출 응답의 `credits`는 `0`입니다.

**2. 완료: 차감**

보류액에서 요금을 차감합니다. 종료된 태스크의 폴링과 webhook은 이를 `creditsCharged`로 보여줍니다.

**3. 실패: 해제**

보류액이 잔액으로 돌아옵니다. 실패한 태스크의 비용은 `0`입니다.

새 계정은 가입 시 500 크레딧을 받습니다.

## 잔액 확인

`GET /v1/credits`는 계정의 크레딧을 반환합니다. 조회에는 크레딧이 들지 않으므로 배치를 보내기 전마다 확인해도 됩니다. [크레딧 잔액](/ko/api-reference/credits.md)을 참고하세요.

```bash theme={"theme":"css-variables"}
curl https://api.querying.ai/v1/credits \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

```json theme={"theme":"css-variables"}
{
  "success": true,
  "remaining": 1879939,
  "perCycle": 1000000,
  "cycleResetsAt": "2026-11-14T07:37:57.000Z",
  "reserved": 61,
  "plan": "max",
  "topUpBalance": { "credits": 1000000, "nextExpiresAt": "2027-01-19T10:01:57.000Z", "nextCredits": 1000000 }
}
```

* `remaining`은 지금 쓸 수 있는 크레딧입니다. 이미 제출한 태스크의 가격은 `reserved`에 보류되어 있으니 다시 빼지 마세요.
* `perCycle`은 요금제가 주기마다 지급하는 크레딧이고, `cycleResetsAt`은 현재 주기가 끝나는 시각입니다. 활성 요금제가 없으면 둘 다 `null`입니다.
* `topUpBalance`는 `remaining`에 든 충전 크레딧과, 그중 가장 먼저 만료되는 날짜와 그날 만료되는 양을 알려 줍니다. 충전 크레딧이 없으면 `null`입니다. 충전 크레딧은 구매 후 3개월 동안 유지되고, 갱신 때 이월되며, 요금제 크레딧을 다 쓴 뒤에 사용됩니다.

하위 계정은 내 크레딧을 쓰므로 하위 계정 키는 `403 SUB_ACCOUNT_FORBIDDEN`을 받습니다. [하위 계정](/ko/sub-accounts.md)을 참고하세요.

## 사용량 확인

`GET /v1/usage`는 UTC 날짜 범위 동안 계정에 청구된 크레딧을 일, 엔진, API 키별로 나눠 반환합니다. 조회에는 크레딧이 들지 않습니다. [크레딧 사용량](/ko/api-reference/usage.md)을 참고하세요.

```bash theme={"theme":"css-variables"}
curl "https://api.querying.ai/v1/usage?from=2026-10-01&to=2026-10-20&groupBy=engine" \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

```json theme={"theme":"css-variables"}
{
  "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`과 `to`는 UTC 날짜이고 두 날짜가 모두 포함됩니다. 기본값은 이번 UTC 달의 첫날과 오늘이며, 범위는 최대 366일입니다.
* `groupBy`는 `day`, `engine`, `key`를 쉼표로 이어 받고 기본값은 `day,engine`입니다. 행에는 고른 기준의 필드가 담기고, 청구가 없는 조합은 행이 없습니다. 맨 위의 `credits`와 `tasks`는 모든 행의 합입니다.
* `groupBy=key`는 크레딧을 쓴 주체를 보여 줍니다. API 키로 보낸 태스크는 `"source": "api"`이고 키의 `id`, `keyPrefix`, `name`, `subAccountId`가 든 `apiKey`가 붙습니다. API 키가 없는 사용은 `source`가 `monitor`(모니터 실행), `playground`, `dashboard` 중 하나이고 `apiKey`는 `null`입니다.
* 사용량은 태스크에 청구된 크레딧을 합산하며, 실패한 태스크는 `0`입니다. 모니터의 경쟁사 분석은 태스크 없이 청구되므로 잔액은 줄지만 사용량에는 나타나지 않습니다.
* [하위 계정](/ko/sub-accounts.md)의 태스크도 내 사용량에 들어가며, `apiKey.subAccountId`가 키를 가진 하위 계정을 알려 줍니다. 하위 계정 하나는 [`GET /v1/sub-accounts/{id}/usage`](/ko/api-reference/sub-accounts/get-usage)로 읽습니다. 하위 계정 키는 `403 SUB_ACCOUNT_FORBIDDEN`을 받습니다.

## 대기열 확인

`GET /v1/async/status`는 계정에서 대기 중이거나 실행 중인 태스크와, 그 태스크가 계산되는 동시 실행 한도를 함께 반환합니다. 조회에는 크레딧이 들지 않습니다. [대기열 상태](/ko/api-reference/queue-status.md)를 참고하세요.

```bash theme={"theme":"css-variables"}
curl https://api.querying.ai/v1/async/status \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

```json theme={"theme":"css-variables"}
{
  "success": true,
  "queuedTasks": 19,
  "processingTasks": 6,
  "priorityBreakdown": [{ "priority": 8, "count": 3 }, { "priority": 1, "count": 16 }],
  "concurrency": { "used": 25, "max": 200 }
}
```

* `concurrency.used`는 `queuedTasks`와 `processingTasks`의 합이며, 요금제의 [동시 실행 한도](#요금제-동시-실행-한도)가 합쳐서 세는 두 값입니다. `max`가 그 한도이므로 `max - used`가 새 태스크를 넣을 수 있는 여유입니다.
* `priorityBreakdown`은 대기 중인 태스크를 제출할 때 보낸 `priority`별로, 높은 값부터 나열합니다.
* 집계에는 한도를 함께 쓰는 하위 계정의 태스크도 들어갑니다. 하위 계정 키는 `403 SUB_ACCOUNT_FORBIDDEN`을 받고, 자기 태스크 수는 [`GET /stats`](/ko/api-reference/stats)로 읽습니다.

## 요금제

| 요금제 | 월 가격 | 월 크레딧 | 동시 실행 태스크 |
| - | - | - | - |
| Free | \$0 | 가입 시 500 | 2 |
| Basic | \$20 | 8,000 | 50 |
| Pro | \$200 | 170,000 | 200 |
| Scale | \$500 | 480,000 | 500 |
| Max | \$1,000 | 1,000,000 | 1,000 |

요금제 비교는 [요금 페이지](https://querying.ai/ko/pricing)에 있습니다.

### 요금제 동시 실행 한도

동시 실행 한도는 계정의 `QUEUED`와 `PROCESSING` 태스크를 합쳐 셉니다. 제출 속도에 대한 한도가 아닙니다. 한도를 넘게 되는 제출은 `details.limit`, `details.active`, `Retry-After`와 함께 `429 PLAN_CONCURRENCY_LIMIT`를 반환합니다. 계약으로 계정에 다른 한도를 둘 수 있고, 상위 계정은 [하위 계정](/ko/sub-accounts.md)의 한도를 정할 수 있습니다.

## 키별·하위 계정별 한도

| 한도 | 설정 위치 | 도달 시 |
| - | - | - |
| API 키의 일일 크레딧 한도 | [대시보드](https://querying.ai/dashboard/keys)의 키 관리, 0.01\~20,000,000 크레딧 | 다음 UTC 자정까지 `429 KEY_DAILY_CREDIT_LIMIT`. `Retry-After`는 그때까지 남은 초입니다. |
| 하위 계정의 `monthlyCreditLimit` | 상위 계정. [하위 계정](/ko/sub-accounts.md)을 참고하세요. | `429 SUB_ACCOUNT_CREDIT_LIMIT` |

키의 일일 한도는 태스크에 필요한 보류액을 셉니다. 그래서 `사용량 + 가격`이 한도를 넘게 되면 태스크가 거부됩니다.

## 요청 속도와 백프레셔

| 한도 | 응답 |
| - | - |
| `/v1/*`에서 `Authorization` 자격 증명당 분당 1,200건 | 엣지의 `429` |
| 출발지 IP당 분당 6,000건 | 엣지의 `429` |
| 한 엔진의 대기열이 가득 참 | `Retry-After`와 함께 `503 QUEUE_BACKPRESSURE` |
| 접수 포화 | `Retry-After`와 함께 `503 SERVER_OVERLOADED` |
| 전체 태스크 대기열이 가득 참 | `Retry-After`와 함께 `503 SERVER_OVERLOADED` |
| 한 엔진이 일시적으로 태스크를 받지 않음 | `Retry-After`와 함께 `503 ENGINE_UNAVAILABLE` |

엣지의 `429`는 API 앞단에서 나오므로 JSON 오류 봉투도 `Retry-After`도 없습니다. 이를 받으면 지수 백오프로 기다리세요. 태스크 제출 엔드포인트의 `429`와 `503`에는 `Retry-After` 헤더(초)가 붙습니다. 코드와 재시도 안내는 [오류](/ko/concepts/errors.md)에 있습니다.

## 대량 제출 속도 조절

**1. 루프 대신 배치**

항목 500개짜리 `POST /v1/async/task/batch` 한 번은 엣지 한도에서 요청 하나로 셉니다. 동시 실행 한도보다 많다면 `POST /v1/batches`를 쓰세요. 서버가 여유가 생기는 대로 항목을 내보냅니다. [배치와 그리드](/ko/concepts/bulk-submission.md)를 참고하세요.

**2. Retry-After 준수**

거부된 태스크를 다시 제출하기 전에 `Retry-After`의 초만큼 기다리세요. 같은 `idempotencyKey`를 다시 쓰면 재시도가 중복을 만들지 않습니다.

**3. 의존 작업은 순서대로**

실행 순서는 보장되지 않습니다. 결과에 의존하는 작업은 앞 태스크가 완료된 뒤에 제출하세요.

**4. 개수 확인**

[`GET /v1/async/status`](/ko/api-reference/queue-status)는 대기 중이거나 실행 중인 태스크를 요금제 한도와 함께 반환하므로 한도 아래로 유지할 수 있습니다. [`GET /stats`](/ko/api-reference/stats)는 최근 24시간 동안 끝난 태스크 수를 더해 줍니다.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.