---
title: "Who ranks for a keyword, who links to them, what we sell"
method: GET
path: "/v1/keywords/winners"
tags: ["Research"]
---

# Who ranks for a keyword, who links to them, what we sell

`GET /v1/keywords/winners`

## Request

- Base URL: `https://api.placementapi.com`
- URL: `https://api.placementapi.com/v1/keywords/winners`
- Auth: HTTP bearer

Top 30 ranking domains for a keyword (fresh SERP fetched within a 200/day budget when none under 60 days is held), the domains linking to two or more of them (or to one we carry), and which we carry with the cheapest offer_id, price_credits and verification. `leaders_with_referrers` says how many leaders have been profiled; shared_referrers is over those.

## Query parameters

- `keyword` string, required

## Response `200`

OK

- object
  - `keyword` string
  - `serp_fetched_at` string, nullable
  - `serp_fresh` boolean
  - `leaders` object[]
    - `domain` string
    - `position` integer
    - `url` string
  - `leaders_with_referrers` integer
  - `shared_referrers` object[]
    - `domain` string
    - `leaders_linked` integer
    - `authority_rank` integer, nullable
    - `carried` boolean
    - `offer_id` string, nullable
    - `price_credits` integer, nullable
    - `verification` 'ok' | 'suspect' | 'unverified' | 'null', nullable: Our independent verdict on the claimed authority; no supplier publishes it. 'suspect' = high link authority with little or no organic search presence, which is what a link farm looks like — do not plan around suspect domains. 'ok' = measured, and search presence matches the rating. 'unverified' = not measured yet, which is not a pass.
  - `carried` integer
  - `note` string

## Other responses

- `400`: Malformed request. `error` is `bad_request` (with a zod `detail`), `invalid_json`, or `unknown_parameter` / `unknown_field` (with `unknown[]` and `accepted[]`).
- `401`: Missing, malformed or revoked Bearer credential: `{ error: "unauthorized" }`.
- `429`: `serp_budget_exhausted`: 200 fresh keyword SERPs per day.
- `503`: `server_misconfigured` when the store is not configured; `upstream_unfunded` when the measurement provider's prepaid balance is exhausted (fresh profiles, gap maps and SERPs pause; cached results and catalogue are unaffected); `upstream_unavailable` on a provider error; `payments_unavailable` when card payments are not configured.

---

[API](https://skmtc.dev/placementapi/apis/placement-api.md) · [All operations](https://skmtc.dev/placementapi/apis/placement-api/llms.txt) · [OpenAPI document](https://skmtc.dev/placementapi/apis/placement-api/revisions/fc4e7866eaf7?raw)