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

# Semrush

> Connect your own Semrush account to see its backlinks, rankings and keyword data beside your Google data, inside a unit budget you control.

Connect your Semrush account and Weelkit adds Semrush figures to your metrics: estimated organic traffic, keyword positions, backlinks and referring domains, each article's ranking keywords, and keyword research. Weelkit uses your own Semrush account and your own keys, so the units it spends come out of your Semrush balance.

Every Semrush figure is an estimate. Weelkit marks it **Estimate**, credits Semrush as the source, and shows it beside your Google data. It never adds Semrush figures to Google's numbers.

## Before you start

* **Who can connect it:** an Admin or a Managing Editor. A custom role can connect it when it includes the permission to create, configure and remove organization integration connections. See [Roles and permissions](https://docs.weelkit.com/get-started/roles.md).
* **Who sees the data:** every role that can see Metrics: Editors, Managing Editors and Admins. Keyword research in the editor also needs edit access to the article.
* **What you need:** a Semrush account with a balance of API units. An organization has one Semrush connection.

## Connect

**1. Create the v4 key in Semrush**

In Semrush, open **Profile → API keys** (see [Semrush's key guide](https://developer.semrush.com/api/get-started/authorization)) and create a v4 key with read-only permission and an expiry. Copy it.

**2. Copy the v3 key**

The same **Profile → API keys** section shows your account-wide v3 key. Weelkit uses it only for the domain and URL reports that still run on v3. Semrush can't revoke it, so keep it private.

**3. Start the connection**

Open [Organization settings → Integrations](https://docs.weelkit.com/settings/organization.md#integrations) (Managing Editors open **Integration**). In the **SEO** section, find **Semrush** and choose **Connect**.

**4. Paste both keys**

Paste the v4 key into **Semrush API key (v4)** and the v3 key into **Semrush v3 key**, then choose **Connect**. Weelkit checks your unit balance, which spends no units. A message says **Semrush connection saved**.

**5. Check the card**

The **Semrush** card shows your plan, the last four characters of the key (for example **•••• 4f2a**), and **Weelkit used 0 of N units this month**. Open the card's **⋯** menu and choose **Test connection** to check it again. It says **Connected to Semrush**.

The first data arrives with the next scheduled pull, and Weelkit only pulls data someone has looked at. Open **Analytics** or a published article's **Performance** page. Until the first pull, the panels say "Data arrives with the next sync."

## What Weelkit asks Semrush for

Weelkit sends Semrush your keys, your site's domain, the public addresses of your published articles, and the keyword when you research one. Your site is the site in your Search Console property, or else the site where your published articles live. If Weelkit can't find it yet, the panels say so.

## Where you see it

| Where | What it shows |
| - | - |
| Analytics → Overview, **Search estimates** | **Estimated organic traffic**, with a trend line. |
| Analytics → Search, **Ranking keywords** | The keywords your site ranks for, from Semrush: **Keyword**, **Position**, **Previous position**, **Volume** and **URL**. The first 10 show. |
| Analytics → **Links** | **Top referring domains**, **New referring domains** and **Lost referring domains**. |
| [Performance](https://docs.weelkit.com/metrics/performance.md#the-article-page), an article's page, **Links and rankings** | That article's **Backlinks**, **Referring domains**, **Authority Score** and **Ranking keywords**. |
| [Performance → Search](https://docs.weelkit.com/metrics/performance.md#search), **Opportunities** → **View all**, **Sites competing for your keywords** | **Site**, **Keywords in common** and **Estimated traffic** for sites that rank for the keywords you rank for. |
| Editor, **SEO & Metadata** → **SEO** tab, **Keyword research** | Type a **Seed keyword** and choose **Research keywords** for volume, difficulty, traffic potential, ideas and questions. |
| [Chat](https://docs.weelkit.com/chat/what-the-ai-can-do.md) | Ask the AI for keyword ideas. It names Semrush and labels the figures as estimates. |

Semrush has no site audit or AI visibility data that Weelkit can read, so **Site audit** and **AEO & GEO → Benchmarks** don't use it. **Benchmarks** says "Semrush doesn't provide AI visibility data." The **Links** page appears under **Analytics** only while a vendor connection can answer. If you connect both Ahrefs and Semrush, these panels show Ahrefs.

## Units and limits

Semrush sells a balance of API units, not a monthly allowance. Weelkit reads your balance the first time it checks each month and treats it as that month's allowance:

* **Weelkit uses at most a quarter.** Each calendar month, Weelkit spends at most 25% of that allowance, scheduled pulls and research together. The card shows **Weelkit used X of Y units this month**, where Y is that quarter.
* **Research has its own cap.** Keyword research you run, from the editor or by asking the AI, can use at most 10% of that allowance in a month.
* **Scheduled pulls pause at 80%.** When your Semrush balance shows 80% of that allowance spent, counting everything charged to it, Weelkit stops its scheduled pulls until next month.
* **Nothing is sent over a cap.** A request that would cross a cap isn't made. The panel says so, and the caps reset each month.
* **Opening a page never spends units.** Pages show data Weelkit already pulled. Weelkit pulls on a schedule, weekly for most data, and only while someone has opened a page that shows this data in the last 14 days. If nobody looks, nothing is spent.
* **Nothing is retried.** Weelkit sends each paid request once. If Semrush doesn't answer in time, units may have been spent, and Weelkit doesn't send it again.
* **You control the keys.** The v4 key is read-only and expires on the date you chose. Delete it in Semrush to cut off access at once.

Weelkit keeps what it pulled for a short time so pages load quickly and repeated views spend nothing: up to 28 days, including the keywords you researched. It deletes expired data daily. Your keys are stored encrypted, and Weelkit shows only the last four characters of the key.

## Replace the keys or disconnect

* **Replace the keys.** If Semrush stops accepting a key, for example when the v4 key expires, choose **Paste a new key** on the card, paste both keys and choose **Connect**. The connection stays, and Weelkit deletes the data pulled with the old key.
* **Disconnect.** On the card, open the **⋯** menu, choose **Disconnect**, then choose **Disconnect** to confirm. **Keep connection** cancels. Weelkit deletes the stored keys and everything it pulled from Semrush, and stops pulling. The panels disappear from your pages.
* **Delete the v4 key in Semrush** if you no longer want it to exist. Disconnecting in Weelkit doesn't delete it there.

See the [Privacy policy](https://weelkit.com/privacy) for how Weelkit handles this data.

## Troubleshooting

| What you see | What it means and what to do |
| - | - |
| "Semrush API key (v4) is required" or "Semrush v3 key is required" | A key field is empty. Paste both keys and choose **Connect**. |
| "Could not connect to semrush: Semrush no longer accepts this key. Paste a new one." | Semrush rejected the key. Check that you copied all of it and that it hasn't expired. |
| "A connected or pending semrush connection already exists. Delete or disconnect it before creating another one." | Your organization already has a Semrush connection. Use **Paste a new key** on it, or disconnect it first. |
| "Your Semrush plan doesn't include API access" | Your account can't use the API. The connection stays, and Weelkit checks again daily. |
| "Semrush has no API units left. Buy units in Semrush to resume scheduled data." | Your balance is empty. Buy units in Semrush. |
| "Checking your Semrush plan…" | Weelkit is reading your balance for the first time. Look again in a moment. |
| **Reconnect required**, with "Semrush no longer accepts this key. Paste a new one." | A key was deleted, changed or expired. Choose **Paste a new key**. Weelkit checks the v3 key when you connect, so a v4 key problem can first show here, after a pull. Weelkit has already deleted the data pulled with the old keys. On a metrics page the same sentence comes with a **Settings → Integrations** link, if you can manage integrations. |
| "Semrush domain and URL reports need its v3 API key. Paste it with the v4 key." | The v3 key is missing. Choose **Paste a new key** and paste both keys. |
| "This connection has used N of its M-unit monthly budget. Paid calls stop until next month." | Weelkit reached its 25% budget. Pages keep showing what was already pulled, and pulls resume next month. |
| "…the research cap is N units…Nothing was sent." | Keyword research reached its 10% cap for the month. |
| "…the 80% stop line…scheduled pulls are paused. Nothing was sent." | Your Semrush balance is at 80% of the month's allowance. Scheduled pulls resume next month. |
| "Data arrives with the next sync." | Weelkit hasn't pulled this data yet. Open a page that shows it, then check back later. |
| "Weelkit has not found your site's domain yet. Publish an article or connect Search Console, then try again." | Weelkit doesn't know your site yet. |
| "This article has no public URL yet. Publish it, then try again." | Links and rankings need the article's public address. |
| "The vendor didn't answer in time. Units may have been spent, and the request was not retried." | Semrush was slow. Check the card's unit count, and try again later. |
| "Semrush is rate limiting requests. Nothing was retried." or "Semrush is temporarily unavailable. Nothing was retried." | Wait a while and try again. |
| "This vendor data could not be loaded." or "Usage unavailable" | The page couldn't read the data. Reload the page. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.