> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# How do I find a competitor's ranking keywords? Are positions live?

> Query POST /v1/seo/ranked-keywords with a competitor domain, market, and optional contains filter to inspect historical snapshot rankings timestamped by position_seen_at.

Call `POST /v1/seo/ranked-keywords` with the competitor's `domain` and target market (`country` and `language`) to list keywords the domain ranks for, ordered by highest search volume first. Returned rankings are recorded snapshots rather than live search results; each row's `position_seen_at` shows when the position was observed.

## Filter by topic and control row spend

Use `contains` (up to 80 characters, case-insensitive; `%` and `_` are rejected) with a small `limit` (`1–1000`, default `100`) to isolate a topic before paginating with `offset`.

```bash
curl -sS https://api.beatapi.io/v1/seo/ranked-keywords \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"domain":"example.com","country":"us","language":"en","contains":"descale","limit":20}'
```

Inspect `keyword`, `position` (organic rank), `absolute_position` (rank across all SERP elements), `url`, `search_volume`, `search_traffic_estimate`, and `position_seen_at` on each returned row.

## Scope limits for single-page analysis

`POST /v1/seo/ranked-keywords` always evaluates the whole domain: passing a full page URL reduces the input to its domain and strips a leading `www.`. To audit one landing page, filter returned rows client-side by `url`, record the query scope (`domain`, `contains`, `limit`, `offset`), and keep `position_seen_at` next to every reported rank because snapshots can be weeks or months old.

## Contracts and related questions

Before sending a paid request, inspect the SEO contracts for free: `data:seo.keyword_overview`, `data:seo.ranked_keywords`, `data:seo.top_pages`, `data:seo.backlinks`.

[Back to SEO questions](/faq/seo).