A Go script that deletes (archives) every item of a Notion database.
Notion has no bulk-delete endpoint: each page is archived individually via
PATCH /v1/pages/{id} with {"archived": true}. Pages are discovered by paginating
POST /v1/databases/{id}/query. Archiving is Notion's form of "deleting" — items can be
restored manually from the trash.
- Respects API limits — a global rate limiter (token bucket) at ~3 req/s shared by all workers.
- Backoff + Retry-After — handles
429/529by honoring theRetry-Afterheader, with exponential backoff and jitter; it also retries5xxand network errors. - Parallelism — a worker pool deletes in parallel while listing is still in progress (producer/consumer over channels). Total throughput is still capped by the rate limiter.
- Structured logs for the whole process (
log/slog). - Dry-run mode and interactive confirmation for safety.
- Minimal dependencies (standard library plus
golang.org/x/syncandgolang.org/x/time).
- Create an internal integration at https://www.notion.so/my-integrations and copy the token.
- Share the target database with the integration (
•••menu → Connections → your integration). - Get the Database ID (the 32 characters in the database URL).
export NOTION_TOKEN="secret_xxx"
export NOTION_DATABASE_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# 1. Preview — lists what would be deleted, without deleting anything:
go run . -dry-run
# 2. Delete for real (asks for a "yes" confirmation):
go run .
# No prompt (e.g. in automation):
go run . -yes
# Tune concurrency and rate:
go run . -workers 4 -rate 3| Flag | Default | Description |
|---|---|---|
-token |
$NOTION_TOKEN |
Notion integration token |
-database |
$NOTION_DATABASE_ID |
Database ID |
-workers |
3 |
Number of concurrent delete workers |
-rate |
3 |
Max requests per second (global) |
-dry-run |
false |
Only list, don't delete |
-yes |
false |
Skip the interactive confirmation |
A specialized copy in cmd/tarefas-ai/ that acts only on the
Tarefas AI Database and deletes only the items whose Event Id field is not empty.
- The database ID is built in (
2a2bca5d3ca880eeab9eddc4d56a7e5e), but can be overridden with-database/NOTION_DATABASE_ID. - The filter is applied server-side (
Event Idis rich_text →is_not_empty), so empty items are never fetched or deleted. - The property is configurable via the
-propertyflag (default"Event Id").
# Preview — lists only the items with Event Id filled in:
go run ./cmd/tarefas-ai -dry-run
# Delete for real (asks for confirmation):
go run ./cmd/tarefas-ai# generic tool
go build -o cleannotiondb .
./cleannotiondb -dry-run
# Tarefas AI variant
go build -o tarefas-ai ./cmd/tarefas-ai
./tarefas-ai -dry-run- Archiving does not delete permanently; items stay in the database's trash.
Ctrl-Cgracefully cancels in-flight requests.