Bulk Update

1---
2name: bulk-update
3description: Update properties or content across many pages in a Notion database with dry-run and error recovery
4argument-hint: "[database name] [what to change]"
5---
6 
7# Bulk Update
8 
9Update properties or content across many pages in a database safely.
10 
11## Pagination (Critical)
12 
13Notion returns max 100 results per query. You MUST paginate to process all pages:
14 
15```
16# First query
17databases(action="query", database_id="<id>", filter={...}, page_size=100)
18# Response includes: has_more=true, next_cursor="abc123"
19 
20# Continue until has_more=false
21databases(action="query", database_id="<id>", filter={...}, page_size=100, start_cursor="abc123")
22```
23 
24Never assume a single query returns all results. Always check `has_more`.
25 
26## Dry-Run Mode
27 
28Before making any changes, ALWAYS show the user what will change:
29 
301. Query the database with the filter
312. For each matching page, show:
32   - Page title (current value)
33   - What will change (old value -> new value)
34   - Total count of affected pages
353. Ask for explicit confirmation before proceeding
36 
37Example dry-run output:
38```
39Found 23 pages matching filter. Changes:
40 
411. "Project Alpha" -- Status: "Active" -> "Archived"
422. "Project Beta" -- Status: "Active" -> "Archived"
43...
44(21 more)
45 
46Proceed with update? (yes/no)
47```
48 
49## Update Execution
50 
51After user confirms:
52 
531. **Track progress** -- maintain counters:
54   - `succeeded`: pages updated successfully
55   - `failed`: pages that errored (with page ID and error message)
56   - `skipped`: pages already in target state
57 
582. **Update each page**:
59   ```
60   pages(action="update", page_id="<id>", properties={
61     "Status": { "select": { "name": "Archived" } }
62   })
63   ```
64 
653. **Rate limit awareness**:
66   - Notion rate limit: 3 requests/second average
67   - For large batches (50+ pages), warn user it may take time
68   - If you get 429 errors, pause and retry
69 
704. **Error recovery**:
71   - Never stop on first error -- continue processing remaining pages
72   - Collect all failures with their page IDs
73   - After completion, report: "Updated 20/23 pages. 3 failed: [page IDs + error reasons]"
74   - Offer to retry failed pages
75 
76## Property Value Format
77 
78Remember the nested format (same as organize-database skill):
79```jsonc
80// Properties must use typed nested objects
81{ "Status": { "select": { "name": "Done" } } }
82{ "Tags": { "multi_select": [{ "name": "urgent" }, { "name": "review" }] } }
83{ "Priority": { "number": 1 } }
84{ "Reviewed": { "checkbox": true } }
85```
86 
87## Common Bulk Operations
88 
89- **Change status**: Filter by old status, update to new status
90- **Add/remove tags**: Read existing multi_select, merge/filter, write back
91- **Set dates**: Update date properties across filtered pages
92- **Archive**: Set `archived: true` on pages matching criteria
93- **Clear field**: Set property to empty value (e.g., `{ "rich_text": [] }`)
94 
95## When to Use
96 
97- Renaming a category/tag across all pages
98- Bulk-archiving completed or old items
99- Adding a new tag to all pages matching a filter
100- Resetting or populating a property across many pages
101- Mass status transitions (e.g., sprint closeout)
102