> 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 summary, history, anchor, and top-page evidence through the Agent API without starting a live provider request.

Use the Backlink Profile Agent API when an integration needs evidence already saved by Rankability. This route is deliberately read-only: it never invokes DataForSEO, refreshes a snapshot, loads the separately billed individual-backlink list, exports rows, or consumes usage.

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

## 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. Set it to `false` only when a separately saved isolated-domain snapshot exists. Changing this flag never starts a new analysis.

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

This contract returns saved aggregate evidence only. It does not expose raw provider payloads, individual live backlinks, CSV export, provider refresh, prospect discovery, enrichment, or outreach. Use the Rankability web workflow when a human explicitly intends to request new provider data and review its current usage impact.

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