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

# Respostas em segundo plano

> Execute uma solicitação da Responses API de forma assíncrona com o modo em segundo plano no AI Gateway e consulte o ID da resposta até que o processamento seja concluído.

Use a execução em segundo plano quando uma solicitação da **Responses API** precisar retornar antes da conclusão da execução do modelo. Defina `background` como `true` em `POST /v3/router/responses`. O **AI Gateway** armazena a resposta, retorna o ID dela com `status: "queued"` e a processa de forma assíncrona.

Consulte periodicamente `GET /v3/router/responses/{response_id}` com o mesmo ID até que a resposta atinja um status final. Consulte a [referência da Responses API](/docs/pt-BR/reference/responses/create-response.md) para ver o schema completo de solicitação e resposta.

## Início rápido

Os exemplos a seguir enviam uma resposta em segundo plano e, em seguida, fazem consultas periódicas até que o processamento termine. Defina `store` como `true`; respostas em segundo plano exigem respostas armazenadas.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
response=$(curl -sS -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Summarize the background response workflow in one sentence.",
    "background": true,
    "store": true
  }')

response_id=$(printf '%s' "$response" | jq -r '.id')
status=$(printf '%s' "$response" | jq -r '.status')

while [ "$status" = "queued" ] || [ "$status" = "in_progress" ]; do
  sleep 1
  response=$(curl -sS "https://router.toqan.ai/eu/v3/router/responses/$response_id" \
    -H "Authorization: Bearer $TOQAN_API_KEY")
  status=$(printf '%s' "$response" | jq -r '.status')
done

printf '%s\n' "$response"
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const headers = {
  Authorization: `Bearer ${process.env['TOQAN_API_KEY']}`,
  'Content-Type': 'application/json',
};

let response = await fetch('https://router.toqan.ai/eu/v3/router/responses', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    model: 'openai/gpt-5.4-mini',
    input: 'Summarize the background response workflow in one sentence.',
    background: true,
    store: true,
  }),
}).then((result) => result.json());

while (response.status === 'queued' || response.status === 'in_progress') {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  response = await fetch(
    `https://router.toqan.ai/eu/v3/router/responses/${response.id}`,
    { headers },
  ).then((result) => result.json());
}

console.log(response);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import time
import requests

headers = {
    'Authorization': f"Bearer {os.getenv('TOQAN_API_KEY', '')}",
    'Content-Type': 'application/json',
}

response = requests.post(
    'https://router.toqan.ai/eu/v3/router/responses',
    headers=headers,
    json={
        'model': 'openai/gpt-5.4-mini',
        'input': 'Summarize the background response workflow in one sentence.',
        'background': True,
        'store': True,
    },
).json()

while response['status'] in ('queued', 'in_progress'):
    time.sleep(1)
    response = requests.get(
        f"https://router.toqan.ai/eu/v3/router/responses/{response['id']}",
        headers=headers,
    ).json()

print(response)
```

## Ciclo de vida da resposta

A solicitação de criação retorna o objeto de resposta com um `id` estável. Consulte esse mesmo objeto enquanto ele passa pelos seguintes status:

| Status | Significado |
| - | - |
| `queued` | A solicitação foi aceita e está aguardando a execução em segundo plano. |
| `in_progress` | A execução em segundo plano está em andamento. |
| `completed` | A resposta contém a saída concluída. |
| `failed` | A execução foi interrompida com um erro no campo `error`. |
| `incomplete` | A execução terminou sem uma resposta concluída; inspecione `incomplete_details`. |

Respostas concluídas incluem `output` e `completed_at`. Respostas com falha mantêm o ID da resposta, para que o erro possa ser consultado com a mesma solicitação GET.

## Limite de execução e polling

A execução em segundo plano é interrompida após 30 minutos. O limite cobre a execução inteira e substitui qualquer `max_execution_time` em `limits` ou no agente. Uma execução interrompida por ele termina como `failed`, com o motivo em `error`, ou como `incomplete`, com `incomplete_details.reason: "max_time"`, quando o limite é atingido entre chamadas ao modelo.

Nenhum intervalo fixo de polling é exigido. O Início rápido consulta a cada segundo; um intervalo maior funciona para execuções longas. Pare em `completed`, `failed` ou `incomplete`.

## Cancelamento

Respostas em segundo plano não podem ser canceladas: `/v3/router/responses/{response_id}` atende apenas `GET`. Interromper o loop de polling não interrompe a execução, que continua até um status final e permanece disponível para consulta.

## Configuração e limitações

| Campo | Requisito |
| - | - |
| `background` | Defina como `true` para enfileirar a resposta e retornar imediatamente. |
| `store` | Omita este campo ou defina-o como `true`. `store: false` é rejeitado em respostas em segundo plano. |
| `stream` | Omita este campo ou defina-o como `false`. A execução em segundo plano não pode ser combinada com streaming. |

A execução em segundo plano usa o modelo, a entrada, as ferramentas e o schema de resposta padrão da Responses API. O comportamento assíncrono muda o momento em que o resultado fica disponível, e não o formato da resposta final.

> [!NOTE]
>
> Para muitas solicitações offline, envie um [batch](/docs/pt-BR/ai-gateway/features/batches.md). A execução em segundo plano abrange uma única resposta de longa duração.


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