feat(ahrefs): validate integration, fix cents/column bugs, add 13 v3 endpoints (#5447)

* feat(ahrefs): validate integration, fix cents/column bugs, add 13 v3 endpoints

Audited the existing Ahrefs integration against live API v3 docs and fixed
real bugs: broken_backlinks selected the wrong column (http_code_target
instead of http_code), and keyword_overview/metrics/metrics_history returned
CPC/cost fields in USD cents without converting to USD. Also fixed the
top-pages mode dropdown missing the "exact" option.

Added 13 new tools covering previously-unsupported Ahrefs v3 endpoints:
Rank Tracker (overview, SERP overview, competitors overview, competitors
stats), Batch Analysis, Site Audit page explorer, four history/trend
endpoints (domain rating, metrics, referring domains, keywords), Related
Terms, Anchors, and Paid Pages.

Note: the CPC/cost unit fix silently shifts existing organicCost/paidCost/cpc
values by 100x for any workflow already consuming them (the old values were
wrong, in cents instead of dollars).

* fix(ahrefs): convert remaining cents-to-USD fields, drop unneeded fallback key

Rank Tracker SERP Overview's value field, Competitors Stats' trafficValue,
and Competitors Overview's nested competitor value were all left in USD
cents while every other monetary field in the integration converts to USD
- fixed for consistency with the rest of the integration.

Also drops the unverified `data.results` fallback in Batch Analysis; the
Ahrefs v3 docs confirm the response key is always `targets`.

* docs(ahrefs): regenerate docs to reflect cents-to-USD conversion fix

The generated docs page was stale after the previous commit converted
rank_tracker_serp_overview.value, rank_tracker_competitors_stats.trafficValue,
and rank_tracker_competitors_overview's nested value from cents to USD -
regenerating picks up the corrected field descriptions.

* fix(ahrefs): revert incorrect broken_backlinks column, fix missed top_pages conversion, revert unverified competitor value conversions

Independent re-verification against live Ahrefs v3 docs surfaced two real
regressions from the earlier fix rounds and one missed conversion:

- broken_backlinks: the earlier fix changed the selected column from
  http_code_target to http_code, but the docs say http_code is the
  *referring page's* status and http_code_target is the *broken target
  page's* status - the tool needs the latter (matches its own output
  description). Reverted to http_code_target.
- top_pages: value field was never divided by 100 despite the docs stating
  it's in USD cents and the output already claiming USD - fixed.
- rank_tracker_competitors_stats.trafficValue and the nested competitor.value
  in rank_tracker_competitors_overview were converted from cents to USD last
  round on a "match every other monetary field" assumption, but the live docs
  do not document these two fields as cents (unlike every field that was
  correctly converted). Reverted to passthrough and dropped the "(USD)"
  claim from their descriptions until Ahrefs documents the unit.

Also added the missing "exact" mode option to top_pages' mode param
description, matching every sibling tool.

* fix(ahrefs): convert rank tracker competitor value/trafficValue to USD

Both bots independently flagged these two fields as inconsistent with
every other monetary field in the integration, all 7 of which are
explicitly documented as USD cents. Neither field has explicit unit
documentation (one is undocumented as cents, the other's schema isn't
statically retrievable at all), but given the unanimous pattern across
every other verified field and no contrary evidence, converting for
consistency is the better bet than leaving them as an outlier.

* style(ahrefs): drop non-TSDoc inline comments introduced in this PR

Repo convention disallows non-TSDoc comments; removed the three
explanatory // comments this PR added next to cents-to-USD conversions
(keyword_overview, paid_pages, related_terms) - pre-existing comments
elsewhere in the file are untouched, out of scope for this PR.

* fix(ahrefs): default optional country to us consistently across all tools

paid_pages, metrics_history, keywords_history, and batch_analysis were the
only 4 of the 11 tools with an optional country param that didn't fall back
to "us" when omitted, unlike domain_rating, metrics, keyword_overview,
organic_keywords, organic_competitors, top_pages, and related_terms - all
of which default client-side. Aligned all four to the same convention so
direct tool/agent calls without an explicit country get the same behavior
regardless of which operation is used.

* fix(ahrefs): split shared date subBlock id for datetime-format operations

site_audit_page_explorer and rank_tracker_serp_overview both reused the
generic 'date' subBlock id with YYYY-MM-DDThh:mm:ss semantics, while every
other operation using that same id expects YYYY-MM-DD. Switching operations
without clearing the field could carry a stale wrong-format value into the
new operation's request. Split into distinct ids (crawlDate, asOfDate)
mapped back to each tool's date param in tools.config.params.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/ahrefs.mdx

@@ -387,12 +387,64 @@
           "name": "Top Pages",
           "description": "Get the top pages of a target domain sorted by organic traffic. Returns page URLs with their traffic, keyword counts, and estimated traffic value."
         },
+        {
+          "name": "Paid Pages",
+          "description": "Get a target domain's pages that receive paid search traffic, sorted by estimated paid traffic. Returns page URLs with their paid traffic, keyword counts, and estimated spend."
+        },
+        {
+          "name": "Anchors",
+          "description": "Get the anchor text distribution for a target domain or URL's backlinks, showing how many links and referring domains use each anchor text."
+        },
         {
           "name": "Keyword Overview",
           "description": "Get detailed metrics for a keyword including search volume, keyword difficulty, CPC, clicks, and traffic potential."
+        },
+        {
+          "name": "Related Terms",
+          "description": "Get keyword ideas related to a seed keyword: terms the same top-ranking pages also rank for (\"also rank for\") or also discuss (\"also talk about\"), with volume, difficulty, and CPC."
+        },
+        {
+          "name": "Domain Rating History",
+          "description": "Get the historical Domain Rating (DR) trend for a target domain or URL over a date range, grouped daily, weekly, or monthly."
+        },
+        {
+          "name": "Metrics History",
+          "description": "Get the historical organic and paid traffic trend for a target domain or URL over a date range: organic traffic/cost and paid traffic/cost at each point in time."
+        },
+        {
+          "name": "Referring Domains History",
+          "description": "Get the historical referring domains trend for a target domain or URL over a date range, grouped daily, weekly, or monthly."
+        },
+        {
+          "name": "Keywords History",
+          "description": "Get the historical organic keyword ranking distribution for a target domain or URL over a date range: how many keywords rank in each position bucket at each point in time."
+        },
+        {
+          "name": "Batch Analysis",
+          "description": "Get bulk SEO metrics (Domain Rating, backlinks, referring domains, organic traffic, and more) for multiple domains or URLs in a single request. Useful for comparing many competitors at once."
+        },
+        {
+          "name": "Site Audit Page Explorer",
+          "description": "Get crawled pages from an Ahrefs Site Audit project with health and SEO metrics: HTTP status, title, link counts, backlinks, indexability, and traffic. Optionally filter to pages affected by a specific issue."
+        },
+        {
+          "name": "Rank Tracker Overview",
+          "description": "Get ranking overview metrics for the keywords tracked in an Ahrefs Rank Tracker project: position, search volume, keyword difficulty, and estimated traffic. This endpoint is free and does not consume API units."
+        },
+        {
+          "name": "Rank Tracker SERP Overview",
+          "description": "Get the full SERP (search engine results page) for a keyword tracked in an Ahrefs Rank Tracker project, including every ranking URL with its position, title, and authority metrics. This endpoint is free and does not consume API units."
+        },
+        {
+          "name": "Rank Tracker Competitors Overview",
+          "description": "Get competitor rankings for the keywords tracked in an Ahrefs Rank Tracker project: each tracked keyword's volume and difficulty alongside every competitor's position, traffic, and traffic value. This endpoint is free and does not consume API units."
+        },
+        {
+          "name": "Rank Tracker Competitors Stats",
+          "description": "Get aggregate competitor stats for an Ahrefs Rank Tracker project: each competitor's traffic, traffic value, average position, and share of voice across all tracked keywords. This endpoint is free and does not consume API units."
         }
       ],
-      "operationCount": 10,
+      "operationCount": 23,
       "triggers": [],
       "triggerCount": 0,
       "authType": "api-key",

apps/sim/blocks/blocks/ahrefs.ts

@@ -0,0 +1,120 @@
+import type { AhrefsAnchorsParams, AhrefsAnchorsResponse } from '@/tools/ahrefs/types'
+import type { ToolConfig } from '@/tools/types'
+
+const SELECT_FIELDS = 'anchor,links_to_target,dofollow_links,refdomains,first_seen,last_seen'
+
+export const anchorsTool: ToolConfig<AhrefsAnchorsParams, AhrefsAnchorsResponse> = {
+  id: 'ahrefs_anchors',
+  name: 'Ahrefs Anchors',
+  description:
+    "Get the anchor text distribution for a target domain or URL's backlinks, showing how many links and referring domains use each anchor text.",
+  version: '1.0.0',
+
+  params: {
+    target: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description:
+        'The target domain or URL to analyze. Example: "example.com" or "https://example.com/page"',
+    },
+    mode: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Analysis mode: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match)',
+    },
+    history: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Historical scope: "live" (currently live), "all_time" (default, includes lost backlinks), or "since:YYYY-MM-DD" (backlinks found since a date)',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of results to return. Example: 50 (default: 1000)',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Ahrefs API Key',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const url = new URL('https://api.ahrefs.com/v3/site-explorer/anchors')
+      url.searchParams.set('target', params.target)
+      url.searchParams.set('select', SELECT_FIELDS)
+      if (params.mode) url.searchParams.set('mode', params.mode)
+      url.searchParams.set('history', params.history || 'all_time')
+      if (params.limit) url.searchParams.set('limit', String(params.limit))
+      return url.toString()
+    },
+    method: 'GET',
+    headers: (params) => ({
+      Accept: 'application/json',
+      Authorization: `Bearer ${params.apiKey}`,
+    }),
+  },
+
+  transformResponse: async (response: Response) => {
+    const data = await response.json()
+
+    if (!response.ok) {
+      throw new Error(data.error?.message || data.error || 'Failed to get anchors')
+    }
+
+    const anchors = (data.anchors || []).map((item: any) => ({
+      anchor: item.anchor || '',
+      backlinks: item.links_to_target ?? 0,
+      dofollowBacklinks: item.dofollow_links ?? 0,
+      referringDomains: item.refdomains ?? 0,
+      firstSeen: item.first_seen || '',
+      lastSeen: item.last_seen ?? null,
+    }))
+
+    return {
+      success: true,
+      output: {
+        anchors,
+      },
+    }
+  },
+
+  outputs: {
+    anchors: {
+      type: 'array',
+      description: 'Anchor text distribution for the backlink profile',
+      items: {
+        type: 'object',
+        properties: {
+          anchor: { type: 'string', description: 'The anchor text' },
+          backlinks: { type: 'number', description: 'Total backlinks using this anchor text' },
+          dofollowBacklinks: {
+            type: 'number',
+            description: 'Number of dofollow backlinks using this anchor text',
+          },
+          referringDomains: {
+            type: 'number',
+            description: 'Number of unique referring domains using this anchor text',
+          },
+          firstSeen: {
+            type: 'string',
+            description: 'When a link with this anchor was first found',
+          },
+          lastSeen: {
+            type: 'string',
+            description: 'When a backlink with this anchor was last seen (null if still live)',
+            optional: true,
+          },
+        },
+      },
+    },
+  },
+}

apps/sim/lib/integrations/integrations.json

@@ -0,0 +1,165 @@
+import type { AhrefsBatchAnalysisParams, AhrefsBatchAnalysisResponse } from '@/tools/ahrefs/types'
+import type { ToolConfig } from '@/tools/types'
+
+const SELECT_FIELDS =
+  'url,domain_rating,ahrefs_rank,backlinks,refdomains,org_traffic,org_keywords,paid_traffic'
+
+export const batchAnalysisTool: ToolConfig<AhrefsBatchAnalysisParams, AhrefsBatchAnalysisResponse> =
+  {
+    id: 'ahrefs_batch_analysis',
+    name: 'Ahrefs Batch Analysis',
+    description:
+      'Get bulk SEO metrics (Domain Rating, backlinks, referring domains, organic traffic, and more) for multiple domains or URLs in a single request. Useful for comparing many competitors at once.',
+    version: '1.0.0',
+
+    params: {
+      targets: {
+        type: 'string',
+        required: true,
+        visibility: 'user-or-llm',
+        description:
+          'Comma-separated list of domains or URLs to analyze. Example: "example.com,competitor.com"',
+      },
+      mode: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description:
+          'Analysis mode applied to every target: domain (entire domain), prefix (URL prefix), subdomains (include all subdomains, default), exact (exact URL match)',
+      },
+      protocol: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'Protocol applied to every target: "both" (default), "http", or "https"',
+      },
+      country: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'Country code for traffic data. Example: "us", "gb", "de" (default: "us")',
+      },
+      volumeMode: {
+        type: 'string',
+        required: false,
+        visibility: 'user-or-llm',
+        description: 'Search volume calculation: "monthly" or "average" (default: "monthly")',
+      },
+      apiKey: {
+        type: 'string',
+        required: true,
+        visibility: 'user-only',
+        description: 'Ahrefs API Key',
+      },
+    },
+
+    request: {
+      url: () => 'https://api.ahrefs.com/v3/batch-analysis/batch-analysis',
+      method: 'POST',
+      headers: (params) => ({
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${params.apiKey}`,
+      }),
+      body: (params) => {
+        const targets = params.targets
+          .split(',')
+          .map((target) => target.trim())
+          .filter((target) => target.length > 0)
+          .map((url) => ({
+            url,
+            mode: params.mode || 'subdomains',
+            protocol: params.protocol || 'both',
+          }))
+
+        return {
+          select: SELECT_FIELDS.split(','),
+          targets,
+          country: params.country || 'us',
+          volume_mode: params.volumeMode || 'monthly',
+        }
+      },
+    },
+
+    transformResponse: async (response: Response) => {
+      const data = await response.json()
+
+      if (!response.ok) {
+        throw new Error(data.error?.message || data.error || 'Failed to run batch analysis')
+      }
+
+      const results = (data.targets || []).map((item: any) => ({
+        url: item.url || '',
+        index: item.index ?? 0,
+        domainRating: item.domain_rating ?? null,
+        ahrefsRank: item.ahrefs_rank ?? null,
+        backlinks: item.backlinks ?? null,
+        referringDomains: item.refdomains ?? null,
+        organicTraffic: item.org_traffic ?? null,
+        organicKeywords: item.org_keywords ?? null,
+        paidTraffic: item.paid_traffic ?? null,
+        error: item.error ?? null,
+      }))
+
+      return {
+        success: true,
+        output: {
+          results,
+        },
+      }
+    },
+
+    outputs: {
+      results: {
+        type: 'array',
+        description: 'Bulk metrics for each analyzed target, in submission order',
+        items: {
+          type: 'object',
+          properties: {
+            url: { type: 'string', description: 'The analyzed target URL or domain' },
+            index: { type: 'number', description: 'Index of the target in the submitted list' },
+            domainRating: {
+              type: 'number',
+              description: 'Domain Rating score (0-100)',
+              optional: true,
+            },
+            ahrefsRank: {
+              type: 'number',
+              description: 'Ahrefs Rank (global ranking)',
+              optional: true,
+            },
+            backlinks: {
+              type: 'number',
+              description: 'Total backlinks to the target',
+              optional: true,
+            },
+            referringDomains: {
+              type: 'number',
+              description: 'Unique domains linking to the target',
+              optional: true,
+            },
+            organicTraffic: {
+              type: 'number',
+              description: 'Estimated monthly organic traffic',
+              optional: true,
+            },
+            organicKeywords: {
+              type: 'number',
+              description: 'Number of organic keywords ranked (top 100)',
+              optional: true,
+            },
+            paidTraffic: {
+              type: 'number',
+              description: 'Estimated monthly paid search traffic',
+              optional: true,
+            },
+            error: {
+              type: 'string',
+              description: 'Error message if this target could not be analyzed',
+              optional: true,
+            },
+          },
+        },
+      },
+    },
+  }