# A backlink checker API: who links to a site

> Query backlinks for any domain or URL with a single API call, returning referring domains, link metrics, anchors, and dofollow status.

**You can inspect who links to any domain or specific page URL by calling the `seo.backlinks` action through thelastapi.** With a single HTTP request or CLI command, you receive an aggregate summary—including total backlinks, referring domains, rank, and spam score—alongside an array of individual backlinks with their source URL, target URL, anchor text, and dofollow status. There are no separate subscriptions or complex setups required: web data runs on the same key and credit balance as the rest of your stack.

Understanding backlink profiles helps track brand mentions, audit referral traffic, assess competitor link acquisition, and monitor incoming link health. This guide covers how to call the backlink checker API, how to parse the payload, and how to build automated backlink checks into your tools.

## How to call the backlink checker API

You can run the backlink checker from your terminal, through direct HTTP requests, or inside an application using `@vibiz/app`.

### Using the CLI

For rapid checks from the terminal or shell scripts, use `vibiz seo backlinks`. Pass the domain or full page URL, along with an optional `--limit`:

```bash
vibiz seo backlinks example.com --limit 50
```

To output raw JSON for piping into tools like `jq`, add the `--json` flag:

```bash
vibiz seo backlinks example.com --limit 20 --json
```

You can also run it generically through the actions runner:

```bash
vibiz run seo.backlinks --input '{"target":"example.com","limit":20}'
```

### Using HTTP

To call the backlink checker from any programming language or backend service, send a `POST` request to `https://thelastapi.dev/v1/actions/seo.backlinks`:

```bash
curl https://thelastapi.dev/v1/actions/seo.backlinks \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "target": "example.com",
      "limit": 20
    }
  }'
```

The response includes the action result, execution metadata, and cost:

```json
{
  "object": "action_result",
  "action": "seo.backlinks",
  "output": {
    "target": "example.com",
    "summary": {
      "backlinks": 14250,
      "referring_domains": 1820,
      "rank": 48,
      "broken_backlinks": 12,
      "referring_ips": 1640,
      "spam_score": 2,
      "first_seen": "2021-03-15T08:00:00Z"
    },
    "backlinks": [
      {
        "from_url": "https://news.example.org/tech/article",
        "to_url": "https://example.com/product",
        "anchor": "software platform",
        "dofollow": true,
        "first_seen": "2023-11-04T12:30:00Z",
        "domain": "news.example.org"
      }
    ]
  },
  "cost_micro_usd": 40000,
  "run_id": "arun_12345",
  "console_url": "https://thelastapi.dev/web-data?action=seo.backlinks&run=arun_12345"
}
```

### From an application

If you are running a Node.js or TypeScript service using `@vibiz/app`, call `vibiz.actions.run` directly:

```ts
import { vibiz } from '@vibiz/app';

const response = await vibiz.actions.run('seo.backlinks', {
  target: 'example.com',
  limit: 50,
});

const { summary, backlinks } = response.output;

console.log(`Found ${summary.backlinks} links across ${summary.referring_domains} domains.`);
for (const link of backlinks) {
  console.log(`${link.from_url} -> ${link.to_url} [${link.anchor}] (dofollow: ${link.dofollow})`);
}
```

Calls run inside an application folder or project context bill directly to that project and record their history in the project dashboard.

## What data the backlink API returns

The `output` property of the response breaks down into two core sections: `summary` and `backlinks`.

### The aggregate summary

The `summary` object provides a high-level assessment of the target's link equity and profile cleanliness:

| Field | Description |
| --- | --- |
| `backlinks` | Total count of live external inbound links identified for the target. |
| `referring_domains` | Total count of distinct referring root domains pointing to the target. |
| `rank` | Aggregate metric representing overall backlink authority. |
| `broken_backlinks` | Total count of incoming links that resolve to a 4xx or 5xx HTTP status. |
| `referring_ips` | Number of distinct IP subnets hosting referring domains. |
| `spam_score` | Metric indicating the proportion of toxic or spam-oriented inbound links. |
| `first_seen` | Earliest timestamp when the system first detected a link pointing to the target. |

### The individual backlinks array

The `backlinks` array lists specific inbound links ordered strongest first. Each item includes:

- `from_url`: The exact referring page URL containing the link.
- `to_url`: The exact destination URL on your target domain.
- `anchor`: The visible anchor text used inside the link tag.
- `dofollow`: A boolean indicating whether the link passes search authority (`false` when marked `rel="nofollow"`, `rel="sponsored"`, or `rel="ugc"`).
- `first_seen`: ISO timestamp when this specific inbound link was first crawled.
- `domain`: The hostname of the referring website.

## Checking a domain versus a specific page URL

The `target` input takes either an entire domain or an individual page URL.

### Auditing an entire domain

When you supply a root domain like `target: "example.com"`, the API returns summary metrics across all subdomains and paths, and lists individual backlinks pointing anywhere on that site:

```bash
vibiz seo backlinks competitor.com --limit 100
```

This view is suited for competitor analysis, evaluating a potential acquisition, or checking your site's overall link profile.

### Auditing a single landing page

When you supply a full URL like `target: "https://example.com/blog/announcement"`, the API scopes results to that exact URL:

```bash
vibiz seo backlinks https://example.com/blog/announcement --limit 20
```

Targeting specific pages allows you to see which external publications cited a particular blog post, documentation release, or product feature.

## Combining backlinks with other SEO and web actions

A backlink checker becomes significantly more powerful when combined with other data endpoints. In thelastapi, web actions share the same input style, billing balance, and run history.

- **Check domain rankings**: After identifying strong referring domains with `seo.backlinks`, evaluate their organic traffic and top rankings using `vibiz seo domain competitor.com`.
- **Audit your own on-page structure**: When you find broken backlinks in `summary.broken_backlinks`, run `vibiz seo audit https://example.com/broken-target` to inspect on-page status codes, canonicals, and internal links.
- **Inspect referring content**: If a backlink lists an unexpected anchor text, use the web scraping action to extract the referring page's full text to markdown without parsing raw HTML. See how to [scrape a website to markdown with one API call](https://thelastapi.dev/blog/scrape-website-to-markdown-api).
- **Deep content analysis**: To extract an entire cluster of referring pages for retrieval pipelines, check [crawl a whole site to markdown for RAG](https://thelastapi.dev/blog/crawl-site-markdown-rag).
- **Monitor live search engine indexation**: While `seo.backlinks` reports external inbound links, the project search system tracks indexation directly via Google Search Console and Bing. Learn more in the [Search documentation](https://thelastapi.dev/docs/search).
- **Find new discovery opportunities**: Combine backlink audits with live web searches for unlinked brand mentions using [a web search API for AI agents and apps](https://thelastapi.dev/blog/web-search-api-ai-agents).

For the complete list of available web extraction actions, see the [Web data documentation](https://thelastapi.dev/docs/actions).

## Run history and console inspection

Every backlink check run via the CLI, HTTP API, or SDK is logged in thelastapi console under **Web data** (in the sidebar and within each project). 

Each run records:
- The exact input parameters provided (`target` and `limit`).
- The complete JSON output.
- Execution duration and exact micro-USD cost.
- Run ID (`arun_...`) and status.

To inspect previous checks without re-querying the external data sources, query the runs history via the CLI:

```bash
vibiz runs --action seo.backlinks --since 1d
```

Or retrieve a specific historical run by its ID:

```bash
vibiz runs arun_12345 --json
```

Agents can also query recent runs using the `vibiz_action_runs` MCP tool to avoid paying twice for identical data within a single session.

## Pricing, limits, and errors

Backlink queries execute synchronously against live data indexes.

- **Pricing**: Backlinks cost about 4 cents per call (`cost_micro_usd` is returned in every response). The account is billed that cost plus the 30% margin on web data, drawn from your account credits. Every run counts against your daily spend ceiling ($5 default across AI and web data, adjustable in billing).
- **Limits**: The `limit` parameter accepts between 1 and 1000 backlinks per request (default is 20).
- **Error handling**:
  - `invalid_request` (HTTP 400): The `target` parameter was missing or malformed.
  - `rate_limited` (HTTP 429): You reached your daily account spend ceiling.
  - `payment_required` (HTTP 402): Account credit balance is exhausted. Top up credits with `vibiz billing top-up`.
  - `provider_unavailable` (HTTP 503): The query timed out or the data index is temporarily unreachable. Retry the request or lower the `limit`.

Next: create your account at [thelastapi.dev/start](https://thelastapi.dev/start) to get an account key, or review the [Web data actions reference](https://thelastapi.dev/docs/actions) to explore SERP tracking, keyword ideas, and domain analytics.

## Frequently asked questions

### Can I check backlinks for individual URLs as well as root domains?

Yes. The `target` parameter accepts either a bare domain (such as `example.com`) to evaluate the entire website's link profile or a complete page URL (such as `https://example.com/page`) to inspect links pointing to that specific page.

### How many backlinks can I retrieve in a single request?

You can request between 1 and 1000 backlinks per call using the `limit` parameter. If omitted, `limit` defaults to 20 backlinks.

### How much does a backlink check API call cost?

A backlink query costs about 4 cents per call. Each response includes the exact `cost_micro_usd` charged, which is billed along with the standard 30% web data margin from your account credit balance.

---

Published 2026-11-15 · https://thelastapi.dev/blog/backlink-checker-api
