---
name: semrush-api
description: Query the GroupBuySEO Semrush API gateway for domain analytics, organic/paid keywords, competitor research, backlinks and Traffic Analytics (Trends beta). Use when the user asks for Semrush metrics, domain overviews across regional databases, keyword difficulty/CPC, or wants to script against api.semrush.com without paying Semrush directly.
metadata:
  vendor: GroupBuySEO
  homepage: https://my.groupbuyseo.org/dashboard/api/products
  api_base_url: https://api-semrush.groupbuyseo.org/
---

# Semrush API (GroupBuySEO gateway)

Drop-in for the official Semrush API — same params, only the host changes.
Base URL: `https://api-semrush.groupbuyseo.org/`.

Auth: the `key` **query parameter** (not a header). Read it from
`$SEMRUSH_API_KEY`; never hardcode it. Key lives at
<https://my.groupbuyseo.org/dashboard/api/keys>.

## Use the script, not raw curl

Semrush returns **semicolon-delimited CSV**, and reports errors as `200` bodies.
`scripts/semrush.mjs` parses the CSV, turns error bodies into real failures,
retries transient errors, and prints compact output.

```bash
# Discover report types and their columns without loading a reference file
node scripts/semrush.mjs list
node scripts/semrush.mjs columns domain_organic

# Query
node scripts/semrush.mjs get domain_rank --domain example.com --database us
node scripts/semrush.mjs get domain_organic --domain example.com \
  --database us --limit 20 --columns Ph,Po,Nq,Cp,Tr --sort tr_desc --table

# Traffic Analytics (Trends beta) — path-based, not type=
node scripts/semrush.mjs trends summary --targets example.com --columns target,visits,users
```

Add `--csv` for raw output, `--json` to post-process, `--dry-run` for the URL.

## The four rules that cause most failures

1. **Responses are CSV with `;` delimiters**, not JSON.
2. **Errors arrive as HTTP `200`** with a body like `ERROR 50 :: NOTHING FOUND`.
   Never treat a `200` as success without inspecting the body.
3. **Never send `database=all`** on `domain_rank`/`domain_ranks` — it returns
   `ERROR 50`. For all regions **omit `database`** (~140 rows); for one region
   pass a single code (`database=us`).
4. **Always pass `export_columns`** — it cuts both payload and unit cost.

## Errors

`ERROR 50` nothing found, or an invalid combo like `database=all` — not
necessarily auth · `ERROR 401` bad key · `ERROR 120` limit exceeded ·
`ERROR 130` invalid parameter · `ERROR 132` out of units, don't retry ·
`ERROR 140` bad database code · HTTP `429` back off.

## Reference files

Load only the one you need:

| File | Read it when |
|---|---|
| `reference/reports.md` | You need the full report-type list with required params and costs |
| `reference/columns.md` | You need column codes (`Ph`, `Nq`, `Cp`, …) per report |
| `reference/filters.md` | You need `display_filter` syntax or database codes |

Official upstream docs: <https://developer.semrush.com/api/>.
