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

# Início rápido da API de dados de busca com IA

> Envie uma tarefa e receba o resultado, por webhook ou por polling.

[Guia de início](https://querying.ai/pt/guides/quickstart) · [Planos e créditos da API](https://querying.ai/pt/pricing)

## 1. Defina suas credenciais

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

## 2. Envie uma tarefa

Faça uma pergunta ao Gemini. `taskType` escolhe o mecanismo; `payload.prompt` é o que você pergunta.

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

A tarefa é aceita e entra na fila:

```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` faz parte do envelope de resposta. No envio e no polling ele é sempre zero; o webhook informa o custo em
  créditos de cada mecanismo (1–2 créditos para os mecanismos de resposta públicos e 12 para o Prompt Research; o Source Influence é medido à parte).
  Os saldos ficam visíveis no painel.
</Note>

## 3. Colete o resultado

<Tabs>
  <Tab title="Webhook (recomendado)">
    Adicione `webhook.url` ao enviar. Quando a tarefa chega a um estado final, enviamos o resultado completo por POST
    para esse endereço, e você nunca precisa fazer polling.

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

    Seu endpoint recebe `{ task, credits, response }`. Veja [Webhooks](/pt/concepts/webhooks) para o contrato de
    entrega e novas tentativas.
  </Tab>

  <Tab title="Polling">
    Omita `webhook` e consulte a tarefa pelo id. `response` fica ausente até a tarefa terminar.

    ```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>
      O polling público fica disponível por 24 horas após a conclusão. Consulte dentro desse prazo, ou uma tarefa
      concluída retornará 404 por ter expirado.
    </Warning>
  </Tab>
</Tabs>

## 4. Envie em lote

`POST /v1/async/task/batch` aceita um **array** JSON com os mesmos objetos de tarefa, até 500 por requisição. Você pode
misturar mecanismos livremente em um lote.

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

Um lote bem formado sempre retorna `200`. Falhas individuais aparecem como `results[].success = false`, então uma
tarefa com problema nunca derruba as demais. Veja [Envio em lote](/pt/api-reference/create-task-batch).

<Note>
  Os mecanismos da família Google (`GOOGLE`, `AIMODE`, `NAVER_*`) leem `payload.query`. Os mecanismos LLM leem
  `payload.prompt`. Qualquer um dos dois passa na validação, mas cada mecanismo lê primeiro o campo que espera.
</Note>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Escolha um mecanismo" icon="cpu" href="/pt/engines/overview">
    Cada `taskType` e o que ele retorna.
  </Card>

  <Card title="Trate as falhas" icon="triangle-alert" href="/pt/concepts/errors">
    Códigos de erro, códigos de status e o que pode ser repetido.
  </Card>
</CardGroup>