Skip to content
DarkSEO
DarkSEOGet $100 free

Setup guide

Find my backlink list and set up a monthly watch

Ten minutes of setup gives you a dated record of who links to you. When trouble comes, you diff two files instead of guessing.

Setup in six steps

01

Sign in with Google

Use the account page to sign in. New accounts hold $100 of credit, no card required.

02

Create an API key

The key starts with sk_. Keep it out of public repositories; treat it like a password.

03

Try the free lookup

action=overview&q=yourdomain.com costs nothing and confirms your key and domain spelling.

04

Pull the real lists

Run refdomains, anchors and toppages, 1,000 rows per call, 2 credits each.

05

Save with the date

Name files like refdomains-2026-10.json. Never overwrite last month's file.

06

Diff

Compare rows against the previous month. The new domains are what you read.

One call, with every field explained

Replace the domain and key. The same pattern works for all actions.

bash
curl "https://darkseo.net/api.php?action=refdomains&q=yourdomain.com&per=1000&page=1&key=sk_live_..." \
  -o refdomains-2026-10.json

Reference of parameters

ParameterMeaningNotes
actionWhich report to runrefdomains, backlinks, anchors, toppages and others
qThe domain you are investigatingBare domain, no scheme
keyYour API keyOr send Authorization: Bearer sk_...
pagePage numberDeep pagination is capped at 50,000 rows
perRows per pageFrom 10 to 5000; billing is once per call
sort, orderSort column and asc or descUseful to see the newest or biggest first

Naming, storing and comparing the files

A find my backlink list only helps if the files can be compared without help. A clear naming rule and one folder per month do most of the work. Spend ten minutes on the rule now, because an hour of sorting later is worse. Then never rename them.

Use the same pattern for every domain and every call, so a plain sort lines the files up by month. Mixed patterns break sorting, and a broken sort is how last month's file ends up overwritten.

File names that sort

Put the year and month first, then the domain, then the call name, such as 2026-10 followed by the domain and refdomains. Zero-padded months sort correctly, and a name in that order reads like a log.

Avoid spaces and accented characters in names. Scripts handle them badly, and a failed copy can look like a successful one.

One folder per month

Create a folder for each month and copy the three files for each domain into it. A folder per month keeps last month untouched, so a diff becomes a comparison between two folders.

Mark the folder read-only once the month is closed, if your system allows it. A saved file that cannot be edited is a much stronger record.

A short changelog

Keep a plain text log in the root folder. Write one line per pull with the date, the domains and the calls made. A changelog lets you explain a gap in the series years later, when nobody remembers the reason.

Add the credit cost from each response to the same line, so the log doubles as the bill.

Record every change to the domain list in the same log, with the reason. A domain added in one month explains a jump in that month, and it saves a long search later. Keep the lines plain, so a script can read the log if you ever want an automatic summary.

Mistakes and fixes

MistakeSymptomFix
Missing or wrong keyHTTP 401Check the key and the header spelling
Balance emptyHTTP 402Top up with USDT (TRC-20) from the account page
Reading ok ignoredEmpty file treated as successTest the ok flag in your script before saving
Overwriting last monthNo diff possiblePut the month in the file name
Expecting live dataNew link missingIndex refreshes about monthly; compare monthly, not daily

Automating it

A cron entry on the first of the month is enough. Write the three curl calls into one shell script, add the month to each file name, and let it email you only when the new-domain count passes your threshold.

Authenticated responses include _credits with the cost and remaining balance, so the script can warn you before the balance runs low. Test it once by hand. Then forget it until the email arrives.

For a team, pair the monthly pull with the example thresholds, so everyone reads the same rule.

Keep the script boring. Plain curl, one loop over your domains, one folder per month. Boring scripts survive staff changes.

Handling a failed run

A failed run should leave last month's files alone and write one line to the changelog. The usual trap is a partial download: a file that exists but holds an error body looks like data at first glance. Check the size and the ok flag before it moves. Nothing reaches the monthly folder unchecked.

If the run fails twice in a row, check the key and the domain spelling first. The free overview call tests both at no cost, so a failure there tells you whether the problem is the setup or the paid call.

Keeping the watch inside a budget

A watch is cheap once you know the arithmetic. Each paid call is billed once, whatever the number of rows, up to 1,000 rows per call. Multiply the calls you make by their credit cost, then by $0.0001 per credit, and you have the monthly bill. Do that first.

Here is the arithmetic for three calls on one domain. refdomains, anchors and toppages cost 2 credits each, so six credits, which comes to $0.0006 for the month.

Estimating the monthly bill

Add one bulk_dr call for the newcomers at 1 credit, and the total rises by one more credit. The table on the thresholds page works out the ten-site case, so you can see how the figures grow with the list.

Keep the estimate in the same log as the pulls. A bill that drifts upward is easier to explain when the estimate was written down first.

Stopping before the balance runs out

Authenticated responses include the cost and the remaining balance. Read them in the script, compare the balance with next month's estimate, and warn yourself when the margin is thin. A response with ok set to false should stop the run before any file is saved.

An HTTP 402 means the balance has run out. Top up with USDT (TRC-20) from the account page, then rerun that month's calls rather than skipping the month.

A monthly loop

A sketch, not a product. It saves three reports per domain with the month in the name. Adjust the list and the key.

bash
#!/bin/bash
M=$(date +%Y-%m)
for D in yourdomain.com second-site.org; do
  for A in refdomains anchors toppages; do
    curl -s "https://darkseo.net/api.php?action=$A&q=$D&per=1000&key=$DARKSEO_KEY" -o "$D-$A-$M.json"
  done
done

What to do with the files

Open last month's and this month's refdomains files side by side and list the domains that are only in the new one. That list is your reading for the month.

Send the list through bulk_dr for a quick quality score, check the anchors file for any phrase that grew, and read the top pages for URLs you do not recognise. If everything looks ordinary, write one line in your log and close the tab.

If something looks wrong, open the runbook and the disavow decision table. The monthly pull costs a fraction of a cent, so the real cost is your attention.

Writing the monthly note

Write a short note at the end of each month. Name the domains, the new-domain count, the largest anchor share and the decision. Four lines are enough. A note written the same day is worth more than a long one written later.

Keep the note next to the files, not inside them. A future reader should find the decision in one place, with the numbers that justified it. That reader may be you, a year on, with no memory of the month.

Questions about the monthly watch

Do I need a paid plan to run this?

There is no subscription and no monthly minimum, because the service is prepaid credit. New accounts receive $100 of free credit with no card needed. The free lookups cost nothing, so you can test the setup before you pull any paid list.

Why not run the script every day?

The index refreshes roughly once a month, so a daily job would download the same picture again and again. Daily runs also spend credits for no new information. Monthly is the honest rhythm for this data.

What should I do if the new file is much bigger?

Check the row count against your baseline, then open the newcomers in the diff. A larger file can come from a real spike or from a changed row limit. Rule out the second cause first, because it is the cheaper check.

Can one script watch several domains?

Yes. The monthly loop above handles a list of domains, and each one gets its own files. Keep the list short enough that every domain gets a real read each month, because a watch nobody reads is only a storage cost.

Two limits to remember

The index refreshes about once a month, so a daily cron job would only download the same picture. And a link list is not a verdict: pair every flag with the Search Console links report before you act.