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

# Quickstart

> Run your first task with a free test key, then go live.

**1. Create an API key**

Sign in to the [dashboard](https://app.apiforgeo.com) and open **API keys**. Create a **test** key first: it runs in the sandbox and costs nothing.

The key shows once. Store it in an environment variable:

```bash theme={null}
export AFG_API_KEY="afg_test_..."
```

**2. Create a task**

Send a prompt, a model, a country and a language:

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

```python Python theme={null}
import os, requests

headers = {"Authorization": f"Bearer {os.environ['AFG_API_KEY']}"}
res = requests.post(
    "https://api.apiforgeo.com/v1/tasks",
    headers=headers,
    json={"prompt": "best running shoes for flat feet", "model": "chatgpt", "country": "US", "language": "en"},
)
task = res.json()
if not res.ok:
    raise SystemExit(task["error"]["message"])
print(task["id"])
```

```javascript Node.js theme={null}
const headers = { Authorization: `Bearer ${process.env.AFG_API_KEY}`, "Content-Type": "application/json" };
const res = await fetch("https://api.apiforgeo.com/v1/tasks", {
  method: "POST",
  headers,
  body: JSON.stringify({ prompt: "best running shoes for flat feet", model: "chatgpt", country: "US", language: "en" }),
});
let task = await res.json();
if (!res.ok) throw new Error(task.error.message);
console.log(task.id);
```

The API answers `201 Created` with the task. It is `queued`, and `result` is `null` for now:

```json theme={null}
{
  "id": "task_0193f2a7b8c77d1e9f3a4b5c6d7e8f90",
  "status": "queued",
  "mode": "test",
  "prompt": "best running shoes for flat feet",
  "model": "chatgpt",
  "country": "US",
  "language": "en",
  "costMicros": 0,
  "result": null
}
```

A test key costs `0`. A live key costs `13000` micro-dollars (\$0.013).

**3. Read the result**

Read the task until its `status` is `completed` or `failed`. In the sandbox, that takes about 15 seconds.

```bash cURL theme={null}
curl https://api.apiforgeo.com/v1/tasks/task_0193f2a7b8c77d1e9f3a4b5c6d7e8f90 \
  -H "Authorization: Bearer $AFG_API_KEY"
```

```python Python theme={null}
import time

while task["status"] in ("queued", "processing"):
    time.sleep(5)
    task = requests.get(f"https://api.apiforgeo.com/v1/tasks/{task['id']}", headers=headers).json()

# A failed task has an error, and no result.
print(task["result"]["entities"] if task["status"] == "completed" else task["error"])
```

```javascript Node.js theme={null}
while (task.status === "queued" || task.status === "processing") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  task = await fetch(`https://api.apiforgeo.com/v1/tasks/${task.id}`, { headers }).then((r) => r.json());
}
// A failed task has an error, and no result.
console.log(task.status === "completed" ? task.result.entities : task.error);
```

A completed task has a `result` with the answer, entities, sources, fan-outs, products and ads. See [Task results](https://docs.apiforgeo.com/concepts/task-results.md).

> [!TIP]
>
> Polling is fine to start. In production, pass a `webhookUrl` and let the result come to you. See [Webhooks](https://docs.apiforgeo.com/concepts/webhooks.md).

**4. Go live**

In the dashboard, open **Billing**:

1. Add your billing details and a card. The first card gives your organization a free \$1.00 trial credit.
2. Top up your balance. A top-up is \$5 or more.
3. Create a **live** key (`afg_live_...`) and use it in place of the test key.

Live tasks run on the real models and cost \$0.013 each. See [Pricing](https://docs.apiforgeo.com/concepts/pricing.md).

## Test the edge cases

In the sandbox, the prompt controls the outcome:

| Prompt contains | Outcome |
| - | - |
| `[fail]` | The task fails. |
| `[slow]` | The task takes about 2 minutes. |
| Anything else | The task completes in about 15 seconds, with a sample result. |

For example, `"prompt": "best CRM [fail]"` lets you test your failure path.


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