AI 검색 데이터 API 빠른 시작

1. 인증 정보 설정

export BASE="https://api.querying.ai"
export API_KEY="<your-key>"

2. 태스크 제출

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

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" }
  }'

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

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

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

3. 결과 수집

Webhook (권장)
폴링

제출할 때 webhook.url을 추가하세요. 태스크가 종료 상태에 도달하면 전체 결과를 그 주소로 POST하므로 폴링할 필요가 없습니다.

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을 참고하세요.

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

curl "$BASE/v1/async/task/8f2c1e40-..." \
  -H "Authorization: Bearer $API_KEY"

{
  "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": "..." }]
  }
}

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

4. 대량 제출

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

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로 나타나므로 태스크 하나가 잘못돼도 나머지는 영향을 받지 않습니다. 배치 제출을 참고하세요.

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

다음 단계

엔진 고르기

모든 taskType과 각 엔진이 반환하는 내용.

실패 처리

오류 코드, 상태 코드, 재시도할 수 있는 경우.

시작하기

핵심 개념

엔진

Source Influence

Prompt Research

GEO 모니터링

마이그레이션

AI 검색 데이터 API 빠른 시작

1. 인증 정보 설정

2. 태스크 제출

3. 결과 수집

4. 대량 제출

다음 단계

엔진 고르기

실패 처리

​1. 인증 정보 설정

​2. 태스크 제출

​3. 결과 수집

​4. 대량 제출

​다음 단계

엔진 고르기

실패 처리

1. 인증 정보 설정

2. 태스크 제출

3. 결과 수집

4. 대량 제출

다음 단계