> ## 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 엔진 질의에는 몇 초에서 몇 분이 걸리므로, 모든 요청은 나중에
가져갈 수 있는 영속적인 큐 태스크가 됩니다.

## 생명주기

```mermaid theme={null}
stateDiagram-v2
    [*] --> QUEUED: POST /v1/async/task
    QUEUED --> PROCESSING: worker claims
    PROCESSING --> COMPLETED: engine answered
    PROCESSING --> FAILED: retries exhausted
    PROCESSING --> QUEUED: transient error, requeued
    COMPLETED --> [*]: polling expires after 24h
    FAILED --> [*]: polling expires after 24h
```

## 상태

<ResponseField name="QUEUED" type="status">
  접수되어 영속 저장된 상태입니다. 워커를 기다립니다.
</ResponseField>

<ResponseField name="PROCESSING" type="status">
  워커가 태스크 lease를 잡고 엔진을 실행하는 중입니다.
</ResponseField>

<ResponseField name="COMPLETED" type="status">
  종료 상태입니다. `response` 필드가 채워집니다.
</ResponseField>

<ResponseField name="FAILED" type="status">
  종료 상태입니다. `error` 필드에 원인이 담깁니다.
</ResponseField>

일시적 실패(엔진 타임아웃, 일시 오류)를 만난 태스크는 `QUEUED`로 돌아가 재시도됩니다. 재시도를
모두 소진해야 `FAILED`로 확정되므로, `PROCESSING → QUEUED` 전환은 정상이며 경보 대상이 아닙니다.

## 우선순위

`priority`는 호환성을 위해 유지되며 태스크 메타데이터에 그대로 돌아옵니다. `1`부터 `10`까지
받고 기본값은 `1`이며, 범위를 벗어난 값은 거부하지 않고 범위 안으로 맞춥니다.

```json theme={null}
{ "taskType": "GEMINI", "priority": 8, "payload": { "prompt": "..." } }
```

실행 순서는 우선순위, 제출 시각, 계정 어느 것으로도 보장되지 않습니다. 앞 작업에 의존하는
작업이라면 앞 태스크가 완료된 뒤에 다음 태스크를 제출하세요. 요금제 동시 실행 한도는 대기 중인
태스크와 처리 중인 태스크 모두에 적용됩니다.

## 보존 기간

종료된 태스크는 **완료 후 24시간 동안** 공개 폴링으로 조회할 수 있습니다. 그 뒤에는
`GET /v1/async/task/{id}`가 존재한 적 없는 id와 똑같이 `404 NOT_FOUND`를 반환합니다. 원본 기록은
영구 보존됩니다. 만료는 공개 폴링과 수동 webhook 재전송을 제한할 뿐 저장을 제한하지 않습니다.
자동 webhook 재시도는 이와 별개로 계속됩니다.

webhook 대신 폴링에 의존한다면 이 기간 안에 넉넉히 결과를 가져가세요.

## Webhook과 폴링 중 선택

Webhook을 권장합니다. 폴링은 복구용 경로입니다.

| | Webhook | 폴링 |
| - | - | - |
| 결과까지 지연 | 완료 즉시 | 폴링 간격만큼 |
| API 부하 | 태스크당 POST 1회 | 태스크마다 폴링 횟수만큼 GET |
| 공개 엔드포인트 필요 | 예 | 아니요 |
| 내 서버 장애 시 | 약 30분 재시도 후 포기 | 24시간 동안 조회 가능 |

견고한 클라이언트는 둘 다 씁니다. Webhook을 빠른 경로로 받고, 소식을 받지 못한 태스크는 보존
기간이 끝나기 전에 폴링으로 맞춰 보세요.