Backlink Profile API

Read saved backlink evidence or explicitly refresh its cache through the Agent API and MCP.

Use the Backlink Profile Agent API when an integration needs evidence saved by Rankability. Reading remains provider-free. A separate confirmed action can create or refresh the four aggregate snapshot sections without exposing the individual-backlink list or export workflow.

Scope and endpoint

Grant backlinks:read, then call:

GET /api/agent/v1/clients/:client_id/backlinks/profile

The API verifies both organization and client ownership. A client outside the authenticated organization is returned as not found.

To create or refresh saved evidence, grant backlinks:run and call:

POST /api/agent/v1/clients/:client_id/backlinks/profile/refresh
Idempotency-Key: stable-retry-key
Content-Type: application/json

{
  "include_subdomains": true,
  "confirm_usage": true
}

First call the usage estimate with operation=backlink_profile_refresh, show the result, and obtain approval. The action populates summary, history, anchors, and top pages. It safely reuses snapshots newer than six hours, so retries do not repeat fresh provider work. Legacy accounts currently receive a zero-credit estimate; no new per-action price is introduced.

Choose a section

Section	Saved evidence	Additional parameters
`summary`	Totals, referring domains, Domain Score, link attributes, and 30-day gains/losses	None
`history`	Referring-domain, gain/loss, and Domain Score observations	`months=1..12`
`anchors`	Anchor text with backlink and referring-domain counts	`limit`, `offset`
`top_pages`	Saved destination pages and their link totals	`limit`, `offset`

limit is capped at 100 and offset at 10,000. The default section is summary.

GET /api/agent/v1/clients/CLIENT_UUID/backlinks/profile?section=anchors&limit=25&offset=0
Authorization: Bearer rk_live_YOUR_KEY

Domain selection

The route defaults to the client’s configured domain. Supply domain=competitor.example only when Rankability previously saved a snapshot for that exact client/domain pair.

include_subdomains=true selects the aggregate domain snapshot. false selects the separately stored isolated-domain variant. A read never starts analysis; a confirmed refresh creates or updates the selected variant.

Freshness and missing data

Available responses include:

{
  "client_id": "CLIENT_UUID",
  "domain": "example.com",
  "section": "summary",
  "data_state": "available",
  "cached_at": "2026-08-24T18:00:00.000Z",
  "freshness": "fresh",
  "summary": {
    "total_backlinks": 1250,
    "referring_domains": 184,
    "domain_score": 42
  }
}

Snapshots older than six hours remain readable with freshness: "stale". When no matching snapshot exists, the route returns data_state: "unavailable", null freshness time, and an explanatory note. Unavailable does not mean the domain has zero backlinks.

Safety boundary

The read contract returns saved aggregate evidence only. The refresh contract updates those four aggregate sections after explicit approval. Neither contract exposes raw provider payloads, individual live backlinks, CSV export, prospect discovery, enrichment, or outreach.