How to Get Backlink Data Using OpenSEO and DataForSEO

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, 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, ensuring type safety before any external API calls occur.

2. Route Handling – The Express-style route in 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 construct payloads for DataForSEO's /v3/backlinks/.../live endpoints, invoke the generic dataforseoPost client from 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 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.

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.

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.

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.

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

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

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. 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, 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, ensuring that compile-time type checking aligns with runtime validation rules.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}