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

# Get DuckDuckGo suggestions

> Get the autocomplete suggestions DuckDuckGo shows for a keyword, as a JSON list with the time they were collected.

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

```bash cURL
curl 'https://rankfield.dev/v1/ddg/suggest?query=keyword%20research' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/ddg/suggest?query=keyword%20research",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/ddg/suggest?query=keyword%20research", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "source": "ddg-suggest",
  "query": "keyword research",
  "market": "default",
  "endpoint": "ac-list",
  "collectedAt": "2026-10-25T14:34:00.361Z",
  "count": 8,
  "suggestions": [
    "keyword research",
    "keyword research tool free",
    "keyword research tips",
    "keyword research free",
    "keyword research report",
    "keyword research tools seo",
    "keyword researcher tool",
    "keyword research and analysis"
  ]
}
```

```json 401
{
  "error": "A valid API key is required"
}
```

One keyword per request, answered at once. For keyword lists, [start a job](/docs/suggest/start-a-job).

## Parameters

### Headers

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `Authorization` | string | Yes | – | `Bearer` followed by your API key. See [Authentication](/docs/get-started/authentication). |

### Query parameters

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | string | Yes | – | The keyword, 1–200 printable characters. URL-encode it. |
| `freshness` | string | No | `fresh` | `fresh` may reuse an answer stored in the last 5 minutes (30 seconds if the list was empty); otherwise it asks the engine. `allow-stale` may also return an answer up to 35 minutes old, marked with a `Warning: 110 - "Response is stale"` header, and refreshes it in the background. |

## Response

| Field | Type | Description |
|---|---|---|
| `source` | string | `ddg-suggest`. |
| `query` | string | The keyword as it was sent to the engine. |
| `market` | string | `default`. |
| `endpoint` | string | Which DuckDuckGo source answered. |
| `collectedAt` | string | When the suggestions were collected (UTC). |
| `count` | integer | How many entries `suggestions` holds. |
| `suggestions` | string[] | The engine's list, in its order. |

DuckDuckGo has one market: `market=default`, or no market, is accepted; any other value or locale option answers `400`. Suggestions are what the engine shows while someone types. They are not search volumes.

## Errors

| Status | When |
|---|---|
| 400 | `query` is missing, empty, over 200 characters, or another parameter is invalid. |
| 401 | No valid API key. |
| 429 | The engine is busy: its collection budget is full for the moment. Wait for `Retry-After`. |
| 502 | DuckDuckGo answered with an error, or with data that couldn't be read. |
| 503 | DuckDuckGo collection is paused, cooling down, timed out or unavailable. Retry after `Retry-After`. |

## Limits

No per-key limits for now. When an engine is busy it answers `429`, or `503` while it cools down, with `Retry-After`. [Get usage and capacity](/docs/suggest/get-usage-and-capacity) shows what your key has used.

## MCP

On the [MCP server](/docs/agents/mcp-server), the tool for this is `get_duckduckgo_suggestions`.