# DuckDuckGo Suggest API

> Returns the suggestions DuckDuckGo shows as people type a keyword. One keyword per GET, or up to 10,000 in a batch job.

- Page: https://rankfield.dev/endpoints/duckduckgo-suggest
- Full reference: https://rankfield.dev/docs/suggest/get-duckduckgo-suggestions

## Request

`GET https://rankfield.dev/v1/ddg/suggest?query={keyword}`

Send `Authorization: Bearer YOUR_API_KEY`. Get a free key at https://rankfield.dev/?tab=key#playground (no account).

```bash
curl "https://rankfield.dev/v1/ddg/suggest?query=seo%20tools" \
  -H "Authorization: Bearer $RANKFIELD_API_KEY"
```

Response:

```json
{
  "source": "ddg-suggest",
  "query": "seo tools",
  "market": "default",
  "endpoint": "ac-list",
  "collectedAt": "2026-10-25T14:34:22.660Z",
  "count": 8,
  "suggestions": [
    "seo tools",
    "seo tools plagiarism checker",
    "seo tools free",
    "seo tools meaning",
    …
  ]
}
```

## Parameters

| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
| `query` | query | string | yes |  | The keyword, 1 to 200 printable characters. |

## Response

| Field | Type | Description |
|---|---|---|
| `source` | string | `ddg-suggest`. |
| `query, market` | string | What you asked; `market` is `default`. |
| `collectedAt` | string | When DuckDuckGo answered (UTC). Answers may be served from a short cache. |
| `count` | integer | How many suggestions came back. |
| `suggestions` | array of strings | In DuckDuckGo's order. |

## Errors

Errors come as `{"error":"…"}` with the HTTP status.

| Status | When |
|---|---|
| 400 | The query is empty or too long (`{"error":"query must contain 1–200 printable characters"}`), or a job holds more than 10,000 keywords (`Supply 1–10000 queries`). |
| 401 | The key is missing, unknown or revoked. |
| 429 | The engine is busy (its request budget is full for the moment), or a job's deadline cannot be met (`capacityLimited: true`). Wait for `Retry-After`. |
| 503 | Collection is paused, cooling down, timed out or unavailable. Wait for `Retry-After`. |

## Price and limits

- Free; no per-call charge.
- No per-key limits for now. Each job takes up to 10,000 keywords, and you can run as many jobs as you like. When an engine is busy it answers `429` or `503` with `Retry-After`.
- `GET …/usage` shows the keywords you sent today.

## Up to 10,000 keywords in one job

`POST /v1/ddg/suggest/jobs` with a unique `Idempotency-Key` header and `{"queries":[…],"delivery":"priority"}`. `delivery` sets how fast the whole batch must finish: `live` 6 seconds, `priority` 60 seconds, `standard` 300 seconds (the default). A batch that cannot meet it answers `429` with `capacityLimited: true` and `Retry-After`: retry later or pick a longer tier.

Follow `GET /v1/ddg/suggest/jobs/{id}`, then read `GET /v1/ddg/suggest/jobs/{id}/results?cursor=0` and keep passing the returned `cursor` while `hasMore` is true. Results arrive as they finish; each carries its `index` in your list. `POST /v1/ddg/suggest/jobs/{id}/cancel` stops a job.

Reference: https://rankfield.dev/docs/suggest/start-a-job

```bash
curl -X POST "https://rankfield.dev/v1/ddg/suggest/jobs" \
  -H "Authorization: Bearer $RANKFIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kw-2026-10-25" \
  -d '{"queries":["seo tools","keyword research"],"delivery":"priority"}'
```

## Notes

- Suggestions show what people type, not how often: they are not search volumes.

## MCP

Tools on https://rankfield.dev/mcp: `get_duckduckgo_suggestions`, `start_duckduckgo_suggest_job`, `get_duckduckgo_suggest_results`.