Ahrefs

Category: SEO & Research
Integration type: Tenant-configured API key (stored in integrations table)
External API: Ahrefs API v3

Purpose

Ahrefs provides backlink data and domain authority metrics. It is the primary data source for the Backlink Researcher agent:

Domain Rating (DR) and URL Rating (UR) — authority scores for prospects
Referring domains count — link popularity
Top backlinks for a domain — identify existing link profile
Keyword rankings — complementary to SEMrush

Tenants provide their own Ahrefs API key. Like SEMrush, Ahrefs API access requires a paid Ahrefs subscription (Advanced or Enterprise plan).

Config Structure

Tenant integration (stored in `integrations` table)


interface AhrefsConfig {
  apiKey: string;  // Ahrefs API key from ahrefs.com/api-key
}


integrations row:
  provider:   'ahrefs'
  api_key:    encrypt(apiKey)
  metadata:   {}

Integration Pattern

Tool layer (`packages/tools/src/ahrefs.ts`)

Ahrefs API v3 uses bearer token auth and returns JSON:


class AhrefsTool {
  constructor(private apiKey: string) {}
 
  private headers() {
    return {
      Authorization: `Bearer ${this.apiKey}`,
      Accept:        'application/json',
    };
  }
 
  async getDomainRating(domain: string): Promise<DomainRatingResult> {
    const response = await axios.get('https://api.ahrefs.com/v3/site-explorer/domain-rating', {
      headers: this.headers(),
      params:  {
        target: domain,
        mode:   'domain',
        select: 'domain_rating,ahrefs_rank',
      },
    });
    return {
      domain:       response.data.domain,
      domainRating: response.data.domain_rating,
      ahrefsRank:   response.data.ahrefs_rank,
    };
  }
 
  async getBacklinks(domain: string, limit = 100): Promise<BacklinkRow[]> {
    const response = await axios.get('https://api.ahrefs.com/v3/site-explorer/backlinks', {
      headers: this.headers(),
      params: {
        target:            domain,
        mode:              'domain',
        select:            'url_from,domain_rating_source,anchor,nofollow',
        order_by:          'domain_rating_source:desc',
        output:            'json',
        limit,
      },
    });
    return response.data.backlinks.map((b: any) => ({
      urlFrom:      b.url_from,
      domainRating: b.domain_rating_source,
      anchor:       b.anchor,
      isNofollow:   b.nofollow,
    }));
  }
 
  async getReferringDomains(domain: string): Promise<number> {
    const response = await axios.get('https://api.ahrefs.com/v3/site-explorer/metrics', {
      headers: this.headers(),
      params:  {
        target: domain,
        mode:   'domain',
        select: 'referring_domains',
      },
    });
    return response.data.referring_domains;
  }
 
  async verify(): Promise<void> {
    // Fetch account/subscription info
    const response = await axios.get('https://api.ahrefs.com/v3/account/usage', {
      headers: this.headers(),
    });
    if (!response.data.subscription) {
      throw new Error('Ahrefs verification failed — no active subscription found');
    }
  }
}

Backlink prospecting workflow

The Backlink Researcher agent uses Ahrefs to score and filter prospects:


// Inside backlink-researcher worker
const prospects = await generateProspects(clientNiche);  // From agent research
 
// Score each prospect using Ahrefs
const scoredProspects = await Promise.all(
  prospects.map(async (domain) => {
    const metrics = await ahrefsTool.getDomainRating(domain);
    return { domain, dr: metrics.domainRating, ...metrics };
  }),
);
 
// Filter: only domains with DR ≥ 30 and < 90 (sweet spot for link building)
const qualified = scoredProspects.filter(p => p.dr >= 30 && p.dr < 90);

API Row Credits

Ahrefs API billing is based on row credits. Each result row returned costs credits from the account’s monthly allocation:

Endpoint	Cost
Domain Rating (1 domain)	1 row credit
Backlinks (per link returned)	1 row credit
Metrics summary	1 row credit

Tenants with Ahrefs Advanced plans receive 500 row credits/month; Enterprise plans get more. The platform does not enforce Ahrefs credit limits — failures surface as activity errors.

Test Cases

Unit tests (`packages/tools/src/ahrefs.test.ts`)

Test	Approach
`getDomainRating()` builds correct params	Mock `axios.get`; assert `target`, `mode`, `select`
`getDomainRating()` returns typed result	Mock response; assert `domainRating` is number
`getBacklinks()` maps response rows	Feed mock `backlinks` array; assert mapped fields
`getReferringDomains()` returns numeric count	Mock `{ referring_domains: 42 }`; assert 42
`verify()` throws when no subscription	Mock `{ subscription: null }`; assert throws
Throws on 401 (invalid API key)	Mock 401 response; assert propagated

Integration tests

Test	Approach
Domain rating for known domain	Use test API key; fetch `ahrefs.com`; assert `domainRating >= 90`
Backlinks for known domain	Assert at least one result

SEMrush Provider — keyword data (complementary to Ahrefs)
DataForSEO Provider — SERP and backlink check (cheaper alternative)
Backlink Researcher Agent — primary consumer
Tool Integration Layer — integration management