# Get AI answers

`POST https://api.dataforgeo.dev/v1/geo/answer` · all plans

Get AI answers for one prompt across engines, with brand mentions, citations and competitor entities marked. Available on all plans.

### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `prompt` | string | Yes | The question to ask, up to 2,000 characters |
| `engines` | string[] | Yes | Engine ids. See Engines & locations |
| `brand` | string | No | Brand to detect. Omit to get answers and entities only |
| `brand_variants` | string[] | No | Brand aliases, e.g. katakana or English names |
| `competitors` | string[] | No | Competitor names, up to 20 |
| `location` | string | No | Country code. Default US |
| `language` | string | No | Language tag. Inferred from location |
| `samples` | integer | No | Samples per engine, 1–10. Default 1 |
| `fresh` | boolean | No | true skips the cache. Default false |
| `async` | boolean | No | true returns a job_id immediately. See Async jobs |
| `webhook_url` | string | No | URL to call when the async job finishes |

### Example request

```bash
curl https://api.dataforgeo.dev/v1/geo/answer \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "prompt": "东京有哪些适合家庭入住的民宿？",
    "engines": [
      "chatgpt"
    ],
    "brand": "晓宅",
    "location": "JP",
    "language": "zh-CN"
  }'
```

### Example response

```json
{
  "request_id": "req_8f2c1a",
  "prompt": "东京有哪些适合家庭入住的民宿？",
  "credits_used": 1,
  "answers": [
    {
      "engine": "chatgpt",
      "sample": 1,
      "status": "ok",
      "cached": false,
      "generated_at": "2026-11-02T00:31:12Z",
      "text": "……",
      "brand": {
        "mentioned": true,
        "mention_count": 2,
        "first_position": 3,
        "sentiment": "positive"
      },
      "entities": [
        {
          "name": "晓宅",
          "type": "brand",
          "position": 3,
          "is_competitor": false
        },
        {
          "name": "Example Stay",
          "type": "brand",
          "position": 1,
          "is_competitor": true
        }
      ],
      "citations": [
        {
          "url": "https://example.com/guide",
          "domain": "example.com",
          "position": 1,
          "is_brand_domain": false
        }
      ]
    }
  ]
}
```

- status is ok, no_answer, timeout or failed. The last three are free.
- When status is timeout or failed, the answer carries an error field with the reason (values below). ok and no_answer answers have no error field.
- first_position is where the brand first appears in the answer’s recommendation list, or null.

### The answer error field

| error | Meaning |
| --- | --- |
| `upstream_timeout` | The engine did not answer within the time limit (retries included) |
| `upstream_error` | The engine returned an error and still failed after automatic retries |
| `engine_unavailable` | The engine is temporarily unavailable and was not called. Check /v1/status |

### Example failed answer

```json
{
  "engine": "grok",
  "sample": 1,
  "status": "failed",
  "error": "engine_unavailable",
  "cached": false
}
```