To automate edits with Wikidata bots, pick the lightest tool that fits the job — QuickStatements for batched TSV edits, Pywikibot for anything needing real logic — test on a few items, then scale while respecting maxlag and an approved task scope. The single most important habit is to make every run reversible: log each QID and change so a mistake can be undone in bulk rather than chased by hand. This guide takes you from choosing a tool to a safe production run.

Which tool should I use?

Task	Tool	Why
Add statements from a spreadsheet	QuickStatements	No code, TSV input, has a batch history
Reconcile then write back	OpenRefine + Wikidata	Match first, export edits
Conditional or computed edits	Pywikibot	Full Python, reads the API
Recurring scheduled maintenance	Pywikibot bot account	Flagged, documented, auditable

Start at the top of the table and only move down when the task genuinely needs it.

Step 1 — Should I register a bot account?

For small batches you may run QuickStatements under your own account. For high-volume or recurring automated edits, register a dedicated account named like ElaraReedBot, then file a request at Wikidata:Requests for permissions/Bot describing the task, source data and edit rate. The bot flag hides your edits from default recent-changes and signals the community has reviewed your task.

Step 2 — How do I prepare reversible input?

Whatever the tool, build the input so you can reverse it. A QuickStatements batch is just lines:

Q42|P800|Q5410773|S248|Q36578
Q42|Len|"Douglas Adams"
CREATE
LAST|Len|"new heritage item"
LAST|P31|Q5

Before running, export the current state of the QIDs you will touch. Keep that export — it is your rollback map.

Step 3 — How do I run Pywikibot safely?

For coded edits, Pywikibot handles login, throttling and maxlag for you. A minimal, safe pattern:

import pywikibot

site = pywikibot.Site("wikidata", "wikidata")
repo = site.data_repository()

def add_collection(qid, collection_qid):
    item = pywikibot.ItemPage(repo, qid)
    item.get()
    if "P195" in item.claims:      # already set — skip, stay idempotent
        return
    claim = pywikibot.Claim(repo, "P195")
    claim.setTarget(pywikibot.ItemPage(repo, collection_qid))
    item.addClaim(claim, summary="Add collection (P195) via approved task")

# run on a 5-item test list first, log every qid you change

Configure throttling and maxlag in user-config.py. The if "P195" in item.claims guard makes the run idempotent — re-running it does not create duplicates.

What pitfalls actually cause blocks?

• Ignoring maxlag — set maxlag=5 so the bot pauses when replicas lag.
• Editing too fast — keep flagged bots within community rate norms; throttle.
• Scope creep — only do the approved task; a side-edit invites a block.
• No references — add S248 / reference URLs as you go, not later.
• No dry run — always test on 5 items and read the diffs before scaling.

How do I monitor and roll back?

QuickStatements gives every batch a history page with a one-click revert. For Pywikibot, write your own audit log (QID, property, old value, new value, timestamp) so a bad run can be reverted precisely. Watch your bot's contributions live during the first minutes of a large run and be ready to stop it.

When is a bot the wrong answer?

If the task is a single import of a few hundred rows with no conditional logic, QuickStatements alone is enough and a coded bot is wasted effort. Reserve Pywikibot and a flagged account for recurring maintenance, computed values, or jobs too large or branchy for a flat TSV.

Key Takeaways

• Use the lightest tool: QuickStatements for batches, Pywikibot for logic.
• Register a flagged bot account for high-volume or recurring tasks.
• Make every run reversible — log QIDs and prior values before editing.
• Respect maxlag=5 and community rate limits to avoid blocks.
• Write idempotent Pywikibot code so re-runs do not duplicate statements.
• Add references as you edit, never as a deferred pass.
• Always dry-run on 5 items and read the diffs before scaling up.

Frequently Asked Questions

Do I need a separate bot account to automate edits?

For high-volume automated edits, yes. You create a dedicated bot account, request the bot flag via Wikidata:Requests for permissions/Bot, and run a documented task. For small batches QuickStatements under your own account is acceptable without a flag.

What is the difference between QuickStatements and a Pywikibot script?

QuickStatements applies edits from a TSV through a web tool with no coding. Pywikibot is a Python framework that gives full programmatic control for complex logic, conditional edits and API access. Use QuickStatements for straightforward batches, Pywikibot when you need real code.

How do I avoid getting my bot blocked?

Respect the maxlag parameter, throttle your edit rate, test on a handful of items first, make edits reversible, and follow the approved task scope. Unapproved high-speed or out-of-scope edits are the fast route to a block.

Can I reverse a bad bot run?

Yes, if you prepared for it. Log every QID and the exact change, and edits can be reverted in bulk. QuickStatements batches have a history page; Pywikibot runs should write their own audit log so you can roll back precisely.

What is maxlag and why does it matter?

Maxlag tells the API to pause your edits when Wikidata's database replicas fall behind. Setting maxlag=5 means your bot backs off when lag exceeds 5 seconds, protecting site performance. Bots that ignore it are considered abusive.

Is a bot the right tool for a one-off import of 200 rows?

Usually QuickStatements alone is enough; a full Pywikibot bot is overkill. Reserve coded bots for recurring tasks, conditional logic or jobs too large or complex for the QuickStatements TSV format.

Related reading

• Batch import with QuickStatements
• Managing Wikidata data quality
• Recording references on Wikidata
• Calling APIs with Python
• Make OpenRefine cleaning reproducible