Skip to content
SEO Tools AI
SEO Tools AISign up

Recipe

Sync link scores from a sheet or n8n

Most tool directories live in a spreadsheet, an Airtable base or a small database. This recipe turns a tool backlink check into a column fill: one request per 2,000 rows.

SEO Tools AI research team ·

Paper cut-out workers building a bridge connecting a filing cabinet to a road

The recipe in five moves

01

Export the domains

Take the website column of your listings, strip the protocol and paths, and remove duplicates. Duplicates cost nothing extra but make the mapping step messy.

02

Chunk into groups of 2,000

bulk_dr accepts up to 2,000 domains per call. A 5,000-row sheet therefore needs three calls.

03

Send, check ok

Call the API, read the JSON, and stop if ok is false. Log _credits so you see the balance after every run.

04

Write back with a date

Store the rating and today's date in two columns. Never overwrite a good value with an empty one.

05

Schedule once a month

Run it on the first of the month. The index moves about monthly, so more often gains nothing.

Choose what starts the job

The trigger decides how often the calls happen, so pick it before you build the mapping. Two starts cover nearly every directory.

A schedule on the first of the month is the simplest option. It matches the rhythm of the index, and nobody has to remember a button.

A schedule for the monthly refresh

Put a schedule trigger first, set it to the first day of each month, and let it read the whole listing table. Each run then makes one batch of bulk_dr calls, sized to the row count.

Keep the schedule even when the table is small. A monthly job that runs on a tiny sheet costs one credit, and it keeps the scores dated and current.

A trigger on each new row

Suppose listings arrive one at a time, every few days. A trigger that fires per new row is tempting, but every call is billed once, so one call per row costs more than one batch for the month.

If you want the score quickly, let the new-row flow write a blank dr and let the monthly run fill it. The row gets its number without a call for each arrival.

If listings arrive in bursts, group the new rows into one batch at the end of the week. That costs one call, and the sheet no longer changes only once a month.

A date that marks finished rows

Store dr_checked_on on every row you score. A run that starts with a filter on that date skips what is already done this month, and no separate queue is needed.

When a run stops halfway, the rows already stamped stay stamped. The next run picks up where the last one ended, which is the cheapest recovery there is.

Before you automate anything

Run the check by hand on five listings first. Use the free overview action for each, which needs no key, and compare what you see with what you expected.

This catches the common surprises early: a listing that points to a subdomain, a product that lives on a path of a larger site, a domain that redirected last spring. A rating belongs to a domain, not to a product.

Decide how your sheet marks those cases, for example with a note column that reads shares domain. Readers forgive a footnote far more readily than a score that looks wrong.

When the five look sane, move on to the batch. Your field reference lists the columns, and the cost example shows what a run costs.

A small Python version

Needs the requests package. It is a sketch for the shape of the job: print one real response first, then map the fields you need into your own columns.

python
import csv, requests

KEY = "sk_live_..."
BASE = "https://seotoolsai.org/api.php"

rows = list(csv.DictReader(open("listings.csv")))
domains = sorted({r["domain"] for r in rows})

for i in range(0, len(domains), 2000):
    chunk = domains[i:i + 2000]
    r = requests.post(BASE, params={"action": "bulk_dr", "key": KEY},
                      data={"domains": ",".join(chunk)}, timeout=60)
    if r.status_code in (401, 402):
        raise SystemExit(f"stop: HTTP {r.status_code}")
    data = r.json()
    if not data.get("ok"):
        raise SystemExit("api said not ok")
    print(data["_credits"])   # cost and remaining balance
    open(f"raw_{i}.json", "w").write(r.text)
Paper gears and conveyor belts sorting blocks into groups

Doing it in Google Sheets or n8n

Sheets can call a URL from Apps Script with UrlFetchApp, and n8n has an HTTP Request node. Both do the same thing as the script above.

In n8n, put a schedule trigger first, then a node that reads your sheet or table, then an item-splitting step that builds groups of 2,000, then the HTTP Request. Add a final node that writes the rating and date back.

Keep the key in the platform's credential store, not in the workflow text. Workflows get shared, copied and pasted into forums, and a key pasted with them is spent money.

No-code or a script: which shape fits your team

Both routes make the same call. The difference is who has to maintain the flow a year from now, and how easy it is to explain it to that person.

Choose the shape you can still read after a break of several months. A clever flow nobody understands is worse than a plain script everyone can follow.

A flow you can explain to the next editor

A short n8n flow with four labelled nodes is easy to hand over: trigger, read, batch, write back. Name each node after what it does, not after the default label.

Avoid stacking many branches for edge cases. Each branch is one more place where a domain can get the wrong score.

When a script earns its place

A script makes sense when the input is a folder of CSV files, or when the job needs logic that a flow handles awkwardly. The sketch above fits that case.

Put the script in version control and keep the key in an environment variable. A script that reads its key from a file in the same folder is a leak waiting for a shared drive.

Tutorials that skip the hard part

Many videos show a flow that works on the first try with three rows. Real listings have blanks, duplicates and odd domains, and those are where the flow needs attention.

Build the flow on your own five test rows first. If a tutorial cannot survive those, the tutorial was never the whole job.

When you hand the flow to someone else, include the five test rows as a sample. The next person can see what a good run looks like before touching live data.

What the errors mean

Behaviour of the API and what a sync job should do.
SignalMeaningWhat the job does
HTTP 401Missing or bad keyStop, alert a human
HTTP 402Credit has run outStop, keep old scores, top up
ok is falseThe call did not succeedLog the body, retry next run
Empty result for a domainNot in the indexLeave the cell blank
Paper gardener straightening a crooked plant stem in a garden

Keep the sheet clean between runs

A sync job is only as good as the sheet it writes to. A few habits stop the slow damage that builds up between one run and the next.

Most problems start with an innocent edit: a column inserted above the score, or a copied row that quietly changes a domain.

Keep raw responses in their own tab

Store each raw response in its own tab, or as JSON Lines with one response per line. That copy lets you rebuild the visible columns without a second paid call.

A raw tab also answers the question an editor asks six months later: what did the API return on that date.

Name each raw tab with its batch date, so the copies sort in order when you scroll back through them.

Lock the header row

Freeze the header row and never insert a column above the score. A mapping that points at column F will read the wrong data after an insert, and it will do so without any error.

Name the columns in the mapping, not by position. A name survives a reordering, and a position does not.

Count the rows before and after

Write the row count into the log before the run and again after it. The two numbers should differ only by the rows you intended to add, and a gap tells you something went wrong.

Sort the sheet by the score column once a month and look at the top and bottom rows. Odd values there usually point to a domain that was mapped to the wrong listing.

Test on a copy first

Duplicate the sheet and run the flow against the copy before you touch the real one. A copy costs nothing to make.

A bad mapping written over live scores is hard to undo, because the old values are gone. Keep the copy until the first honest run matches what you expected.

Delete the copy only after the second scheduled run has matched it. Two clean runs in a row are a better signal than one.

Before the first live run

  • The key sits in the platform's credential store or an environment variable, not in the workflow text.
  • One free overview call was checked by hand against a listing you know.
  • The run was tested on a copy of the sheet, and the copy matched what you expected.
  • The job writes the date next to every score it touches.
  • Status 401 and 402 stop the job and send a message to a person.

Sync questions

How do I avoid paying twice if the job crashes halfway?

Write the date next to each score as you go, and have the next run skip rows already stamped this month. Chunks of 2,000 mean a crash costs at most one credit, so the risk is tiny, but the habit keeps the sheet tidy.

Can a non-programmer set this up?

Mostly yes. An HTTP Request node in n8n or Make needs only a URL, a key and a list. The fiddly part is turning the response into columns, so do one test call and look at the JSON before you build the mapping.