# How to Get Backlink Data Using OpenSEO and DataForSEO

> Learn how to get backlink data using OpenSEO and DataForSEO. Access structured backlink information via OpenSEO's TypeScript API and helper functions for seamless integration.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: how-to-guide
- Published: 2026-09-10

---

**You can retrieve backlink data from DataForSEO through OpenSEO's TypeScript-typed API by using the helper functions in [`src/server/lib/dataforseo/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/backlinks.ts), which validate requests with Zod schemas and transform responses into strongly-typed objects like `BacklinksSummaryItem` and `ReferringDomainItem`.**

OpenSEO provides a robust wrapper around DataForSEO's backlink endpoints, offering type-safe access to comprehensive link intelligence. To get backlink data using OpenSEO and DataForSEO, you interact with a pipeline that validates requests using Zod schemas, executes calls through a generic HTTP client, and returns standardized TypeScript interfaces. This architecture ensures runtime safety and consistent data structures across both frontend and backend implementations.

## Architecture Overview: The Backlink Data Pipeline

OpenSEO implements a layered architecture to process backlink requests securely and efficiently. The flow moves from request validation through data transformation to final delivery:

1. **Request Validation** – Incoming parameters are parsed and validated against Zod schemas defined in [`src/types/schemas/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/backlinks.ts), ensuring type safety before any external API calls occur.

2. **Route Handling** – The Express-style route in [`web/src/routes/api/backlink-check.ts`](https://github.com/every-app/open-seo/blob/main/web/src/routes/api/backlink-check.ts) extracts the target domain and query parameters, then delegates to server-side helpers.

3. **Data Retrieval** – Helper functions in [`src/server/lib/dataforseo/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/backlinks.ts) construct payloads for DataForSEO's `/v3/backlinks/.../live` endpoints, invoke the generic `dataforseoPost` client from [`src/server/lib/dataforseo/core.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/core.ts), and parse responses using `assertOk` validation.

4. **Billing Classification** – Cost and usage information from DataForSEO is processed through `createDataforseoBillingClassifier` in [`src/server/lib/dataforseoBillingClassification.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseoBillingClassification.ts) to provide user-friendly billing feedback.

All data flowing from DataForSEO is first declared with Zod schemas such as `backlinksItemSchema` and `referringDomainItemSchema`, guaranteeing runtime safety and a single source of truth for both frontend table columns and backend API contracts.

## Fetching Backlink Summaries

Use `fetchBacklinksSummary` to retrieve high-level metrics for a target domain, including total backlink counts, broken links, and referring domain statistics.

```typescript
import { fetchBacklinksSummary } from '@/server/lib/dataforseo/backlinks';

async function getDomainOverview(domain: string) {
  const { data, billing } = await fetchBacklinksSummary({ target: domain });
  
  console.log('Total backlinks:', data.backlinks);
  console.log('Broken backlinks:', data.broken_backlinks);
  console.log('Referring domains:', data.referring_domains);
  
  return { data, billing };
}

```

The function returns a `BacklinksSummaryItem` object along with billing information that tracks your DataForSEO API usage costs.

## Retrieving Detailed Backlink Rows

For granular link data, use `fetchBacklinksRows` with the `BacklinksRowsPageInput` interface. This supports pagination, sorting, and spam filtering through the filters parameter.

```typescript
import { fetchBacklinksRows, BacklinksRowsPageInput } from '@/server/lib/dataforseo/backlinks';

const input: BacklinksRowsPageInput = {
  target: 'example.com',
  page: 1,
  pageSize: 100,
  sortField: 'firstSeen',
  sortOrder: 'desc',
  mode: 'one_per_domain',
  filters: {
    minDomainRank: 30,
    hideSpam: true,
    spamThreshold: 20,
  },
};

const { data, billing } = await fetchBacklinksRows(input);

console.log(`Showing ${data.items.length} of ${data.totalCount} backlinks`);
data.items.forEach((row: BacklinksItem) => {
  console.log(`${row.domain_from} → ${row.url_to} (Rank: ${row.rank})`);
});

```

The `mode: 'one_per_domain'` option returns only the highest-quality backlink from each referring domain, reducing noise in large datasets.

## Analyzing Referring Domains

To analyze unique referring domains rather than individual links, use `fetchReferringDomains` with the `ReferringDomainsPageInput` type.

```typescript
import { fetchReferringDomains, ReferringDomainsPageInput } from '@/server/lib/dataforseo/backlinks';

const input: ReferringDomainsPageInput = {
  target: 'example.com',
  pageSize: 50,
  sortField: 'backlinks',
  sortOrder: 'desc',
};

const { data } = await fetchReferringDomains(input);

data.items.forEach((domain: ReferringDomainItem) => {
  console.log(`${domain.domain}: ${domain.backlinks} links, DR ${domain.domain_rank}`);
});

```

Each item in the response is typed as `ReferringDomainItem`, providing structured access to domain authority metrics and backlink counts per referring site.

## Tracking Historical Backlink Trends

Monitor backlink growth over time using `fetchBacklinksHistory`, which queries time-series data from DataForSEO.

```typescript
import { fetchBacklinksHistory } from '@/server/lib/dataforseo/backlinks';

const history = await fetchBacklinksHistory({
  target: 'example.com',
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31',
});

history.data.forEach(entry => {
  console.log(`${entry.date}: ${entry.backlinks} total backlinks`);
});

```

This function is essential for SEO auditing and competitor analysis, revealing acquisition patterns and link velocity over custom date ranges.

## Validating Requests with Zod Schemas

Runtime type safety is enforced through schemas defined in [`src/types/schemas/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/backlinks.ts). These schemas define validation rules for lookup parameters, pagination settings, filters, and sorting options used across all backlink fetchers.

The schemas export TypeScript types inferred from Zod definitions, ensuring that `BacklinksRowsPageInput` and `ReferringDomainsPageInput` remain synchronized between validation logic and function signatures. When you pass parameters to `fetchBacklinksRows`, they are automatically validated against `backlinksSearchSchema` before the DataForSEO API call executes.

## Exposing Data via the REST API

OpenSEO exposes backlink functionality through the public endpoint `GET /api/backlink-check/:domain`, implemented in [`web/src/routes/api/backlink-check.ts`](https://github.com/every-app/open-seo/blob/main/web/src/routes/api/backlink-check.ts). This route handles HTTP requests, validates query parameters using the Zod schemas, and returns JSON containing summary statistics, paginated rows, or referring domain lists.

You can call this endpoint directly from client applications:

```javascript
fetch('https://openseo.so/api/backlink-check/example.com?page=1&pageSize=50')
  .then(r => r.json())
  .then(({ summary, rows, billing }) => {
    console.log('Summary:', summary);
    console.table(rows.items);
  });

```

The route accepts the same query parameters defined in `backlinksSearchSchema`, including scope, filters, sort fields, and pagination controls.

## Summary

- **Use `fetchBacklinksSummary`** in [`src/server/lib/dataforseo/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/backlinks.ts) for high-level domain metrics and broken link counts.
- **Use `fetchBacklinksRows`** with `BacklinksRowsPageInput` for detailed, paginated backlink data with spam filtering and sorting capabilities.
- **Use `fetchReferringDomains`** to analyze unique referring domains and their authority scores.
- **Use `fetchBacklinksHistory`** to retrieve time-series data for trend analysis and link velocity tracking.
- **All functions** validate input through Zod schemas in [`src/types/schemas/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/backlinks.ts) and return strongly-typed objects like `BacklinksItem` and `ReferringDomainItem`.
- **Access data via HTTP** through the `/api/backlink-check/:domain` endpoint defined in [`web/src/routes/api/backlink-check.ts`](https://github.com/every-app/open-seo/blob/main/web/src/routes/api/backlink-check.ts).

## Frequently Asked Questions

### What DataForSEO endpoints does OpenSEO use internally?

OpenSEO targets DataForSEO's `/v3/backlinks/.../live` endpoints through the `dataforseoPost` client in [`src/server/lib/dataforseo/core.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/core.ts). Specific functions map to specific endpoints: `fetchBacklinksSummary` retrieves summary data, `fetchBacklinksRows` accesses the detailed backlink list, `fetchReferringDomains` queries the referring domains endpoint, and `fetchBacklinksHistory` fetches historical time-series data.

### How does OpenSEO handle DataForSEO API authentication?

Authentication is managed internally by the `dataforseoPost` function in [`src/server/lib/dataforseo/core.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/core.ts), which automatically injects API credentials into request headers. You do not need to manually handle authentication tokens when calling the helper functions; the generic client manages retries, header configuration, and envelope parsing transparently.

### Can I filter backlink results by domain authority or spam score?

Yes. The `BacklinksRowsPageInput` interface accepts a `filters` object that supports `minDomainRank`, `hideSpam`, and `spamThreshold` parameters. These filters are applied server-side before results are returned, allowing you to exclude low-quality or spam links during the initial DataForSEO query rather than filtering client-side.

### What TypeScript types are available for backlink data?

OpenSEO exports several strongly-typed interfaces including `BacklinksSummaryItem` for aggregate statistics, `BacklinksItem` for individual link records, and `ReferringDomainItem` for domain-level analysis. All response types are derived from Zod schemas in [`src/types/schemas/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/types/schemas/backlinks.ts), ensuring that compile-time type checking aligns with runtime validation rules.