---
name: majestic-api
description: Query the GroupBuySEO Majestic API gateway (wire-compatible with the official Majestic API) for Citation Flow, Trust Flow, backlinks, referring domains, anchors, topics and neighbourhood data. Use when the user asks for Majestic metrics, CF/TF, backlink profiles, or wants to script against api.majestic.com without paying Majestic directly.
metadata:
  vendor: GroupBuySEO
  homepage: https://my.groupbuyseo.org/dashboard/api/products
  api_base_url: https://majestic-api.groupbuyseo.org/api/json
---

# Majestic API (GroupBuySEO gateway)

Wire-compatible drop-in for the **official Majestic API** — same `cmd` and
params, only the host changes. Every call is:

```
GET/POST https://majestic-api.groupbuyseo.org/api/json?app_api_key=$KEY&cmd=<Command>&…
```

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

This is the **JSON API product**, not the website proxy (`maj.groupbuyseo.org`).

## Use the script, not raw curl

Majestic returns a nested `{ Code, DataTables }` envelope and signals failure
as **HTTP 200** with `Code` ≠ `OK`. `scripts/majestic.mjs` checks `Code`,
retries `429`/`502`/`503`, and prints compact tables so a fat report does not
flood context.

```bash
# Discover commands without loading a reference file
node scripts/majestic.mjs list
node scripts/majestic.mjs tables GetBackLinkData

# Query. --table is the default; --json only if you must post-process.
node scripts/majestic.mjs get GetIndexItemInfo --item example.com --datasource fresh
node scripts/majestic.mjs get GetRefDomains --item example.com --count 20 --datasource fresh --table
node scripts/majestic.mjs get GetBackLinkData --item example.com --count 10 --datasource fresh

# Cost preview (analysis + retrieval) before a big pull
node scripts/majestic.mjs cost GetBackLinkData --count 100
```

Add `--csv` for spreadsheet output, `--dry-run` to print the URL only.

## The five rules that cause most failures

1. **HTTP 200 is not success.** Always read `Code`. Anything other than `OK`
   (and `QueuedForProcessing` for async downloads) is an error.
2. **Default index is `historic`.** Pass `--datasource fresh` for the Fresh
   Index. `GetRelatedSites` **requires** `fresh`.
3. **Do not prefix domains with `http://`** unless you want homepage URL
   metrics, not the root domain.
4. **List table names differ per `cmd`.** `GetTopPages` is `Matches`, not
   `Results`. `GetBackLinkData` is `BackLinks`. Check with
   `node scripts/majestic.mjs tables <cmd>`.
5. **Always set `Count`.** Web adapters cap `Count` at **1000**. Official
   `GetBackLinkData` can return 50,000 rows and bills **1 retrieval unit per
   row** on top of analysis.

## Cost (collapsed into `FullCost`)

| `cmd` | Formula |
|---|---|
| `GetIndexItemInfo` | 1 × items (batch up to 100) |
| `GetBackLinkData`, `GetTopPages` | 5000 + rows |
| `GetHostedDomains` | 5000 + rows |
| `GetRefDomains`, `GetAnchorText`, `GetTopics` | 1000 + rows |
| `GetNewLostBackLinks` | 500 × days + rows (default 1 day) |
| `GetDownloadsList` | 0 |

Non-OK bodies are **not** charged. Batch `GetIndexItemInfo` — never loop one URL.

## Do not call

`SubmitURLsToCrawl`, `AddToBucket`, `AddFileToRecrawlList`, `AnalyseIndexItem`
mutate the **shared** upstream account. Never enable them from an agent.

`GetSubscriptionInfo` reports the **pooled upstream** plan, not the customer's
GBS credit ledger. HTTP `503` means no official Majestic key is pooled — the
nine web-primary cmds still work.

## Errors

`Code=Error` + invalid key → bad `app_api_key` · missing `cmd` → gateway `400`
· `NotEnoughUnits` → do not retry · `RealTimePrefixQueryNotPossible` → call
`GetPrefixQueryEstimate` first · HTTP `429` back off (max 3 in flight) ·
HTTP `503` official path down.

## Reference files

Load only the one you need:

| File | Read it when |
|---|---|
| `reference/commands.md` | You need the full `cmd` list, tables, required params and costs |
| `reference/params.md` | You need shared params, item types, errors, or the forbidden list |

Official upstream docs: <https://developer-support.majestic.com/api/>.
