backfill_items is for a single, one-time initial load of items into a board - for example, when seeding a board before it goes into day-to-day use. It is not intended for ongoing operational imports; for those, use ingest_items instead.

Compared with ingest, backfill differs in two important ways:

• Automations are not triggered on items created during a backfill.
• Item creation is not logged in the Activity Log.

This makes backfill suitable for one-shot data migrations where you want to seed the board without firing a flood of automation events. To compare the two flows side-by-side, see the Importing items in bulk guide.

The backfill workflow is asynchronous:

1. Start the job with backfill_items and receive a job_id plus a pre-signed upload_url
2. Upload your CSV to the upload_url
3. Poll fetch_job_status with the job_id until the job reaches a terminal state

Supported column types

Board Relation, Date, Dropdown, Email, Link, Long Text, Number, People, Phone, Status, Text, and Timeline. Rows that include unsupported column types may fail validation.

Endpoint behavior

• Maximum rows per uploaded file: 20,000
• Maximum file size: 150 MB
• Upload URL and report URL expiration: 10 minutes
• Required scope: boards:write and account admin role
• on_match is not supported (every row creates a new item)
• Does not count against the per-account hourly item create/update budget that applies to ingest
• Supports create-only hierarchy imports on multi-level subitems boards. Use level columns from name.l1 through name.l5; see the Importing items in bulk guide for the full CSV format.
• Supports Board Relation columns. See the Importing items in bulk guide for the CSV value format and limits.

Queries

Fetch job status

Use fetch_job_status to poll a backfill job. It returns the JobStatus union, currently implemented as ItemsJobStatus.

• Required scope: boards:read
• Returns a JobStatus union
• Can only be queried directly at the root; cannot be nested inside another selection set

query {
  fetch_job_status(job_id: "550e8400-e29b-41d4-a716-446655440000") {
    ... on ItemsJobStatus {
      status
      counts {
        submitted
        invalid
        skipped
        created
        updated
        failed
      }
      progress_percentage
      failure_reason
      failure_message
      fully_imported
      report_created
      report_url
    }
  }
}

Arguments

Fields (ItemsJobStatus)

Mutations

Required scope: boards:write (account admin only)

Backfill items

Starts a backfill import job and returns UploadJobInit with the job_id and the pre-signed upload_url.

mutation {
  backfill_items(board_id: "1234567890", group_id: "topics") {
    job_id
    upload_url
  }
}

Arguments

Response fields

Do not include x-amz-checksum-crc32 as a request header when uploading to the pre-signed URL. The URL may include checksum query parameters, but forwarding the checksum as an unsigned request header can cause S3 to reject the upload with HTTP 403.

Multi-level subitems hierarchy imports

For MLS file format and hierarchy rules, see the Multi-level subitems boards section in the Importing items in bulk guide. backfill_items remains admin-only and does not trigger automations or Activity Log item creation.

Capacity and rate limits

• Start-job calls. backfill_items and ingest_items share a per-account hourly limit of 100 successful start-job calls per hour. Exceeding the limit returns RATE_LIMIT_EXCEEDED (HTTP 429) with extensions.retryAfterMs.
• Item create/update budget. Backfill does not consume the 19,000-item-per-hour budget that ingest_items uses.
• File size. Files over 150 MB are rejected with failure_reason: FILE_TOO_LARGE.

See also

• Importing items in bulk - full step-by-step guide
• Ingest items API reference - recommended for ongoing integrations
• Bulk import other types - input objects, result types, and enums