> ## 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.

# AI 검색 데이터 API 빠른 시작

> 태스크를 제출하고 webhook 또는 폴링으로 결과를 받습니다.

[시작 가이드](https://querying.ai/ko/guides/quickstart) · [API 요금제와 크레딧](https://querying.ai/ko/pricing)

## 1. 인증 정보 설정

```bash theme={null}
export BASE="https://api.querying.ai"
export API_KEY="<your-key>"
```

## 2. 태스크 제출

Gemini에 질문해 봅니다. `taskType`은 엔진을 고르고, `payload.prompt`는 질문 내용입니다.

```bash theme={null}
curl -X POST "$BASE/v1/async/task" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "GEMINI",
    "payload": { "prompt": "best wireless earbuds 2026", "country": "US" }
  }'
```

태스크가 접수되어 큐에 들어갑니다.

```json theme={null}
{
  "success": true,
  "task": {
    "id": "8f2c1e40-...",
    "taskType": "GEMINI",
    "status": "QUEUED",
    "priority": 1,
    "createdAt": "2026-07-09T04:12:00.000Z"
  },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 }
}
```

<Note>
  `credits`는 응답 봉투의 일부입니다. 제출과 폴링 응답에서는 항상 0이고, webhook은 엔진별
  크레딧 비용을 알려줍니다(공개 답변 엔진은 1–2 크레딧, Prompt Research는 12 크레딧, Source Influence는 별도로 계량합니다).
  잔액은 대시보드에서 확인할 수 있습니다.
</Note>

## 3. 결과 수집

<Tabs>
  <Tab title="Webhook (권장)">
    제출할 때 `webhook.url`을 추가하세요. 태스크가 종료 상태에 도달하면 전체 결과를 그 주소로
    POST하므로 폴링할 필요가 없습니다.

    ```bash theme={null}
    curl -X POST "$BASE/v1/async/task" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "taskType": "GEMINI",
        "payload": { "prompt": "best wireless earbuds 2026" },
        "webhook": { "url": "https://your-server.example.com/hook" }
      }'
    ```

    엔드포인트는 `{ task, credits, response }`를 받습니다. 전달과 재시도 계약은
    [Webhook](/ko/concepts/webhooks)을 참고하세요.
  </Tab>

  <Tab title="폴링">
    `webhook`을 생략하고 id로 태스크를 폴링합니다. 태스크가 종료 상태가 되기 전에는
    `response`가 없습니다.

    ```bash theme={null}
    curl "$BASE/v1/async/task/8f2c1e40-..." \
      -H "Authorization: Bearer $API_KEY"
    ```

    ```json theme={null}
    {
      "success": true,
      "task": { "id": "8f2c1e40-...", "status": "COMPLETED", "...": "..." },
      "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
      "response": {
        "text": "The best wireless earbuds in 2026 are ...",
        "sources": [{ "position": 1, "url": "https://...", "label": "..." }]
      }
    }
    ```

    <Warning>
      공개 폴링은 완료 후 24시간 동안 가능합니다. 그 안에 폴링하지 않으면 완료된 태스크도
      만료로 404를 반환합니다.
    </Warning>
  </Tab>
</Tabs>

## 4. 대량 제출

`POST /v1/async/task/batch`는 같은 태스크 객체의 JSON **배열**을 요청당 최대 500개까지 받습니다.
한 배치 안에서 엔진을 자유롭게 섞을 수 있습니다.

```bash theme={null}
curl -X POST "$BASE/v1/async/task/batch" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    { "taskType": "GEMINI",     "payload": { "prompt": "best wireless earbuds 2026" } },
    { "taskType": "PERPLEXITY", "payload": { "prompt": "best wireless earbuds 2026" } },
    { "taskType": "GOOGLE",     "payload": { "query":  "best wireless earbuds 2026" } }
  ]'
```

형식이 올바른 배치 요청은 항상 `200`을 반환합니다. 개별 실패는 `results[].success = false`로
나타나므로 태스크 하나가 잘못돼도 나머지는 영향을 받지 않습니다.
[배치 제출](/ko/api-reference/create-task-batch)을 참고하세요.

<Note>
  Google 계열 엔진(`GOOGLE`, `AIMODE`, `NAVER_*`)은 `payload.query`를 읽고, LLM 엔진은
  `payload.prompt`를 읽습니다. 둘 중 하나만 있어도 검증은 통과하지만, 엔진은 자기가 기대하는
  필드를 먼저 읽습니다.
</Note>

## 다음 단계

<CardGroup cols={2}>
  <Card title="엔진 고르기" icon="cpu" href="/ko/engines/overview">
    모든 `taskType`과 각 엔진이 반환하는 내용.
  </Card>

  <Card title="실패 처리" icon="triangle-alert" href="/ko/concepts/errors">
    오류 코드, 상태 코드, 재시도할 수 있는 경우.
  </Card>
</CardGroup>