Ahrefs Automation

Setup

1. Add the Composio MCP server to your configuration: https://rube.app/mcp
2. Connect your Ahrefs account when prompted. The agent will provide an authentication link.
3. Most tools require a target (domain or URL) and a country code (ISO 3166-1 alpha-2). Some also require a date in YYYY-MM-DD format.

Core Workflows

1. Site Explorer Metrics

• target (required) -- domain or URL to analyze
• date (required) -- metrics date in YYYY-MM-DD format
• country -- ISO country code (e.g., us, gb, de)
• mode -- scope: exact, prefix, domain, or subdomains (default)
• protocol -- both, http, or https
• volume_mode -- monthly or average

2. Historical Metrics Tracking

• target (required) -- domain to track
• date_from (required) -- start date in YYYY-MM-DD
• date_to -- end date
• history_grouping -- daily, weekly, or monthly (default)
• select -- columns like date,org_cost,org_traffic,paid_cost,paid_traffic

• target (required), date_from (required), date_to, history_grouping

3. Backlink Analysis

• target (required) -- domain or URL
• select (required) -- comma-separated columns (e.g., url_from,url_to,anchor,domain_rating_source,first_seen_link)
• limit (default 1000) -- number of results
• aggregation -- similar_links (default), 1_per_domain, or all
• mode -- exact, prefix, domain, or subdomains
• history -- live, since:YYYY-MM-DD, or all_time
• where -- rich filter expressions on columns like is_dofollow, domain_rating_source, anchor

4. Keyword Research

• select (required) -- columns to return (volume, difficulty, CPC, etc.)
• country (required) -- ISO country code
• keywords -- comma-separated keyword list
• where -- filter by volume, difficulty, intent, etc.

• select (required) and country (required)
• keywords -- comma-separated seed keywords
• match_mode -- terms (any order) or phrase (exact order)
• terms -- all or questions (question-format keywords only)

5. Organic Keywords Audit

• target (required) -- domain or URL
• country (required) -- ISO country code
• date (required) -- date in YYYY-MM-DD
• select -- columns to return (keyword, position, volume, traffic, URL, etc.)
• date_compared -- compare against a previous date
• where -- rich filter expressions on keyword, volume, best_position, intent flags, etc.
• limit (default 1000), order_by

6. Batch URL Analysis

• targets (required) -- array of objects with url, mode (exact/prefix/domain/subdomains), and protocol (both/http/https)
• select (required) -- array of column identifiers
• country -- ISO country code
• output -- json or php

Known Pitfalls

• Column selection is required: Most Ahrefs tools require a select parameter specifying which columns to return. Omitting it or using invalid column names will cause errors. Refer to each tool's response schema for valid identifiers.
• Date format consistency: Dates must be in YYYY-MM-DD format. Some historical endpoints return data at the granularity set by history_grouping, not by exact date.
• API unit costs vary: Different columns consume different unit amounts. Columns marked with "(5 units)" or "(10 units)" in the schema are more expensive. Monitor API usage when requesting expensive columns like traffic, refdomains_source, or difficulty.
• Batch limit is 100 targets: AHREFS_BATCH_URL_ANALYSIS accepts up to 100 targets per request. For larger analyses, split into multiple batches.
• Filter expressions are complex: The where parameter uses Ahrefs' filter expression syntax, not standard SQL. Consult the column descriptions in each tool's schema for supported filter types and value formats.
• Deprecated offset parameter: The offset parameter was deprecated on May 31, 2024. Use cursor-based pagination or adjust limit instead.
• Mode affects scope significantly: Setting mode to subdomains (the default) includes all subdomains, which can dramatically increase result counts compared to domain or exact.

Quick Reference