Reference
Backlinks API reference: actions, costs and errors
One page for the facts a monitor needs: what each action costs, how pagination works, and what the API does when something goes wrong.
Actions by credit cost
| Cost | Actions | Notes |
|---|---|---|
| Free, no key | domain, overview, stats, suggest | Good for dashboards and the DR checker |
| 1 credit | bulk_dr, compare, top, dr_distribution, tld_breakdown | bulk_dr takes up to 2,000 domains (GET domains= or POST body); compare up to 20 |
| 2 credits | refdomains, backlinks, anchors, toppages, anchor_cloud, intersect | intersect takes 2 to 10 domains |
| 3 credits | search, keyword | Full-text over anchors, titles and URLs; keyword finds who is linked with an exact anchor |
Authentication and status codes
Pass the key as key= or as a bearer header. Check the HTTP code before you parse the body.
# header style
curl -s -H "Authorization: Bearer sk_live_..." \
"https://seouptr.com/api.php?action=anchors&q=yourdomain.com&per=100"
# a cron-safe wrapper
code=$(curl -s -o out.json -w '%{http_code}' "$URL")
case "$code" in
200) jq '._credits' out.json ;; # cost and remaining balance
401) echo 'bad or missing key' ;;
402) echo 'out of credit: top up' ;;
*) echo "unexpected $code" ;;
esacParameters and errors
| Item | Value | Meaning |
|---|---|---|
q | a domain | The target of the lookup |
page, per | per from 10 to 5000 | Pagination; rows per call are capped at 1,000, deep pagination at 50,000 |
sort, order | order=asc or desc | Sorting of returned rows |
ok | in every response | Whether the call succeeded |
_credits | authenticated responses only | Cost of the call and remaining balance |
| HTTP 401 | missing or bad key | Check the key or header |
| HTTP 402 | credit used up | Top up with USDT (TRC-20) |
Reading the numbers
The data is our own link graph: 181,132,097 domains, 2,774,625,913 domain-to-domain links and about 798.5 billion backlinks. It refreshes roughly once a month. Anything newer than that will not be in it, which is why a seo backlinks api is best polled weekly.
DR is round(100 · log(ref_domains+1) / log(2·10^7)). It is a log. Because of that, 100 referring domains score 27, 1,000 score 41 and 10,000 score 55, so doubling your link count adds only a few points. Use DR for ranking sites against each other and the raw count for alerts, as the severity table does.
Pricing is prepaid. There is no subscription and no minimum. The sign-up credit is $100, which is 1,000,000 credits. Compare that with Ahrefs API units, sold inside plans from $129/month for 200,000 units, with at least 50 units per request.
Cost planning is simple multiplication. A weekly refdomains call for one site is 2 credits times 4, or 8 credits a month, which is $0.0008. Ten sites cost ten times that. The lost-link recipe and the competitor job both use only actions from the table above.
domain, overview, stats and suggest need no key and cost nothing. Use them to sanity-check a domain name, an exact spelling or a rough size before you spend a single credit on a paid action.
Before you put a call in cron
- The action's cost is known and multiplied by runs per month.
- Exit code and HTTP status are both checked.
- A 402 sends an alert to a human.
- Responses are saved sorted, so diffs stay clean.
- The cadence matches the monthly refresh.
Notes on pagination
Order matters. Use per=1000 for snapshots and keep the same sort and order every week. If the order changes between runs, a diff shows noise. That is a classic cause of false alarms.
Bigger sites? For a site with more than 1,000 referring domains, page through with page=1, page=2 and so on. Each page is a separate billed call. Deep pagination is capped at 50,000 rows, which covers nearly every ordinary site.
