> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-backlink-profile.md).

# 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:

```http
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:

```http
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`.

```http
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:

```json
{
  "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.

## Related articles

* [Getting started with the API](/api/api-getting-started.md)
* [Authentication and API scopes](/api/api-authentication.md)
* [Using Backlink Profile](/promote/backlink-profile-guide.md)
* [Prospector API](/api/api-prospector.md)