Ahrefs Integration with SmythOS
Want to put your SEO data on autopilot? Connect Ahrefs to SmythOS and let your agents fetch backlink profiles, monitor referring domains, and track SEO metrics in real time.
List of Ahrefs Components
Quickly compare Ahrefs components by what they do and their key I/O. Click any component name to jump directly to its detailed guide.
Component | Action | What it Does | Inputs | Key Outputs | Use Case |
---|---|---|---|---|---|
List All Backlinks | Read | Returns all backlinks for a URL, prefix, or domain. | required target , select optional limit | backlinks | Monitor link-building campaigns. |
List Broken Backlinks | Read | Retrieves backlinks pointing to broken pages on a target. | required target , select optional limit | backlinks | Find and reclaim lost link equity. |
List Referring Domains | Read | Fetches all unique domains linking to a target. | required target , select optional limit | refdomains | Analyze the quality of a link profile. |
List Anchors | Read | Extracts all anchor texts used in backlinks to a target. | required target , select optional limit | anchors | Audit anchor text for brand safety. |
Prerequisites
Before you begin, please ensure you have the following:
- An active SmythOS account. (Sign up here).
- An Ahrefs account with a subscription plan that includes API access.
- Your Ahrefs API Key.
Getting Started With Ahrefs
The connection between SmythOS and Ahrefs is configured using a secure API key.
Step 1: Get Your Ahrefs API Key
- Log in to your Ahrefs account.
- In the top-right corner, click on your profile icon and go to Account settings.
- From the left-hand menu, navigate to the API section.
- If you don't have a key, click Generate New API Key.
- Copy your API key.
Step 2: Store Your API Key in SmythOS Vault
Your Ahrefs API Key is a sensitive credential. Use the SmythOS Vault
to store it securely.
- In your SmythOS dashboard, navigate to the Vault.
- Create a new secret and paste your Ahrefs API Key as the value. Give it a memorable name, like
ahrefs_api_key
. - For more details, see the Vault Documentation.
Step 3: Configure an Ahrefs Component
- In your SmythOS agent graph, drag and drop any Ahrefs component.
- Click the component to open its Settings panel.
- In the
API Key
field, select the secret you saved in the Vault (e.g.,ahrefs_api_key
). - Your connection is now configured for that component.
Which Ahrefs Component Should I Use?
If you need to… | Target | Use this Component | Why this one? |
---|---|---|---|
Get a full list of links to a new blog post | A specific URL | List All Backlinks | Provides a complete list of every single backlink. |
Find link reclamation opportunities | Your domain | List Broken Backlinks | Pinpoints valuable links pointing to 404 pages. |
Assess the authority of a link profile | A competitor's domain | List Referring Domains | Shows the unique domains linking out, which is a key quality metric. |
Check for brand vs. keyword anchor text | Your homepage | List Anchors | Reveals how other sites are describing you in their links. |
Component Details
This section provides detailed information for each Ahrefs component.
List All Backlinks
Retrieves all backlinks pointing to a specific URL, domain, or prefix.
Inputs
Field | Required | Notes |
---|---|---|
target | required | The URL, domain (e.g., example.com ), or prefix (e.g., example.com/* ) to analyze. |
select | required | Comma-separated list of fields to return (e.g., url_from,anchor,domain_rating_source ). |
limit | optional | The maximum number of results to return (default: 100). |
Outputs
Field | Description |
---|---|
backlinks | An array of backlink objects containing the selected fields. |
response | The raw JSON response from the Ahrefs API. |
headers | HTTP headers from the API response, including rate limit information. |
{
"component": "ahrefs.listAllBacklinks",
"target": "smythos.com",
"select": "url_from,anchor,nofollow,domain_rating_source",
"limit": 500
}
List Broken Backlinks
Retrieves all backlinks that point to a broken (e.g., 404) page on the target.
Inputs
Field | Required | Notes |
---|---|---|
target | required | The URL, domain, or prefix to check for broken inbound links. |
select | required | Comma-separated list of fields (e.g., url_from,url_to,http_code ). |
limit | optional | The maximum number of results to return (default: 100). |
Outputs
Field | Description |
---|---|
backlinks | An array of objects, each detailing a broken backlink. |
response | The raw JSON response from the Ahrefs API. |
headers | HTTP headers from the API response. |
{
"component": "ahrefs.listBrokenBacklinks",
"target": "smythos.com",
"select": "url_from,url_to,anchor,domain_rating_source",
"limit": 200
}
List Referring Domains
Fetches all unique domains that link to the target, along with metrics for each domain.
Inputs
Field | Required | Notes |
---|---|---|
target | required | The URL, domain, or prefix to analyze. |
select | required | Comma-separated list of fields (e.g., refdomain,domain_rating,backlinks,traffic_domain ). |
limit | optional | The maximum number of results to return (default: 100). |
Outputs
Field | Description |
---|---|
refdomains | An array of objects, each representing a unique referring domain. |
response | The raw JSON response from the Ahrefs API. |
headers | HTTP headers from the API response. |
{
"component": "ahrefs.listReferringDomains",
"target": "competitor.com",
"select": "refdomain,domain_rating,first_seen,last_seen",
"limit": 1000
}
List Anchors
Extracts the anchor texts used in backlinks pointing to the target.
Inputs
Field | Required | Notes |
---|---|---|
target | required | The URL, domain, or prefix to inspect. |
select | required | Comma-separated list of fields (e.g., anchor,backlinks,refdomains ). |
limit | optional | The maximum number of results to return (default: 100). |
Outputs
Field | Description |
---|---|
anchors | An array of objects, each detailing an anchor text and its frequency. |
response | The raw JSON response from the Ahrefs API. |
headers | HTTP headers from the API response. |
{
"component": "ahrefs.listAnchors",
"target": "[smythos.com/blog/seo-automation](https://smythos.com/blog/seo-automation)",
"select": "anchor,backlinks,type",
"limit": 100
}
Best Practices & Advanced Tips
- Secure Your API Key: Your Ahrefs API key is a credential. Always use the SmythOS
Vault
to store it securely. Never expose it in plaintext in your agent's configuration. - Be Specific with
select
: To minimize your API credit usage and speed up your agent, only request the fields you absolutely need in theselect
parameter. - Handle Rate Limits: The Ahrefs API has usage limits. Design your agents to handle potential rate-limiting errors, perhaps by inspecting the response headers or building in small delays between large batches of requests.
- Paginate for Large Audits: For comprehensive audits, you may need more than the maximum
limit
of 1000 results. The Ahrefs API supports cursor-based pagination; you can build a looping mechanism in your agent to fetch all pages of results.
Troubleshooting Common Issues
-
Error:
401 Unauthorized
- Cause: The API key provided is invalid, has been revoked, or is not included in the request.
- Solution: Verify that the API key stored in your SmythOS Vault is correct and has not expired. Ensure the key is correctly selected in the component's settings.
-
Error:
402 Payment Required
- Cause: Your Ahrefs subscription has expired, or you have exhausted your API credits for the month.
- Solution: Check your subscription status and API usage in your Ahrefs account settings.
-
Empty
backlinks
orrefdomains
Array- Cause: The target may genuinely have no data, or the
target
parameter is formatted incorrectly. - Solution: Double-check the
target
. For domains, do not includehttp://
orwww.
. For prefixes, ensure it ends with a*
. Confirm in the Ahrefs UI that the target has data.
- Cause: The target may genuinely have no data, or the
What's Next?
You're now ready to build powerful, automated SEO workflows with the SmythOS Ahrefs Integration!
Consider these ideas:
-
Build an Agent That...
- Runs weekly, fetches all new backlinks using
List All Backlinks
, filters for links with a Domain Rating over 50, and logs them in a Google Sheet. - Monitors a competitor's domain with
List Referring Domains
, and when a new, high-quality domain is found, sends an alert to a Slack channel for your outreach team. - Performs a monthly health check by using
List Broken Backlinks
, generating a PDF report of the findings, and emailing it to the webmaster.
- Runs weekly, fetches all new backlinks using
-
Explore Other Integrations: Combine Ahrefs data with other SmythOS tools. Use the Google Sheets Integration for reporting, or the Gmail components to automate notifications.