SEO API
Twelve tools give an application or an agent SEO data: how much a keyword is searched and how hard it is to rank for, which keywords and pages bring a domain its search traffic, who competes with it, who links to it, its Domain Rating, and how many visits the site gets. Each tool is one POST under /v1/seo/, uses your BeatAPI API key and answers in one response. Agents reach the same tools as capabilities.
Quick start
Authentication
Send your BeatAPI API key on every call as Authorization: Bearer <key>; the key works with or without the sk- prefix. Create one in Dashboard → API Keys. All tools live on https://api.beatapi.io and spend your account balance.
Choose a tool
For Domain Rating and total site visits, see Domain Rating and site traffic.
There is no live results-page tool. To check a domain’s position for a keyword, call ranked-keywords with contains. That is the last recorded position, not a live one.
Country and language
country and language choose the market: Google search in that country, in that language. The keyword tools, domain-overview, ranked-keywords, top-pages and competitors take them. The backlink tools have no market and reject both fields.
A country or language outside the list is rejected with 400 bad_request, and the message says what the market has: language 'de' is not covered in us; use one of: en, es.
Limit and offset
keyword-ideas, ranked-keywords, top-pages, competitors and backlinks return pages of rows.
These responses repeat limit and offset, and carry total, the rows available in all, when it is known.
Responses
Every tool answers synchronously: the result is in the response to your POST, so there is nothing to poll. Most calls take a few seconds.
usage.price_usd is the settled charge in US dollars. billing_unit is always request and quantity always 1; billed_rows says how many rows the charge covers.
A number the data does not have is left out of the row, so check for the field before using it. Unknown request fields are rejected with 400 bad_request: a misspelt field that was silently dropped would answer a different question from the one you asked.
Keyword tools
Keyword overview
POST https://api.beatapi.io/v1/seo/keyword-overview
Volume, CPC, competition, difficulty, intent and monthly history for keywords you already have. A keyword nobody searches comes back missing, not as zero.
The response is in the quick start. Fields of each row:
Keyword ideas
POST https://api.beatapi.io/v1/seo/keyword-ideas
Related keywords for your seed keywords, most relevant first. Rows have the fields of keyword-overview without monthly_searches.
Keyword difficulty
POST https://api.beatapi.io/v1/seo/keyword-difficulty
Only keyword_difficulty, for many keywords at once. It takes the same fields as keyword-overview.
Domain tools
All four take a domain such as example.com, plus country and language.
Domain overview
POST https://api.beatapi.io/v1/seo/domain-overview
A domain’s organic and paid search footprint in one market. This is search traffic only, not total visits to the site.
A domain with nothing on record comes back with has_data: false and neither organic nor paid. That is no data, not zero traffic, and the call is billed.
Ranked keywords
POST https://api.beatapi.io/v1/seo/ranked-keywords
The keywords a domain ranks for in one market, highest search volume first.
Rows add these fields to those of keyword-ideas:
Top pages
POST https://api.beatapi.io/v1/seo/top-pages
A domain’s pages, highest estimated search traffic first. Fields: domain, limit, offset, country, language. Each row has a url and the footprint fields of that page.
Competitors
POST https://api.beatapi.io/v1/seo/competitors
Domains competing with a domain for the same search keywords. Fields: domain, limit, offset, country, language. The domain itself and the largest general sites, such as youtube.com and wikipedia.org, are left out of the rows, and total counts what is left.
Backlink tools
Backlink summary
POST https://api.beatapi.io/v1/seo/backlink-summary
A domain’s link profile. The only field is domain.
has_data is false when the domain is not on record, with no other fields, and the call is billed.
Backlinks
POST https://api.beatapi.io/v1/seo/backlinks
The links pointing at a domain, strongest first.
Reading the numbers
- Search traffic.
search_traffic_estimateis estimated search traffic, not total visits to a site. - Estimates. Traffic and value figures are estimates, not measurements of the site.
- Link authority.
link_authorityruns from 0 to 1000 on this data set’s own scale. - Keyword difficulty is this data set’s own scale. Do not compare it with another tool’s score.
- Missing is not zero. A number that is missing is unknown, never zero.
- No live results page. There is no live results-page tool. To check a domain’s position for a keyword, use
ranked-keywordswithcontains. That is the last recorded position, not a live one. - Domain Rating and site traffic have their own notes in Reading these numbers.
Billing
Domain Rating and site traffic have their own prices.
domain-overviewandbacklink-summaryreturn one record, which counts as one row, and none whenhas_dataisfalse. A call that returns 100 rows ofranked-keywordscosts $0.048.- A call that finds nothing still costs its per-call part. A rejected request (
400) costs nothing, and neither does a failed call (503). - Before a call runs, your balance must cover the most it can cost: every row of
limit, or every keyword sent. You are then charged only for what came back. - Send an
Idempotency-Keyheader when your client may retry the same request. Reusing a key with a different body is rejected with409 idempotency_conflict.
Agents
There is no separate MCP tool for SEO data. On the BeatAPI MCP endpoint https://beatapi.io/mcp, agents use capabilities_search, capabilities_inspect and capabilities_run with these references:
The references for Domain Rating and site traffic are listed with those tools.
Inspect shows the input schema and the current price. input is the request body of the tool, and Run answers with the result:
The same three calls work over REST at POST /v1/capabilities/search, /v1/capabilities/inspect and /v1/capabilities/run. See Capabilities API.
Errors
Errors use the standard BeatAPI error envelope, with retryable on every error. See Errors for the retry policy.
A 503 is never charged. BeatAPI does not answer 502.
Domain Rating and site traffic
Three more tools work the same way: same key, same answer in the response, same usage and errors. They take a domain and have no market, so country and language are rejected. There is no limit or offset.
Domain Rating
POST https://api.beatapi.io/v1/seo/domain-rating
domain_rating runs from 0 to 100. link_rank is the domain’s global rank by links; lower is stronger.
Domain Rating history
POST https://api.beatapi.io/v1/seo/domain-rating-history
An unknown domain returns has_data: false, an empty results and billed_rows: 1.
Site traffic
POST https://api.beatapi.io/v1/seo/site-traffic
Estimated total visits to a website from all channels, with sources, countries, rank and engagement.
Reading these numbers
- Two kinds of traffic.
search_traffic_estimateis estimated search traffic;site_visits_estimateis total visits from all channels. They are different measures: never add or compare them. Visits are not unique visitors. - Two authority scores.
link_authorityruns from 0 to 1000 on this data set’s own scale;domain_ratingruns from 0 to 100. They cannot be converted to each other. - Not on record.
has_data: falsemeans the domain is not on record, which differs from a rating or traffic of zero: a new site can have a rating of0and still have alink_rank.
Prices of these tools
domain-ratingandsite-trafficare billed whenhas_dataisfalse.domain-rating-historyfor an unknown domain returns no months and costs one, $0.004.- A rejected request (
400) and a failed call (503) cost nothing. - Before
domain-rating-historyruns, your balance must cover 24 months of history. You are then charged only for what came back.

