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

# Tasks

> The life of a task, safe retries, your own metadata, and lists.

A task is one prompt, sent to one model, in one country and one language.

## Lifecycle

| `status` | Meaning |
| - | - |
| `queued` | Charged and waiting. `startedAt` is null. |
| `processing` | The model is answering. |
| `completed` | The result is ready. `completedAt` and `resultExpiresAt` are set. |
| `failed` | No result. `error` says why, and a live task is refunded (`refunded: true`). |

`completed` and `failed` are final. A task does not change after it gets there.

To know when a task ends, poll [`GET /v1/tasks/{taskId}`](https://docs.apiforgeo.com/api-reference/get-a-task) every few seconds, or pass a `webhookUrl`. See [Webhooks](https://docs.apiforgeo.com/concepts/webhooks.md).

## Create a task

```json theme={null}
{
  "prompt": "best running shoes for flat feet",
  "model": "chatgpt",
  "country": "US",
  "language": "en",
  "webhookUrl": "https://example.com/hooks/apiforgeo",
  "metadata": { "campaign": "q4", "promptSetId": "running" }
}
```

| Field | Rule |
| - | - |
| `prompt` | 1 to 2,000 characters. |
| `model` | An `id` from [`GET /v1/models`](https://docs.apiforgeo.com/api-reference/list-models), for example `chatgpt`. |
| `country` | Two upper-case letters, for example `US`, `FR`, `DE`. The model must run there. |
| `language` | A language code, for example `en`, `fr`, `de`. |
| `webhookUrl` | Optional. `https` only. Gets this task's `task.completed` or `task.failed`. |
| `metadata` | Optional. Your own string labels, up to 500 characters each. They come back as you gave them. |
| `enrichments` | Optional. Accepted for later. Today every task gets every enrichment. |

`GET /v1/models` lists the countries and languages. A model with `countries: null` runs in every country of the list.

## Retry safely with an Idempotency-Key

A network error can hide whether a task was created. To retry without paying twice, send an `Idempotency-Key` header:

```bash theme={null}
curl https://api.apiforgeo.com/v1/tasks \
  -H "Authorization: Bearer $AFG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: running-2026-11-19-chatgpt-US" \
  -d '{"prompt":"best running shoes for flat feet","model":"chatgpt","country":"US","language":"en"}'
```

* The first request creates the task: `201 Created`.
* The same key with the same body returns that same task: `200 OK`. It is charged once.
* The same key with a different body is refused: `409` with the code `idempotency_key_reused`. `details.taskId` names the first task.

Use a key that names the work, for example the prompt set, the date, the model and the country. A key is 1 to 255 characters.

## List tasks

[`GET /v1/tasks`](https://docs.apiforgeo.com/api-reference/list-tasks) lists your organization's tasks, newest first. It filters by `status`, `model`, `apiKeyId`, `from`, `to`, and `q` (a task id or words of the prompt). `status=running` means `queued` or `processing`.

A list gives up to `limit` tasks (50 by default, 100 at most), without their results. To read the next page, pass `nextCursor` as `cursor`. A null `nextCursor` means the last page.

```bash theme={null}
curl "https://api.apiforgeo.com/v1/tasks?status=failed&limit=100" \
  -H "Authorization: Bearer $AFG_API_KEY"
```

To get a result, read the task by its id.


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