# How to Integrate Retool with Ahrefs

- Tool: Retool
- Difficulty: Intermediate
- Time required: 25 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to Ahrefs by creating a REST API Resource with Ahrefs' API base URL and your API token in the Authorization header. Use Ahrefs' API to build a backlink monitoring dashboard — track referring domains, lost and new backlinks, organic keyword rankings, and Domain Rating trends for your sites and competitors from a centralized Retool SEO command center.

## Build an Ahrefs-Powered SEO Monitoring Dashboard in Retool

Ahrefs is the industry standard for backlink analysis, but switching between Ahrefs' web interface and other tools to correlate SEO data with content performance or business metrics is inefficient. Connecting Ahrefs to Retool lets you build a centralized SEO command center where your team can monitor backlinks, track referring domain growth, and review keyword positions alongside the internal data — content publish dates, campaign launches, technical SEO changes — that explains why metrics shift.

With a Retool-Ahrefs integration, your SEO and content teams can track Domain Rating and URL Rating changes for your site, monitor new and lost backlinks daily, compare competitor referring domain counts, identify broken backlinks pointing to your site, and check organic keyword rankings for target pages — all in a configurable panel that your team builds and adapts without depending on Ahrefs' fixed report views.

Ahrefs' API uses token-based authentication with your API token sent in the Authorization header as a Bearer token. The API provides access to Site Explorer data (backlinks, referring domains, organic keywords, paid keywords, outgoing links) and batch analysis endpoints. Retool's server-side proxy keeps your Ahrefs token secure, and Retool Workflows can be configured to run daily checks and alert your Slack channel when high-authority backlinks are lost.

## Before you start

- An Ahrefs account with API access (available on Advanced and Enterprise plans; API access is charged separately per unit)
- An Ahrefs API token generated from your Ahrefs account settings under API
- The target domains you want to monitor stored as configuration variables or accessible via a Retool Text Input
- A Retool account with permission to create Resources
- Familiarity with Retool's query editor, Table component, and Chart component

## Step-by-step guide

### 1. Create an Ahrefs REST API Resource in Retool

Navigate to the Resources tab in your Retool instance and click Add Resource. Select REST API from the resource type list. Name the resource 'Ahrefs API'.

In the Base URL field, enter https://api.ahrefs.com/v3. This is Ahrefs' current REST API base URL. All endpoint paths you write in queries will be appended to this base.

For authentication, Ahrefs uses an API token sent as a Bearer token in the Authorization header. In the Authentication section, select Bearer Token from the dropdown. In the Token field, enter your Ahrefs API token, or reference a configuration variable: {{ retoolContext.configVars.AHREFS_API_TOKEN }}.

To use a configuration variable (recommended for team instances), first go to Settings → Configuration Variables, create a new variable named AHREFS_API_TOKEN, paste your API token as the value, and mark it as Secret. Then return to the resource and use the {{ retoolContext.configVars.AHREFS_API_TOKEN }} reference in the Bearer Token field.

Add a default header: key = Accept, value = application/json. Click Save Changes. Your Ahrefs resource is now configured and ready for queries.

**Expected result:** The Ahrefs API resource appears in your Resources list with Bearer token authentication. A test GET query to /site-explorer/domain-rating?target=ahrefs.com returns domain metrics, confirming the connection and authentication are working.

### 2. Query backlinks and referring domains for a target site

Create your first Ahrefs query to pull backlink data. In your Retool app, open the Code panel and add a new query. Name it getBacklinks and select the Ahrefs API resource.

Set Method to GET and Path to /site-explorer/all-backlinks. Add URL parameters:
- key = target, value = {{ textInput_domain.value || 'yourdomain.com' }}
- key = limit, value = 100
- key = order_by, value = domain_rating_source:desc
- key = mode, value = subdomains (covers the full domain including subdomains)
- key = date_from, value = {{ moment().subtract(30, 'days').format('YYYY-MM-DD') }}

Create a second query named getNewBacklinks with the same parameters but add: key = where, value = is_new:true. This filters to only backlinks added in the date window.

Create a third query named getLostBacklinks: same base parameters, add key = where, value = is_lost:true.

Create a fourth query named getReferringDomains with Path /site-explorer/refdomains and the same target parameter. This returns aggregate data per referring domain rather than individual backlinks.

Add a Text Input component named textInput_domain so users can enter any domain to analyze. Set all queries to run on change of this component.

```
// JavaScript transformer — format backlinks for Table component
const links = (data.backlinks || []);
return links.map(link => {
  return {
    source_url: link.url_from || 'N/A',
    target_url: link.url_to || 'N/A',
    source_domain: link.domain_from || 'N/A',
    domain_rating: link.domain_rating_source || 0,
    anchor_text: link.anchor || '(no anchor)',
    link_type: link.type || 'dofollow',
    first_seen: link.first_seen
      ? new Date(link.first_seen).toLocaleDateString()
      : 'N/A',
    last_seen: link.last_visited
      ? new Date(link.last_visited).toLocaleDateString()
      : 'N/A',
    is_dofollow: link.nofollow === false ? 'Yes' : 'No'
  };
});
```

**Expected result:** The backlinks query returns a table of inbound links with source domain, DR, anchor text, and link type. The new vs. lost backlink queries populate separate tables, and the referring domains query shows domain-level aggregates.

### 3. Build domain metrics and Domain Rating trend queries

Create queries to pull high-level domain authority metrics and track Domain Rating over time. Create a query named getDomainRating. Set Method to GET and Path to /site-explorer/domain-rating. Add URL parameters:
- key = target, value = {{ textInput_domain.value }}
- key = date, value = {{ moment().format('YYYY-MM-DD') }} (today's metrics)

This returns the current Domain Rating and the URL Rating for the root domain, along with total backlink counts.

For historical DR trend data, create a query named getDRHistory with Path /site-explorer/domain-rating-history and an additional parameter: key = history_grouping, value = monthly. This returns DR values at monthly intervals so you can chart Domain Rating growth over time.

Create a Chart component in your Retool app. Set the Chart data to {{ getDRHistory.data?.domain_rating_history || [] }}. Configure the chart type as Line, x-axis as the date field, and y-axis as the domain_rating field.

Add summary stat components showing the current DR, total referring domains, and total backlink count pulled from getDomainRating. Format these using a JavaScript transformer that extracts the key fields from the API response and rounds numbers appropriately.

For competitor comparison, add a multi-domain Text Input or a Table of competitor domains, then use a JavaScript query that loops through each domain, triggers getDomainRating for each, and returns an array of domain comparison objects for a summary comparison table.

```
// JavaScript transformer — format domain rating history for Chart component
const history = (data.domain_rating_history || []);
return history.map(entry => ({
  date: entry.date,
  domain_rating: entry.domain_rating || 0,
  backlinks: entry.backlinks || 0,
  refdomains: entry.refdomains || 0
})).sort((a, b) => new Date(a.date) - new Date(b.date));
```

**Expected result:** The domain metrics panel shows current DR, total referring domains, and total backlinks as stat components. The line chart shows Domain Rating growth over the past 12 months based on the history endpoint response.

### 4. Query organic keyword rankings for target pages

Create queries to track organic keyword positions for your most important pages. Create a query named getOrganicKeywords. Set Method to GET and Path to /site-explorer/organic-keywords. Add URL parameters:
- key = target, value = {{ textInput_url.value }} (a specific page URL or domain)
- key = limit, value = 100
- key = order_by, value = traffic:desc
- key = mode, value = exact (for specific URL) or subdomains (for full domain)
- key = country, value = {{ dropdown_country.value || 'us' }}

This returns the top organic keywords driving traffic to the target URL, with current position, search volume, keyword difficulty, and estimated traffic.

Add a Text Input component for the URL input and a Dropdown for country selection with common country codes (us, gb, au, ca, etc.).

Create a second query named getPositionHistory with Path /site-explorer/positions-history and a specific keyword parameter to track ranking history for a selected keyword over time.

Bind the getOrganicKeywords results to a Table component named table_keywords. When a row is selected, trigger getPositionHistory for the selected keyword to show its ranking history in a Chart component below the table.

Add a JavaScript transformer to the keyword query that adds a position_change_indicator field (up, down, or stable) based on the previous vs. current position values, which you can use to color-code rows in the Table.

```
// JavaScript transformer — format organic keywords with change indicators
const keywords = (data.keywords || []);
return keywords.map(kw => {
  const posChange = (kw.pos_prev || kw.pos) - kw.pos;
  return {
    keyword: kw.keyword,
    position: kw.pos,
    position_change: posChange > 0 ? `+${posChange}` : posChange.toString(),
    change_direction: posChange > 0 ? 'improved' : posChange < 0 ? 'dropped' : 'stable',
    search_volume: kw.volume ? kw.volume.toLocaleString() : '0',
    keyword_difficulty: kw.kd || 0,
    estimated_traffic: kw.traffic ? kw.traffic.toLocaleString() : '0',
    serp_features: Array.isArray(kw.serp_features) ? kw.serp_features.join(', ') : '',
    url: kw.url || 'N/A'
  };
});
```

**Expected result:** The organic keywords table shows top-traffic keywords for the entered URL with current position, volume, difficulty, and position change indicators. Selecting a keyword row loads the position history chart showing ranking trends over time.

### 5. Set up a lost backlink alert Workflow

Create a Retool Workflow that runs on a daily schedule to check for lost high-authority backlinks and alert your team via Slack or email. Navigate to Workflows in your Retool instance and create a new Workflow named 'Daily Lost Backlink Check'.

Add a Schedule trigger set to run every day at 8:00 AM. Add a Resource Query block targeting your Ahrefs API resource. Configure it as a GET request to /site-explorer/all-backlinks with parameters:
- target: your primary domain (stored as a Workflow variable or configuration variable)
- where: is_lost:true
- date_from: yesterday's date using a JavaScript expression
- limit: 100
- order_by: domain_rating_source:desc

Add a Filter block or JavaScript Code block after the Ahrefs query to filter only backlinks where domain_rating_source >= 40. This focuses alerts on meaningful link losses rather than spammy link churn.

Add a Branch block: if the filtered results array has length > 0, trigger the alert path. In the alert path, add a Resource Query block targeting your Slack resource with a message summarizing the number of lost high-DR backlinks and listing the top 5 by Domain Rating.

For RapidDev implementations, this Workflow pattern — daily API query → filter → conditional Slack alert — is a reusable template for any monitoring scenario where you need proactive notifications rather than reactive dashboard checks.

```
// JavaScript Code block — format lost backlinks for Slack message
const lostLinks = previousBlock.data?.backlinks || [];
const highDrLost = lostLinks.filter(link => (link.domain_rating_source || 0) >= 40);

if (highDrLost.length === 0) {
  return { should_alert: false, message: 'No high-DR backlinks lost today.' };
}

const topLinks = highDrLost.slice(0, 5);
const summary = topLinks.map(
  link => `• DR${link.domain_rating_source} — ${link.domain_from} → ${link.url_to}\n  Anchor: "${link.anchor || 'none'}"`
).join('\n');

return {
  should_alert: true,
  count: highDrLost.length,
  message: `🔴 ${highDrLost.length} high-DR backlink(s) lost today:\n\n${summary}\n\nReview in Retool: https://retool.yourcompany.com/apps/seo-backlink-monitor`
};
```

**Expected result:** The Workflow runs each morning, queries Ahrefs for lost backlinks from the previous day, filters to DR 40+ links, and sends a formatted Slack message if any high-authority losses are detected. The Workflow shows green in the run history log when it completes successfully.

## Best practices

- Store your Ahrefs API token in a Secret configuration variable in Retool — never paste tokens directly into query parameter fields or share them in app URLs.
- Cache Ahrefs API responses in Retool Database using scheduled Workflows — Ahrefs API calls consume units from a limited monthly budget, so pre-caching daily data dramatically reduces consumption compared to on-demand queries.
- Set up a Retool Workflow for daily lost backlink monitoring rather than expecting your team to check the dashboard proactively — proactive alerts catch time-sensitive link losses before they affect rankings.
- Use the domain_rating_source >= 40 filter for backlink alerts to focus on meaningful link changes and avoid alert fatigue from low-quality link churn.
- Build separate Retool apps for different SEO audiences — a high-level dashboard with DR and referring domain trends for leadership, and a detailed backlink analysis panel with anchor text and link type breakdowns for the SEO team.
- Combine Ahrefs backlink data with your content database in the same Retool app to correlate link acquisition spikes with specific content publication dates and campaign launches.
- Use Ahrefs' batch analysis endpoint when analyzing multiple URLs simultaneously to reduce API unit consumption compared to making individual requests per URL.

## Use cases

### Build a backlink monitoring dashboard with new and lost link alerts

Create a Retool dashboard that queries Ahrefs for new and lost backlinks within a configurable date window. Display referring domains by Domain Rating, anchor text distribution, and link type. Set up a Retool Workflow that runs daily, queries lost backlinks, and posts a Slack message when a referring domain with DR 50+ is lost.

Prompt example:

```
Build a backlink monitoring panel that fetches new_backlinks and lost_backlinks from Ahrefs' Site Explorer API for a target domain, displays them in separate Tables with DR, anchor text, and target URL columns, and shows a bar chart of daily link velocity over the past 30 days.
```

### Competitor referring domain comparison dashboard

Build a Retool app that queries Ahrefs' referring domains endpoint for your domain and up to four competitor domains. Display side-by-side charts showing referring domain growth over time, Domain Rating distribution, and new vs. lost domain velocity for each competitor.

Prompt example:

```
Create a competitor analysis panel with a multi-input for domain names, Chart components showing referring domain count over 90 days per domain from Ahrefs' API, and a summary table with current DR, total backlinks, and total referring domains for each domain sorted by DR descending.
```

### Organic keyword ranking tracker for target pages

Build a ranking tracker that queries Ahrefs' organic keywords endpoint for specific URLs on your site. Show current position, search volume, traffic estimate, and position change over the past 30 days for the top 100 keywords driving traffic to each target page. Add position change indicators so the team can spot rapid drops requiring immediate attention.

Prompt example:

```
Build a keyword ranking dashboard where entering a URL triggers a query to Ahrefs' organic keywords endpoint, displays a Table of keywords with position, volume, difficulty, and 30-day position change, and highlights rows in red where position dropped more than 5 places.
```

## Troubleshooting

### Ahrefs API returns 402 Payment Required or 429 Too Many Requests

Cause: The 402 error means your Ahrefs API unit balance is exhausted for the current billing period. The 429 error means you have hit the API rate limit for concurrent requests.

Solution: For 402 errors, check your Ahrefs account API usage page to see unit consumption and refill or upgrade your API plan. To reduce unit consumption in Retool, cache Ahrefs data in Retool Database using a scheduled Workflow rather than querying Ahrefs directly on every dashboard load. For 429 errors, reduce the number of queries triggered simultaneously — use event-driven query chaining instead of running multiple Ahrefs queries on page load.

### Backlinks query returns 'Invalid target' or empty results for a valid domain

Cause: The domain format in the target parameter is incorrect. Ahrefs' API requires the domain without protocol (no https://) and without a trailing slash. Some endpoints also require you to specify the mode parameter (exact, prefix, domain, or subdomains) to determine how the target is matched.

Solution: Strip the protocol and trailing slash from the domain input. Use a JavaScript expression in the URL parameter value field: {{ textInput_domain.value.replace(/^https?:\/\//, '').replace(/\/$/, '') }}. Also ensure the mode parameter is set appropriately — use domain for full domain analysis or exact for a specific URL.

```
// URL parameter value — clean domain input for Ahrefs API
{{ textInput_domain.value.replace(/^https?:\/\//, '').replace(/\/$/, '').toLowerCase() }}
```

### Organic keywords query returns results but position values are all null

Cause: The country parameter may be set to a country where Ahrefs has insufficient data for the target domain, or the URL has no ranking keywords in that country's Google index.

Solution: Test with country=us first as Ahrefs has the most comprehensive data for the US Google index. If the domain is non-English, switch to the appropriate country code. Also verify the target URL is indexed by Google — Ahrefs cannot show positions for URLs that have no organic visibility in the specified country.

### Lost backlink Workflow runs but sends no alerts even when backlinks are clearly lost

Cause: The date_from parameter in the Workflow may be using the wrong date format, causing Ahrefs to return an empty date range. Alternatively, the Workflow's filter condition for DR threshold may be filtering out all results.

Solution: Verify the date_from parameter produces a valid YYYY-MM-DD string. In the Workflow JavaScript Code block, add a log statement: console.log('Lost links found:', lostLinks.length) to verify how many links the API returned before filtering. Lower the DR threshold temporarily to DR 10+ to verify the query is returning data, then raise it once you confirm the filter logic is correct.

## Frequently asked questions

### Does Ahrefs have a native connector in Retool?

No, Ahrefs does not have a native connector in Retool. You connect it using Retool's generic REST API Resource type with Bearer token authentication. All Ahrefs data — backlinks, referring domains, organic keywords, and domain metrics — is accessible through queries to Ahrefs' v3 REST API endpoints configured in the resource.

### What Ahrefs plan is required to access the API?

Ahrefs API access is available on Advanced and Enterprise plans. The API is priced separately from the core Ahrefs subscription based on API units consumed per request. Each API call deducts a number of units proportional to the amount of data returned. Check Ahrefs' API pricing page for current unit rates per endpoint type.

### How do I reduce Ahrefs API unit consumption in my Retool dashboards?

The most effective approach is to use Retool Workflows on a schedule (daily or hourly) to fetch Ahrefs data and store it in Retool Database or your own PostgreSQL database. Your Retool dashboard apps then query the cached data instead of calling Ahrefs directly, eliminating per-refresh API unit consumption. Only trigger live Ahrefs queries for on-demand lookups where fresh data is critical.

### Can I track keyword rankings for multiple sites in the same Retool dashboard?

Yes. Build a Retool app with a multi-domain input (or a Table of domains loaded from your own database) and use Retool's JavaScript query to iterate through each domain, calling the Ahrefs organic keywords endpoint for each. Combine the results into a unified comparison table. For team use, the cached database pattern works well — nightly Workflows pull rankings for all tracked domains and update a shared database table.

---

Source: https://www.rapidevelopers.com/retool-integrations/ahrefs
© RapidDev — https://www.rapidevelopers.com/retool-integrations/ahrefs