Ahrefs API

Access real-time Ahrefs SEO data directly through the Ahrefs API to analyze websites, research keywords, track rankings, and make data-driven SEO decisions.

First-Time Setup

If this is your first time using the Ahrefs API, read references/setup.md for complete setup instructions. You'll need:

• An Ahrefs account (Enterprise plan for full API access, or Lite+ for limited free test queries)
• An API key from your Ahrefs workspace

Core Capabilities

Ahrefs API provides access to:

• Site Explorer - Domain metrics, backlinks, organic traffic, referring domains
• Keywords Explorer - Search volume, keyword difficulty, SERP analysis, related keywords
• Rank Tracker - Position tracking, visibility metrics, competitor rankings (requires pre-configured projects)
• Site Audit - Technical SEO issues, crawl data, site health (requires pre-configured projects)
• SERP Overview - Top 100 SERP results for any keyword
• Batch Analysis - Process up to 100 targets per request
• Brand Radar - Brand performance stats

Authentication

All API requests require an API key passed via the Authorization header:

Authorization: Bearer YOUR_API_KEY

Store your API key securely. Consider using environment variables:

export AHREFS_API_KEY="your-api-key-here"

Usage Workflow

1. Understand the Request

Identify what SEO data is needed:

• Domain/URL analysis → Site Explorer endpoints
• Keyword data → Keywords Explorer endpoints
• Position tracking → Rank Tracker endpoints (requires project)
• Technical SEO → Site Audit endpoints (requires project)
• SERP data → SERP Overview endpoints

2. Make API Requests

Use curl or similar tools to call the Ahrefs API. Base URL: https://api.ahrefs.com/v3

Example - Get domain overview:

curl -X GET "https://api.ahrefs.com/v3/site-explorer/domain-overview?target=example.com" \
  -H "Authorization: Bearer $AHREFS_API_KEY"

Example - Keyword metrics:

curl -X GET "https://api.ahrefs.com/v3/keywords-explorer/overview?keyword=seo+tools&country=us" \
  -H "Authorization: Bearer $AHREFS_API_KEY"

3. Process and Present Results

• Parse JSON responses
• Extract relevant metrics
• Present data in clear, actionable formats
• Highlight key insights and opportunities
• Suggest next steps based on findings

Common Workflows

Keyword Research + Cross-Reference

• User provides keyword list
• Make batch API calls to Keywords Explorer
• Parse and consolidate metrics (volume, difficulty, CPC)
• Present analysis with prioritization recommendations

Competitive Analysis

• Identify target domain and competitors
• Call Site Explorer for each domain
• Compare metrics (DR, organic traffic, referring domains)
• Analyze top organic keywords
• Identify content gaps
• Provide actionable recommendations

Site Audit Review

Note: Requires pre-configured Site Audit project in Ahrefs web interface.

• Call Site Audit API for project data
• Identify critical issues by severity
• Prioritize fixes by impact
• Provide technical recommendations

API Limits & Best Practices

Rate Limiting

• 60 requests per minute by default
• API returns HTTP 429 if limit exceeded
• Implement exponential backoff for retries

API Unit Consumption

• Each request consumes API units from your monthly allowance
• Cost depends on the number of rows returned (minimum 50 units per request)
• Track usage in Account settings → Limits and usage
• Enterprise plans include units; additional units can be purchased

Optimization Tips

• Batch requests when possible (up to 100 targets)
• Limit result rows using limit parameter
• Select specific columns with select parameter to reduce costs
• Cache results when appropriate
• Use date ranges to limit historical data

Plan-Specific Access

• Enterprise: Full API access
• Lite/Standard/Advanced: Limited free test queries (check your plan for specifics)

Error Handling

Common HTTP status codes:

• 200 OK - Success
• 400 Bad Request - Invalid parameters
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - Insufficient permissions or plan limits
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Ahrefs server issue

When API Key is Missing

If the API key is not configured:

• Provide setup instructions from references/setup.md
• Guide through API key generation in Ahrefs Account settings
• Explain how to securely store the key (environment variables recommended)
• Test the connection with a simple API call

Resources

• API Documentation: https://docs.ahrefs.com/docs/api/reference/introduction
• API Key Management: https://app.ahrefs.com/account/api-keys
• Pricing & Limits: https://ahrefs.com/pricing
• Limits & Usage Tracking: https://app.ahrefs.com/account/limits-and-usage/web