Import Records

Use the importRecords mutation to bulk-import records into a workspace from a CSV file that has already been uploaded to storage. The file is parsed in streaming chunks and records are created in the background. Records are Record objects and a workspace is a Workspace in the API.

The import runs asynchronously: the mutation returns true once the job is accepted, then you follow its progress with the subscribeToImportExportProgress subscription. Use cancelRecordImport to stop an import that is still running.

Before calling importRecords, upload the CSV and obtain its storage key. See Uploading Files for both upload paths.

Request

The smallest call needs the storage key of the uploaded file, an ordered array of column headers, and the workspace id.

mutation ImportRecords {
  importRecords(
    input: {
      s3Key: "uploads/org_123/project_123/import.csv"
      headers: ["Title", "List", "Done", "Due Date"]
      projectId: "project_123"
    }
  )
}

projectId is the workspace CUID (the id field of Workspace). The headers map each CSV column, in order, to a record field; see Recognized headers below.

Parameters

ImportRecordsInput

Recognized headers

The headers array tells the importer how to interpret each CSV column. These built-in names are recognized; any other header is matched to a custom field of the same name in the workspace.

To produce a CSV that already lines up with a workspace’s columns, download a CSV template first.

Response

importRecords returns Boolean! — true once the import has been accepted and queued.

{ "data": { "importRecords": true } }

A true response means the job is enqueued, not finished. Subscribe to import progress to know when it completes.

Full example

Custom-field columns are imported by adding their exact field name as a header alongside the built-in ones. Here the workspace has Budget and Priority custom fields:

mutation ImportRecordsWithCustomFields {
  importRecords(
    input: {
      s3Key: "uploads/org_123/project_123/import.csv"
      headers: ["Title", "List", "Done", "Due Date", "Assignees", "Tags", "Budget", "Priority"]
      projectId: "project_123"
    }
  )
}

Track import progress

Subscribe to subscribeToImportExportProgress to receive real-time progress while an import (or export) runs. The field returns JSON (nullable); each event is an untyped JSON object with the shape below.

subscription TrackImportProgress {
  subscribeToImportExportProgress(projectId: "project_123", userId: "user_123")
}

The stream is filtered by userId only: you receive every import and export event for that user. projectId is required by the schema but does not currently scope the events.

Event payload

A sample event:

{
  "data": {
    "subscribeToImportExportProgress": {
      "type": "IMPORT",
      "userId": "clm4n8qwx000008l0g4oxdqn7",
      "username": "Ada",
      "projectId": "marketing-ops",
      "projectName": "Marketing Ops",
      "status": "IN_PROGRESS",
      "progress": 42
    }
  }
}

Note the identifier spaces differ: you pass the workspace CUID as projectId to importRecords, but the payload’s projectId is the workspace slug.

Cancel an import

Use cancelRecordImport to stop an import that is still running. The worker checks for the cancel flag on each chunk and aborts.

mutation CancelImport {
  cancelRecordImport(projectId: "project_123")
}

projectId accepts either the workspace id (CUID) or its slug. The mutation returns Boolean! — true once the cancellation has been recorded.

{ "data": { "cancelRecordImport": true } }

Errors

Permissions

Behavior notes

• Lists and tags auto-create. Lists and tags referenced in the CSV that don’t already exist in the workspace are created during the import.
• Custom fields match by name. Any header that isn’t a built-in name is matched to a custom field of the same name. Add custom-field columns to the headers array to import their values.
• Upload first. The CSV must be uploaded to storage before you call importRecords. See Uploading Files to get the s3Key.

Related

• Export records
• Export a CSV template
• Uploading files
• Error codes