v0.8.0-alpha

Breaking

• site_explorer_best_by_external_links() renamed to site_explorer_pages_by_backlinks()
• site_explorer_best_by_internal_links() renamed to site_explorer_pages_by_internal_links()
• Corresponding type renames: SiteExplorerBestByExternalLinks{Data,Request} → SiteExplorerPagesByBacklinks{Data,Request}, same for internal links
• Brand Radar country parameter changed from CountryEnum | None to list[CountryEnum | None] across all 9 brand-radar endpoints — wrap single values in a list

Added

• management_brand_radar_prompts(), management_create_brand_radar_prompts(), management_brand_radar_prompts_delete() — manage Brand Radar custom prompts
• PagePositionsEnum for filtering site_explorer_pages_history() by ranking position (top10, top100)
• search_queries filter and response field on Brand Radar endpoints
• tags response field on brand_radar_ai_responses()
• size_uncompressed, size_uncompressed_diff, size_uncompressed_prev fields on site_audit_page_explorer()
• project_url, project_name filter parameters on site_audit_projects()

Fixed

• List-valued query parameters (e.g. country) now serialize as CSV instead of repeated keys, matching the API's expected format

v0.7.1-alpha

• Smarter error messages — Error responses show extracted message text instead of raw JSON. 404s hint at common causes (date not available, target not in index, incorrect parameters).
• Inline enum values — format_for_context() shows valid values inline, e.g. ModeEnum (exact, prefix, domain, subdomains). Large enums (200+) show the first 20 with a remaining count. No second lookup needed.
• History endpoint labels — Search results distinguish time-series endpoints from point-in-time snapshots, so agents pick the right variant on the first try.

v0.7.0-alpha

Added

• Management API support (13 endpoints) — manage Rank Tracker projects, keywords, keyword lists, and competitors
• PUT and PATCH HTTP method support
• HTTP method tags ([POST], [PUT], [PATCH]) in docstrings and API reference for write endpoints

v0.6.0-alpha

Added

• Public API support: public_crawler_ips() and public_crawler_ip_ranges() for retrieving Ahrefs crawler IP addresses
• Subscription Info API support: subscription_info_limits_and_usage() for checking API usage, limits, and key expiration

v0.5.0-alpha

• Web Analytics API support (34 endpoints) — 17 dimension endpoints and 17 chart variants
• Python reserved word handling: from parameter available as from_ with automatic API serialization

v0.4.2-alpha

format_for_context() in the search module now truncates results exceeding 9K chars. Only affects site_audit_page_explorer (605 fields, 86K → 9K). If you see ... [truncated] in search output, use select to request only the columns you need.

v0.4.1-alpha

Add Brand Radar report and prompt filtering parameters:

• New report_id parameter on all Brand Radar endpoints to load settings from a saved report
• New prompts parameter ("ahrefs" | "custom") to filter by prompt source
• PromptsEnum type for prompt source values
• Use python3/pip3 in README CLI examples

v0.4.0-alpha

Add BM25 method search for on-demand API method discovery:

• Add BM25-based search module (ahrefs.search) for AI agents to find API methods by natural language query
• CLI entry point: python -m ahrefs.api_search for agent tool use

v0.3.1-alpha

What's New

• 3 new Brand Radar endpoints: brand_radar_sov_history(), brand_radar_cited_domains(), brand_radar_cited_pages()
• 52 endpoints total (was 49)

Example

from ahrefs import AhrefsClient

# Uses AHREFS_API_KEY environment variable
client = AhrefsClient()
data = client.brand_radar_cited_domains(
    select="domain,responses",
    data_source="chatgpt",
    brand="ahrefs",
    limit=5,
)
for item in data:
    print(f"{item.domain}: {item.responses} responses")
client.close()

v0.3.0-alpha

What's New

• Batch Analysis endpoint — new batch_analysis() method for the Batch Analysis POST API
• POST request support — sync and async clients now support POST endpoints with JSON request bodies
• New types — BatchAnalysisRequest, BatchAnalysisTarget, BatchAnalysisData

Example

from ahrefs import AhrefsClient
from ahrefs.types import BatchAnalysisTarget

# Uses AHREFS_API_KEY environment variable
client = AhrefsClient()
data = client.batch_analysis(
    select=["ahrefs_rank", "domain_rating"],
    targets=[
        BatchAnalysisTarget(url="https://ahrefs.com", mode="domain", protocol="both"),
    ],
)
for item in data:
    print(f"DR {item.domain_rating}, Rank {item.ahrefs_rank}")
client.close()