Skip to main content
All Ahrefs API calls are available under corsair.ahrefs.api.*. Every method is fully typed, validates inputs with Zod, and surfaces Ahrefs request failures through the plugin error handlers.

​
Site Explorer

​
getDomainRating

Get Ahrefs Domain Rating and Ahrefs Rank for a target domain. 
const result = await corsair.ahrefs.api.siteExplorer.getDomainRating({
  target: 'example.com',
  date: '2024-01-01',
  protocol: 'https', // optional: 'http' | 'https' | 'both'
});

console.log(result.domain_rating.domain_rating); // 0-100
console.log(result.domain_rating.ahrefs_rank); // global rank
Risk Level: read

​
backlinksStats

Get live and all-time backlink and referring-domain counts for a target. 
const result = await corsair.ahrefs.api.siteExplorer.backlinksStats({
  target: 'example.com',
  date: '2024-01-01',
  mode: 'domain', // optional: 'exact' | 'prefix' | 'domain' | 'subdomains'
  protocol: 'https', // optional
});

console.log(result.metrics.live); // live backlinks count
console.log(result.metrics.live_refdomains); // live referring domains
console.log(result.metrics.all_time); // all-time backlinks
console.log(result.metrics.all_time_refdomains); // all-time referring domains
Risk Level: read

​
organicKeywords

List organic keywords a target ranks for, including positions and traffic metrics. 
const result = await corsair.ahrefs.api.siteExplorer.organicKeywords({
  target: 'example.com',
  country: 'us',
  date: '2024-01-01',
  select: 'keyword,volume,best_position,sum_traffic',
  limit: 100, // optional, default 1000
  order_by: 'sum_traffic:desc', // optional
  mode: 'domain', // optional: 'exact' | 'prefix' | 'domain' | 'subdomains'
});

result.keywords.forEach(keyword => {
  console.log(keyword.keyword);
  console.log(keyword.volume); // monthly search volume
  console.log(keyword.best_position); // ranking position
  console.log(keyword.sum_traffic); // estimated traffic
});
Risk Level: read

​
refdomains

List referring domains linking to a target. 
const result = await corsair.ahrefs.api.siteExplorer.refdomains({
  target: 'example.com',
  date: '2024-01-01',
  select: 'domain,domain_rating,links,dofollow_links',
  limit: 100, // optional
  history: 'all_time', // optional
  mode: 'domain', // optional
});

result.refdomains.forEach(refdomain => {
  console.log(refdomain.domain);
  console.log(refdomain.domain_rating);
  console.log(refdomain.links); // total links from this domain
});
Risk Level: read

​
topPages

List top organic pages for a target with traffic, keyword, and link metrics. 
const result = await corsair.ahrefs.api.siteExplorer.topPages({
  target: 'example.com',
  country: 'us',
  date: '2024-01-01',
  select: 'raw_url,sum_traffic,keywords,referring_domains',
  limit: 100, // optional
  mode: 'domain', // optional
});

result.pages.forEach(page => {
  console.log(page.raw_url);
  console.log(page.sum_traffic); // estimated traffic
  console.log(page.keywords); // number of ranking keywords
  console.log(page.referring_domains); // referring domains count
});
Risk Level: read

​
Keywords Explorer

​
overview

Get keyword metrics such as volume, difficulty, CPC, clicks, and traffic potential. 
const result = await corsair.ahrefs.api.keywordsExplorer.overview({
  select: 'keyword,volume,difficulty,cpc,clicks,traffic_potential',
  keywords: 'seo tools', // can also be an array: ['seo tools', 'backlink checker']
  country: 'us', // 2-letter country code
  limit: 100, // optional
  order_by: 'volume:desc', // optional
});

result.keywords.forEach(keyword => {
  console.log(keyword.keyword);
  console.log(keyword.volume); // monthly search volume
  console.log(keyword.difficulty); // keyword difficulty (0-100)
  console.log(keyword.cpc); // cost per click
  console.log(keyword.clicks); // estimated clicks
  console.log(keyword.traffic_potential); // traffic potential
});
Risk Level: read Optional Parameters:
  • target: Filter by target domain
  • target_mode: ‘exact’ | ‘prefix’ | ‘domain’ | ‘subdomains’
  • target_position: ‘in_top10’ | ‘in_top100’
  • keyword_list_id: Filter by keyword list ID
  • where: Custom SQL-like filter
  • volume_monthly_date_from: Start date for historical volume
  • volume_monthly_date_to: End date for historical volume

​
Rank Tracker

​
overview

Get Rank Tracker keyword overview data for a project and device. 
const result = await corsair.ahrefs.api.rankTracker.overview({
  project_id: 123456, // your Ahrefs project ID
  device: 'desktop', // 'desktop' | 'mobile'
  date: '2024-01-01',
  select: 'keyword,position,previous_position,url,traffic',
  limit: 100, // optional
});

result.overviews.forEach(row => {
  console.log(row.keyword);
  console.log(row.position); // current position
  console.log(row.previous_position); // previous position
  console.log(row.url); // ranking URL
  console.log(row.traffic); // estimated traffic
});
Risk Level: read

​
SERP Overview

​
overview

Get SERP positions for a keyword and country, including ranking page metrics. 
const result = await corsair.ahrefs.api.serp.overview({
  keyword: 'seo tools',
  country: 'us',
  select: 'position,url,title,domain_rating,backlinks,traffic',
  top_positions: 10, // optional, default all
  date: '2024-01-01', // optional, default latest
});

result.positions.forEach(position => {
  console.log(position.position); // SERP position (1, 2, 3...)
  console.log(position.url); // ranking URL
  console.log(position.title); // page title
  console.log(position.domain_rating); // Ahrefs Domain Rating
  console.log(position.backlinks); // backlinks to this page
  console.log(position.traffic); // estimated traffic
});
Risk Level: read

​
Subscription Info

​
limitsAndUsage

Get Ahrefs subscription limits and API unit usage. 
const result = await corsair.ahrefs.api.subscriptionInfo.limitsAndUsage({});

console.log(result.limits_and_usage.subscription); // subscription type
console.log(result.limits_and_usage.units_limit_api_key); // API key limit
console.log(result.limits_and_usage.units_usage_api_key); // API key usage
console.log(result.limits_and_usage.usage_reset_date); // usage reset date
console.log(result.limits_and_usage.api_key_expiration_date); // key expiration
Risk Level: read

​
Error Handling

All API calls can throw an error from the underlying Ahrefs request: 
try {
  const result = await corsair.ahrefs.api.siteExplorer.getDomainRating({
    target: 'example.com',
    date: '2024-01-01',
  });
} catch (error) {
  if (error instanceof Error) {
    console.error('Message:', error.message);
  }
}

​
Rate Limiting

Corsair automatically handles Ahrefs rate limits:
  • Retries HTTP 429 responses
  • Uses Retry-After when Ahrefs sends it
  • Configurable retry strategy (default: 3 retries)
You can customize rate limit behavior: 
import { ahrefs } from '@corsair-dev/ahrefs';

export const corsair = createCorsair({
  plugins: [
    ahrefs({
      // custom error handlers
      errorHandlers: {
        RATE_LIMIT_ERROR: {
          match: (error) => error.message.includes('429'),
          handler: async (error, context) => ({
            maxRetries: 5,
            retryStrategy: 'exponential_backoff_jitter',
          }),
        },
      },
    }),
  ],
});