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.

POSThttps://rankfield.dev/v1/bing/suggest/jobs

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"}'

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())

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());

{
  "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
}

{
  "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.
`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.
`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. 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, the tools for this are start_bing_suggest_job, start_duckduckgo_suggest_job and start_yahoo_search_predictions_job.

Start a suggest job

#Parameters

#Headers

#Body

#Delivery

#Response

#Errors

#Limits

#MCP