Get suggest job results

Read a suggest job's keywords as they finish, each with its engine answer, and page through them with a cursor.

GEThttps://rankfield.dev/v1/bing/suggest/jobs/{id}/results

curl 'https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a/results?cursor=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

import requests

response = requests.get(
    "https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a/results?cursor=0",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())

const response = await fetch("https://rankfield.dev/v1/bing/suggest/jobs/1e3aff33-2831-4112-b934-cb727ab6c23a/results?cursor=0", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());

200

{
  "id": "1e3aff33-2831-4112-b934-cb727ab6c23a",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "succeeded": 2,
  "failed": 0,
  "createdAt": 1792938856915,
  "deadlineAt": 1792938916915,
  "completedAt": 1792938857066,
  "delivery": "priority",
  "keywordCount": 2,
  "workUnits": 2,
  "cursor": 2,
  "hasMore": false,
  "items": [
    {
      "index": 0,
      "query": "keyword research",
      "market": "en-US",
      "status": 200,
      "result": {
        "source": "bing-suggest",
        "query": "keyword research",
        "market": "en-US",
        "count": 17,
        "suggestions": ["keyword research", "keyword research tool", "keyword research tool free"]
      },
      "attempts": 1,
      "cache": "hit",
      "ageSeconds": 17,
      "durationMs": 0
    }
  ]
}

Parameters

Headers

Name	Type	Required	Default	Description
`Authorization`	string	Yes	–	`Bearer` followed by your API key. See Authentication.

Path parameters

Name	Type	Required	Default	Description
`id`	string	Yes	–	The job id from Start a suggest job.

Query parameters

Name	Type	Required	Default	Description
`cursor`	integer	No	`0`	Where to continue: the `cursor` of the previous answer.
`limit`	integer	No	`100`	Items per answer, 1–500.

Read results

Start with cursor=0. Read items, then ask again with the returned cursor until status is no longer running and hasMore is false. Items arrive in the order they finish; index is the keyword's position in your queries, from 0.

Field	Type	Description
`items[].index`	integer	Position in `queries`.
`items[].query`, `market`	string	The keyword and market.
`items[].status`	integer	`200`, or the error status for this keyword: `499` after a cancel, `504` when it was not finished by the deadline.
`items[].result`	object	The same answer as the single-keyword GET.
`items[].attempts`	integer	Tries it took.
`items[].cache`, `ageSeconds`	string, integer	Whether a stored answer was used, and its age.
`cursor`	integer	Where to continue.
`hasMore`	boolean	Whether more finished items are ready to read now. While the job runs and you have caught up, it is `false`.

Errors

Status	When
400	`cursor` or `limit` is invalid.
401	No valid API key.
404	No job with this id for this key.

MCP

On the MCP server, the tools for this are get_bing_suggest_results, get_duckduckgo_suggest_results and get_yahoo_search_predictions_results.