Overview of the two bulk item import mutations - ingest_items and backfill_items - and how to choose between them
Only available in API versions
2026-07and later
The platform API exposes two mutations for importing items in bulk: ingest_items and backfill_items. Both follow the same asynchronous workflow - start a job, upload a CSV, poll for status - but they are designed for different scenarios.
Use ingest_items for recurring imports and imports that should behave like normal board activity. It runs with full platform side effects (automations fire, the Activity Log records every change) and supports upsert/skip logic via on_match for regular item imports.
Use backfill_items only for a planned, one-time initial load where you want to seed a board silently before users or automations start working on the board. It requires account admin permissions, skips automations, and does not write to the Activity Log.
Bulk import also supports create-only hierarchy imports on multi-level subitems boards. For MLS boards, the CSV uses level columns from name.l1 through name.l5 to represent parent-child hierarchy. See the Importing items in bulk guide for the file format.
Bulk import supports Board Relation columns as another supported column type, with additional per-cell and board relation limits. See the guide for the CSV value format.
Comparison
ingest_items (recommended) | backfill_items | |
|---|---|---|
| Use for | Integrations, recurring imports, any import that should behave like normal board activity | A single large initial setup import before users or automations start working on the board |
| Who can call it | Any user with boards:write | Account admin + boards:write |
| Maximum rows per job | 10,000 | 20,000 |
| Upsert / skip existing items | Yes, via on_match for regular item imports | Not supported - always creates new items |
| Multi-level subitems hierarchy imports | Create-only, using level columns in the CSV | Create-only, using level columns in the CSV |
| Automations triggered | Yes | No |
| Activity Log | Recorded normally | Not recorded |
| Hourly item budget | Counts toward 19,000 items/account/hour | Does not consume this budget |
For a full step-by-step walkthrough including CSV format, multi-level subitems file format, column type validation, and troubleshooting, see the Importing items in bulk guide.