> ## 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 Yahoo Search Predictions

> Get the search predictions Yahoo shows for a keyword, as a JSON list with the time they were collected.

`GET https://rankfield.dev/v1/yahoo/search-predictions?query={keyword}`

```bash cURL
curl 'https://rankfield.dev/v1/yahoo/search-predictions?query=seo%20tools' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python
import requests

response = requests.get(
    "https://rankfield.dev/v1/yahoo/search-predictions?query=seo%20tools",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(response.json())
```

```javascript JavaScript
const response = await fetch("https://rankfield.dev/v1/yahoo/search-predictions?query=seo%20tools", {
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
  },
});
console.log(await response.json());
```

```json 200
{
  "source": "yahoo-search-predictions",
  "query": "seo tools",
  "market": "default",
  "endpoint": "gossip-us-fp",
  "collectedAt": "2026-10-25T14:34:16.607Z",
  "count": 10,
  "predictions": [
    "seo tools plagiarism checker",
    "seo tools free",
    "seo tools adda",
    "seo tools meaning",
    "seo tools for website",
    "seo tools list",
    "seo tools plagiarism",
    "seo tools centre paraphrasing tool",
    "seo tools group buy",
    "seo tools bd"
  ]
}
```

```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 | `yahoo-search-predictions`. |
| `query` | string | The keyword as it was sent to the engine. |
| `market` | string | `default`. |
| `endpoint` | string | Which Yahoo source answered. |
| `collectedAt` | string | When the predictions were collected (UTC). |
| `count` | integer | How many entries `predictions` holds. |
| `predictions` | string[] | The engine's list, in its order. |

The list is called `predictions`, not `suggestions`. Yahoo returns no predictions for some keywords: `count` is then `0` and the list is empty. `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 | Yahoo answered with an error, or with data that couldn't be read. |
| 503 | Yahoo 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_yahoo_search_predictions`.