# Ahrefs

## Ahrefs Integration

Import your keyword research and SEO data from Ahrefs to supercharge your content strategy. Cuppa supports two ways to use Ahrefs data: **CSV Import** (available to all plans) and **API Integration** (Enterprise plans).

### What You Can Do

* **Import keyword data** from any Ahrefs report (Keywords Explorer, Site Explorer, Content Gap, etc.)
* **Auto-map columns** from Ahrefs CSV exports for quick imports
* **Cluster and prioritize** your keywords automatically with AI
* **Feed the Link Engine** with SEO data to improve internal linking
* **Track data provenance** with links back to the original Ahrefs report

***

### Two Ways to Connect

#### Option 1: CSV Import (All Plans)

Upload CSV exports from Ahrefs whenever you need to import keyword data. Perfect for:

* One-time keyword research imports
* Quarterly content planning refreshes
* Ad-hoc competitive analysis

#### Option 2: API Integration (Enterprise Plans)

Connect your Ahrefs API for automated data pulls. Ideal for:

* Scheduled keyword monitoring
* Automated backlink tracking
* Continuous content gap analysis

***

### CSV Import Guide

#### Step 1: Export Data from Ahrefs

1. Go to any Ahrefs tool (Keywords Explorer, Site Explorer, Content Gap, etc.)
2. Run your desired report
3. Click the **Export** button
4. Select **CSV** format
5. Download the file

> 💡 **Tip**: Keep the Ahrefs report URL handy — Cuppa lets you store it for traceability!

#### Step 2: Import to Cuppa

1. Go to **Keywords** → **Import**
2. Select **Ahrefs** as your source tool
3. (Optional) Paste the Ahrefs report URL for reference
4. Enter your target domain
5. (Optional) Add business focus and competitor domains for better clustering
6. Click **Select CSV File**

#### Step 3: Map Your Columns

Cuppa will auto-detect common Ahrefs column names:

| Ahrefs Column           | Cuppa Field        |
| ----------------------- | ------------------ |
| Keyword                 | Keyword            |
| Volume / Search Volume  | Search Volume      |
| KD / Keyword Difficulty | Keyword Difficulty |
| CPC                     | CPC                |
| Clicks                  | Clicks             |
| Traffic                 | Traffic            |
| Position                | Current Position   |
| URL                     | URL                |
| Country                 | Country            |

If your columns have different names, you can manually map them in the interface.

#### Step 4: Process Your Keywords

After mapping, Cuppa will:

1. **Validate** your data
2. **Normalize** metrics to a standard format
3. **Cluster** related keywords together using AI
4. **Prioritize** based on volume, difficulty, and relevance

You'll be redirected to your keyword batch where you can review clusters and create content briefs.

***

### Supported Ahrefs Reports

Cuppa supports CSV exports from any Ahrefs tool:

| Report Type                          | Use Case                               |
| ------------------------------------ | -------------------------------------- |
| **Keywords Explorer**                | General keyword research               |
| **Site Explorer - Organic Keywords** | Audit your current rankings            |
| **Content Gap**                      | Find keywords competitors rank for     |
| **Keyword Ideas**                    | Expand on seed keywords                |
| **Matching Terms**                   | Find keywords containing your terms    |
| **Related Terms**                    | Discover semantically related keywords |
| **Questions**                        | Find question-based keywords           |
| **Also Rank For**                    | Find related opportunities             |
| **Traffic Share**                    | Domain-level analysis                  |

***

### API Integration Guide (Enterprise)

#### Prerequisites

* **Ahrefs API subscription** (separate from your Ahrefs web subscription)
* **Cuppa Enterprise plan**

#### Step 1: Get Your Ahrefs API Key

1. Go to [ahrefs.com/api](https://ahrefs.com/api)
2. Sign up for an API plan if you haven't already
3. Navigate to your API settings
4. Copy your API key

#### Step 2: Connect in Cuppa

1. Go to **Team Settings** → **Integrations**
2. Find **Ahrefs** in the Connections section
3. Click **Connect API**
4. Enter your:
   * **API Key**
   * **API Tier** (Lite, Standard, Advanced, or Enterprise)
5. Click **Connect**

#### Step 3: Configure Automated Syncs

Once connected, you can set up:

* **Keyword monitoring** for your domains
* **Backlink alerts** for new or lost links
* **Scheduled data pulls** to keep your keyword data fresh

***

### How AI Clustering Works

When you import keywords, Cuppa's AI:

1. **Groups related keywords** into topical clusters
2. **Identifies search intent** (informational, commercial, transactional)
3. **Suggests page types** (blog post, landing page, comparison, etc.)
4. **Calculates priority scores** based on:

```
Priority Score = 
  (Volume Score × 0.35) +      // Higher volume = better
  (Difficulty Score × 0.30) +  // Lower difficulty = better
  (Intent Score × 0.20) +      // Transactional > Commercial > Info
  (Page Type Score × 0.15)     // How-To > Comparison > Blog
```

***

### Best Practices

#### For CSV Imports

1. **Include the report URL** — Makes it easy to return to Ahrefs for deeper analysis
2. **Set your target domain** — Helps with relevance scoring and prioritization
3. **Add competitor domains** — Enables gap analysis in clustering
4. **Be specific with business focus** — Better context = better clustering

#### For API Integration

1. **Match your API tier** — Ensures Cuppa respects your rate limits
2. **Start with key domains** — Don't try to monitor everything at once
3. **Review automated data** — Schedule regular reviews of synced data

***

### How Imported Data Is Used

#### In Content Planning

* Keyword clusters become content briefs
* Priority scores help you focus on high-impact topics
* Difficulty scores inform your content strategy

#### In the Link Engine

* Imported keywords inform semantic matching
* Traffic data helps prioritize which pages to link to
* Your existing rankings influence link suggestions

#### In SEO Clusters

* Imported keywords populate your cluster library
* AI identifies gaps in your current content
* Recommendations are based on your actual keyword data

#### In Brand Research

* Imported competitor data enriches competitive analysis
* Content gap insights inform strategy recommendations

***

### Troubleshooting

#### CSV Import Issues

**"Required field missing"**

* Ensure you have at least a "Keyword" column mapped
* Check that your CSV isn't empty

**"Invalid difficulty value"**

* Difficulty should be 0-100
* Check for unexpected characters or formatting

**"Too many rows"**

* Maximum import is 10,000 keywords per batch
* Split large exports into multiple imports

#### API Connection Issues

**"Invalid API key"**

* Double-check your key was copied correctly
* Ensure your Ahrefs API subscription is active

**"Rate limit exceeded"**

* Select the correct API tier in settings
* Reduce the number of domains being monitored

**"Connection failed"**

* Check your Ahrefs API subscription status
* Contact <support@cuppa.ai> if issues persist

***

### Data Privacy & Security

* Your Ahrefs API key is encrypted at rest
* CSV uploads are processed and stored securely
* We never share your SEO data with third parties
* You can disconnect and delete your data at any time

***

### FAQ

**Can I import from multiple Ahrefs accounts?** Yes, CSV import works with any Ahrefs account. For API integration, you can connect one API key per team.

**How often can I import CSV data?** As often as you like! There's no limit on CSV imports.

**Does the API integration cost extra?** The Ahrefs API has its own pricing (separate from Ahrefs web plans). Cuppa's Enterprise plan includes the API integration feature at no additional cost.

**Can I mix CSV imports and API data?** Absolutely. CSV imports and API syncs are complementary — use whichever method fits your workflow.

**How long is my imported data stored?** Keyword data is stored indefinitely or until you delete it. You can manage your keyword batches in the Keywords section.

**What happens to my existing keyword clusters?** New imports create new batches. Your existing clusters remain unchanged unless you delete them.

**Can I re-import the same CSV?** Yes, but it will create a new batch. Cuppa doesn't deduplicate across batches.

**Which Ahrefs plans work with CSV import?** Any Ahrefs plan that allows CSV export (which is all of them).

***

### Related Features

* Keyword Import — Full guide to importing keywords
* SEO Clusters — Organize and prioritize your keyword clusters
* Link Engine — Use keyword data for smarter internal linking
* Content Planner — Plan content from your keyword clusters

***

### Need Help?

* Check our [Help Center](https://learn.cuppa.ai)
* Contact support at <support@cuppa.ai>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://learn.cuppa.ai/integrations/ahrefs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.