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

# Start a suggest job

> Collect suggestions for up to 10,000 keywords in one job, with a delivery deadline of 6, 60 or 300 seconds.

`POST https://rankfield.dev/v1/bing/suggest/jobs`

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

```python Python
import requests

response = requests.post(
    "https://rankfield.dev/v1/bing/suggest/jobs",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": "keywords-2026-10-25"},
    json={"queries": ["keyword research", "seo tools"], "delivery": "priority"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/bing/suggest/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "Idempotency-Key": "keywords-2026-10-25",
  },
  body: JSON.stringify({"queries":["keyword research","seo tools"],"delivery":"priority"}),
});
console.log(await response.json());
```

```json 202
{
  "id": "1e3aff33-2831-4112-b934-cb727ab6c23a",
  "status": "running",
  "total": 2,
  "completed": 0,
  "succeeded": 0,
  "failed": 0,
  "createdAt": 1792938856915,
  "deadlineAt": 1792938916915,
  "completedAt": null,
  "delivery": "priority",
  "keywordCount": 2,
  "workUnits": 2
}
```

```json 400
{
  "error": "Supply an Idempotency-Key of 1–128 letters, numbers, dots, colons, underscores or hyphens"
}
```

The same request works on every engine: POST to `{base path}/jobs`.

| Engine | Base path |
|---|---|
| Bing | `/v1/bing/suggest` |
| DuckDuckGo | `/v1/ddg/suggest` |
| Yahoo | `/v1/yahoo/search-predictions` |

## Parameters

### Headers

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `Authorization` | string | Yes | – | `Bearer` followed by your API key. See [Authentication](/docs/get-started/authentication). |
| `Idempotency-Key` | string | Yes | – | 1–128 letters, numbers, dots, colons, underscores or hyphens. Use a new one for each new job. Sending the same key with the same body again returns the same job instead of a new one. |

### Body

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `queries` | string[] | Yes | – | 1–10,000 keywords, each 1–200 printable characters. |
| `delivery` | string | No | `standard` | When the whole job must be done: `live` (6 seconds), `priority` (60 seconds) or `standard` (300 seconds). |
| `market` | string | No | `en-US` | Bing only. One market for every keyword: see [Get Bing suggestions](/docs/suggest/get-bing-suggestions). |
| `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. |

## Delivery

A deadline covers the whole job, retries included. A job that cannot finish in time under current load is refused with `429` and a `Retry-After`, rather than accepted and finished late. Try again later or choose a longer tier. Keywords not finished by the deadline end with status `504`.

## Response

`202` with the job, as in [Get a suggest job](/docs/suggest/get-a-job). Sending the same `Idempotency-Key` and body again answers `200` with the same job and an `Idempotency-Replayed: true` header.

## Errors

| Status | When |
|---|---|
| 400 | No `Idempotency-Key`, more than 10,000 keywords, an invalid keyword, an unknown `delivery` or `freshness`, an unsupported `market`, or locale options (`language`, `country`, `client`, `cursor`, and `kl` on DuckDuckGo) on DuckDuckGo and Yahoo. |
| 401 | No valid API key. |
| 409 | The `Idempotency-Key` was used before with a different body. |
| 429 | The deadline can't be met under current load: the engine's capacity or the time left. Wait for `Retry-After`, or choose a longer tier. |

## Limits

Up to 10,000 keywords per job. No per-key limits for now. When an engine is busy it answers `429`, or `503` while it cools down, with `Retry-After`.

## MCP

On the [MCP server](/docs/agents/mcp-server), the tools for this are `start_bing_suggest_job`, `start_duckduckgo_suggest_job` and `start_yahoo_search_predictions_job`.