SEO Metrics API documentation

1. Authentication

Bearer token in the Authorization header

Every request (except /v1/health and the public tool endpoints) carries your key in the Authorization header. Keys come from the signup page, look like sk_live_pub_…, and are stored by us only as a hash. A missing or invalid key answers 401.

$ curl -H "Authorization: Bearer sk_live_pub_YOUR_KEY" \
    "https://seometricsapi.com/v1/domains/example.com?fields=rating,traffic"

2. Response envelope

Every response carries data, meta and error

{
  "data": {
    "domain": "apnews.com",
    "requested": "apnews.com",
    "domain_rating": 91,
    "ahrefs_rank": 412,
    "monthly_visits": 105300000,
    "monthly_visits_basis": "total",
    "organic_monthly_visits": 38200000,
    "sources": {
      "domain_rating":  { "provider": "ahrefs",     "fetched_at": "2026-08-28T09:14:02Z", "status": "ok" },
      "monthly_visits": { "provider": "similarweb", "fetched_at": "2026-08-27T22:41:55Z", "status": "ok" }
    }
  },
  "meta": {
    "resource": "domain",
    "request_id": "req_01J6XY0M9…",
    "cache": "hit",
    "age_seconds": 254407,
    "cost_units": 0,
    "degraded": false
  },
  "error": null
}

Numbers are numbers. 105300000, never "105M+"; formatting is left to the client.
null means unknown. Never zero, never a placeholder. The matching sources entry says why: no_data, provider_error, disabled or not_requested.
Provenance per field. Each metric names its provider and fetch time in sources; derive freshness from fetched_at, not from the time of the request.
meta.cache and meta.cost_units. A cache hit costs 0 credits; a fresh fetch costs each billed provider call at its API type's credits (see credit costs). degraded: true marks an answer served past its freshness window.

3. Endpoints

Endpoint reference

Method	Path	Returns	Notes
GET	`/v1/domains/{domain}`	The domain resource	Domain metrics. Parameters: `fields`, `traffic_fallback`, `country`, `max_age`.
POST	`/v1/domains:batch`	Results, or a job	Up to 200 domains; above 25 it answers `202` with a job. Growth plans and up.
POST	`/v1/domains:aggregate`	Bundle stats	`domain_rating_avg`, `domain_rating_max`, `monthly_visits_sum` over a list.
GET	`/v1/jobs/{job_id}`	Batch progress	`total / done / ok / no_data / failed`; results once terminal.
GET	`/v1/keywords`	Keyword metrics	`q` = up to 5 comma-separated phrases; volume, difficulty, CPC + currency.
GET	`/v1/serp`	SERP snapshot	`q`, plus `country`, `language`, `limit`, `type`. Organic results with `serp_position`; `data.engine` always named.
GET	`/v1/index`	Index check	`target` (a domain or a full URL) plus `samples` (0–10). Reports presence in Google's index. `engine` is `serper`, `google_search116` or `indexchecker`; `samples` and `indexed_sample_count` are `null` when the engine supplies no evidence, and `[]`/`0` when it looked and found none.
GET	`/v1/backlinks/{domain}`	Link-graph metrics	Scope `backlinks:read`, enabled per key on request. Includes Moz Spam Score — see section 5.
POST	`/v1/indexing`	An indexing task	Link indexing: up to 500 URLs (`mode: "advanced"`, up to 100, uses the priority queue). Answers `202`; charged per URL — see section 6.
GET	`/v1/indexing/{task_id}`	Task progress	`processed`, `indexed`, `status`. Scoped to the key that submitted the task. Costs 0.
GET	`/v1/favicon`	Verified favicon URL	Probed, size-checked, never a blank placeholder.
GET	`/v1/usage`	Your consumption	Current period: events, credits spent, cache hits, your limits.
GET	`/v1/health`	Service status	Anonymous. Database + provider availability.

# Domain metrics, scoped to what you pay for
$ curl -H "Authorization: Bearer $KEY" \
  "https://seometricsapi.com/v1/domains/nytimes.com\
?fields=rating,traffic,countries,engagement"

# Keyword volumes, difficulty, CPC
$ curl -H "Authorization: Bearer $KEY" \
  "https://seometricsapi.com/v1/keywords\
?q=seo%20api,domain%20rating&country=US"

# SERP snapshot
$ curl -H "Authorization: Bearer $KEY" \
  "https://seometricsapi.com/v1/serp\
?q=affordable%20seo%20api&country=US&limit=10"

# Index check, and the key's usage
$ curl -H "Authorization: Bearer $KEY" \
  "https://seometricsapi.com/v1/index?target=example.com"
$ curl -H "Authorization: Bearer $KEY" \
  "https://seometricsapi.com/v1/usage"

4. Field groups

Field selection with the fields parameter

The fields parameter scopes both the response and the spend. Default: rating,traffic,countries.

Group	Fields included
`rating`	`domain_rating` (0–100), `ahrefs_rank`
`traffic`	`monthly_visits` (+ `monthly_visits_basis`), `organic_monthly_visits`
`countries`	`top_countries` — `[{country_code, share}]`, share is a fraction 0–1
`engagement`	`bounce_rate`, `pages_per_visit`, `time_on_site_seconds`, `month`, `traffic_sources`
`ranks`	`traffic_ranks` — global, country and category popularity ranks
`history`	`monthly_visits_history` — recent months of visit estimates
`site`	`site` — name, title, description, category
`favicon`	`favicon_url`
`all`	Everything above

5. Backlinks and spam score

Link-graph metrics, attributed per vendor

GET /v1/backlinks/{domain} returns five fields, each with its own sources[field] entry saying which vendor supplied it and when. It needs the backlinks:read scope, which is not granted by default — ask support to add it to a key.

Field	Meaning
`backlinks`	Unique external pages linking to the root domain (Moz).
`referring_domains`	Unique referring root domains (Moz).
`moz_domain_authority`	Moz Domain Authority, 0–100. This is not `domain_rating`.
`moz_spam_score`	Moz Spam Score as a percentage, 0–100. Moz's bands: 1–30 low, 31–60 medium, 61–100 high.
`semrush_authority_score`	Semrush Authority Score, 0–100. It blends the link graph with organic search traffic, so it is not comparable one-to-one with Domain Rating or Domain Authority.

What it costs. 1 credit per vendor fetched fresh; cache hits cost 0. The Moz fields and semrush_authority_score are two independent vendor calls, so a request that refreshes both costs 2 credits and one that is served entirely from cache costs nothing. meta.cost_units always reports what this request actually spent.

Ships disabled. Until a Moz or Semrush credential is configured, this endpoint answers 200 with every value null, every sources[field].status set to "disabled" and meta.cost_units: 0. That is the honest answer for "no provider is configured" — it is not an outage, and it is not a zero.

Vocabulary. da is a legacy alias of domain_rating (Ahrefs); Moz Domain Authority is moz_domain_authority and has no alias. Three vendors publish three different authority scores on three different scales, and this API never merges them or renames one as another.

# Link-graph metrics for one domain
$ curl -H "Authorization: Bearer $KEY" \
  "https://seometricsapi.com/v1/backlinks/nytimes.com"

6. Link indexing

Submitting URLs for crawling

POST /v1/indexing queues a list of URLs with an indexing provider and answers 202 with a task; GET /v1/indexing/{task_id} reports its progress. The key needs the indexing:write scope, which new keys carry.

Body field	Meaning
`urls`	1 to 500 absolute http(s) URLs; trimmed and de-duplicated before counting. One submission is capped at 65,535 credits.
`client_ref`	Optional, 1–64 characters. An idempotency key: a retry with the same value answers the task already queued and charges nothing.
`mode`	`standard` (default) or `advanced`. Advanced takes at most 100 URLs and asks for the priority queue, which Googlebot follows within minutes; if the queue declines, the task runs standard, is charged standard, and `warning` says so.

Cost. Charged per URL submitted at the credits set for link indexing (see credit costs; 100 standard and 200 advanced by default). The credits are reserved before the upstream is called: a submission the quota cannot cover answers 429 quota_exceeded with nothing queued. The status read costs 0. A test key is refused. Without a provider credential the endpoint answers 501.

# Queue two URLs in the standard queue
$ curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com/new-page", "https://example.com/updated-page"]}' \
  https://seometricsapi.com/v1/indexing
# Poll the task
$ curl -H "Authorization: Bearer $KEY" https://seometricsapi.com/v1/indexing/6609d023a3188540f09fec6c

7. Errors, limits and quotas

Error codes, rate limits and the monthly quota

Every failure is the same envelope with data: null and an error of {code, message, retriable}.

Code	HTTP	Retriable	Meaning
`invalid_input`	400	no	The request could not be understood; the message names the parameter.
`unauthorized`	401 / 403	no	No usable key (401), or the key lacks the required scope (403).
`not_found`	404	no	The target can't be identified — a malformed domain, an unknown job.
`rate_limited`	429	yes	Per-minute burst limit. Back off for `Retry-After` seconds.
`quota_exceeded`	429	no	Monthly credits spent. Resets monthly on the day the account signed up (UTC); upgrading lifts it immediately.
`provider_unavailable`	503	yes	An upstream provider is down; cached data may still be served with `degraded: true`.

Rate-limit state travels in headers — X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, plus Retry-After on a refusal. Cache hits are charged at a tenth of the per-minute weight, so a well-cached integration is effectively unthrottled. The monthly credit meter is the one /v1/usage reports — the same number that triggers quota_exceeded, so what you see is what refuses you.

Get an API key

A free key carries 100 credits a month and works on every endpoint above.

Get a free API key See pricing

Product

Alternatives

Company

Start now

100 free credits a month, forever. Upgrade only when you outgrow them.

Get free API key

SEO Metrics API is an independent service and is not affiliated with, endorsed by or sponsored by Ahrefs, Similarweb or Semrush. Authority and organic-traffic metrics are retrieved from the Ahrefs API under our own subscription; visit estimates come from third-party Similarweb-style datasets. All traffic figures are estimates, not analytics.

API reference