> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mavera.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SEMrush

> 5 production-ready jobs — keyword gap content generation, competitor content audit, keyword cluster focus groups, backlink outreach content, and position tracking executive reports

SEMrush holds your competitive intelligence — which keywords your rivals rank for, what content earns them links, and where your search visibility is shifting. These five jobs pull that data through Mavera's surfaces (Mave Agent, Custom Personas, Focus Groups, Brand Voices, Generate) so your SEO strategy, outreach, and content plans are grounded in competitive data rather than intuition.

## API Reference Card

| Detail              | Value                                                  |
| ------------------- | ------------------------------------------------------ |
| **Base URL**        | `https://api.semrush.com/`                             |
| **Auth**            | API key as query parameter (`?key=YOUR_KEY`)           |
| **Rate limits**     | 10 requests per second                                 |
| **Response format** | Semicolon-delimited text (not JSON) for most endpoints |
| **Mavera base**     | `https://app.mavera.io/api/v1`                         |
| **Mavera auth**     | `Authorization: Bearer mvra_live_...`                  |

<Info>
  All examples use two environment variables: `SEMRUSH_API_KEY` and `MAVERA_API_KEY`. SEMrush returns semicolon-delimited text for most endpoints — Python examples parse with `csv.reader(delimiter=';')` and JavaScript examples split lines by `\n` then each by `;`. Each API call consumes units from your SEMrush plan; check your balance at [SEMrush → Subscription Info](https://www.semrush.com/billing-admin/profile/subscription).
</Info>

## Prerequisites

<Steps>
  <Step title="SEMrush API key with available units">Log in to [SEMrush](https://www.semrush.com/) and navigate to your profile settings to find your API key. Verify that your plan includes API units — most Pro plans include 10,000 units/month.</Step>
  <Step title="Mavera API key">Generate a key at [app.mavera.io/settings/api-keys](https://app.mavera.io/settings/api-keys). The key starts with `mvra_live_`.</Step>

  <Step title="Install dependencies">
    ```bash theme={"dark"}
    pip install requests
    ```
  </Step>

  <Step title="Environment variables">
    ```bash theme={"dark"}
    export SEMRUSH_API_KEY="your_semrush_api_key_here"
    export MAVERA_API_KEY="mvra_live_xxxxx"
    ```
  </Step>
</Steps>

## Jobs

| # | Job                                                                         | SEMrush Data                    | Mavera Surface            | Output                                       |
| - | --------------------------------------------------------------------------- | ------------------------------- | ------------------------- | -------------------------------------------- |
| 1 | [Keyword Gap → Content Generation](keyword-gap-content)                     | domain\_domains                 | Mave Agent                | Content briefs for uncovered keywords        |
| 2 | [Competitor Content Audit](competitor-content-audit)                        | url\_organic                    | Mave Agent + Focus Groups | Messaging gap analysis with persona feedback |
| 3 | [Keyword Clusters → Focus Group Validation](keyword-focus-group-validation) | phrase\_related                 | Personas + Focus Groups   | Validated content concepts per cluster       |
| 4 | [Backlink Analysis → Outreach Content](backlink-outreach-content)           | backlinks\_overview + backlinks | Brand Voices + Generate   | Outreach email variants by link type         |
| 5 | [Position Tracking → Performance Reports](position-tracking-reports)        | domain\_organic                 | Mave Agent                | Executive ranking narrative with actions     |

***

## Rate Limits & Production Notes

| SEMrush Endpoint     | Unit Cost   | Caching Strategy                           |
| -------------------- | ----------- | ------------------------------------------ |
| domain\_domains      | 10-40 units | Cache daily — gaps don't shift hourly      |
| url\_organic         | 10 units    | Cache 24h — competitor pages change slowly |
| phrase\_related      | 10 units    | Cache per seed keyword for 7 days          |
| backlinks / overview | 20-70 units | Cache 48h — profiles update slowly         |
| domain\_organic      | 10 units    | Cache 24h — positions shift daily at most  |

<Warning>
  SEMrush enforces **10 requests/second**. All jobs include delays. In production, add a centralized rate limiter for concurrent jobs. `ERROR 130 :: TOO MANY REQUESTS` — retry after 1s with exponential backoff.
</Warning>

<Tip>
  Always use `csv.reader(delimiter=";")` in Python and split-then-validate in JavaScript. Raw `.split(";")` breaks on quoted fields or semicolons inside keyword text.
</Tip>

| Concern          | Recommendation                                                        |
| ---------------- | --------------------------------------------------------------------- |
| API key security | Store in a secrets manager. Never commit to version control.          |
| Unit monitoring  | Check balance before batch runs. Full backlink audit costs 90+ units. |
| Response caching | SEMrush data updates daily at most. Cache with 24-48h TTL.            |
| Mavera credits   | Monitor at [Dashboard](https://app.mavera.io/settings/usage).         |
| Baseline storage | Use a database or versioned JSON for trend analysis.                  |

## What's Next

<CardGroup cols={2}>
  <Card title="All Integrations" icon="plug" href="/integrations">
    50+ API integrations with full code
  </Card>

  <Card title="SEMrush API Docs" icon="magnifying-glass" href="https://developer.semrush.com/api/">
    Official SEMrush API reference
  </Card>

  <Card title="Mave Agent" icon="brain" href="/api-reference/mave">
    Full reference for POST /api/v1/mave/chat
  </Card>

  <Card title="Focus Groups API" icon="comments" href="/api-reference/focus-groups">
    Full reference for POST /api/v1/focus-groups
  </Card>

  <Card title="Generate API" icon="wand-magic-sparkles" href="/api-reference/generations">
    Full reference for POST /api/v1/generations
  </Card>

  <Card title="Brand Voices API" icon="bullhorn" href="/api-reference/brand-voices">
    Full reference for POST /api/v1/brand-voices
  </Card>
</CardGroup>