A monthly runbook for a reproducible backlink report
Run it once a month, store a dated snapshot, render from the file. The rest of the page is the detail behind those three habits.
CranSEO research team ·
The runbook
Pull
A scheduled script calls the API and writes a dated file, for example links_2026-10.rds. GitHub Actions or cronR both work.
Check
Fail the job on HTTP 401 or HTTP 402, and log the credits field. A silent partial pull is worse than a loud stop.
Freeze
Never overwrite last month's file. With renv and targets, old reports still rerun against old data.
Render
Quarto reads the stored file, not the API. Rendering is then free and repeatable.
Annotate
Add the dated update lines below to charts, so a bump is read against the right context.
Why monthly and not daily
Our graph refreshes roughly once a month. A daily job returns the same numbers.
Running it more often does not make a report more current, it only makes it more expensive to explain. A reader who sees 30 identical points will assume the pipeline is broken.
Choose the day deliberately. Pick one day each month, ideally a week after the previous refresh settles, and write the date into the file name so the schedule itself is documented.
What to store besides the numbers
Metadata is half the report. Store it.
Write the pull date, the action name, the parameters (per, sort, order) and the credits field of the response into a small sidecar file next to every snapshot. Six months later, when a colleague asks why October looks different from September, that file answers in ten seconds instead of an afternoon.
Add the git commit of the script and the package versions from renv. A report that cannot say which code and which index state produced a chart is a screenshot, not an analysis, no matter how tidy the tibble looks.
Dated Google events worth drawing on your charts
Penguin 4.0
Penguin became part of the core algorithm and worked in near real time.
Helpful content update
Started rolling out on 25 August 2022.
March 2024 core update
Announced alongside spam policy changes in March 2024.
March 2025 core update
A further broad core update, rolled out over about two weeks.
A minimal targets layout
Keep the plan small. Three targets are enough.
One target pulls from the API and writes the dated file, one reads the file and builds the tibble, one renders the Quarto document. Because only the first target touches the network, you can rerun the others offline as often as you like and the chart never changes by accident.
Pin package versions with renv, record the session info in the footer of the report, and keep the threshold table from the bulk scoring page in the repository next to the code. For the money side, the budget page tells you what a month should cost.
Errors come next. Read the code first. HTTP 401 means the key is wrong or missing, HTTP 402 means credit ran out, and anything else is worth logging in full. The teardown covers those stages, and the join example is a good first job to schedule.
Run sheet for the first of the month
- Key present in the CI secrets store, not in the repository
- Balance above the expected spend (see the budget page)
- Snapshot file written with the month in the name
- Previous month's file untouched
- Report rendered from files, with the update lines drawn