Export Records

Use the exportRecords mutation to start an asynchronous CSV export of records from a workspace. The mutation returns immediately with true to confirm the job was queued; the finished CSV is emailed to the requesting user as a download link. There is no API-returned URL — the emailed link is the only way to fetch the file. Track progress in real time with the subscribeToImportExportProgress subscription. (Records are Record objects in the API; a workspace is a Workspace.)

This page also covers two related exports:

• exportReport — export records across every workspace referenced by a report’s data sources.
• exportChartCSV — export the underlying data of a dashboard chart.

Request

Export all records from a workspace. Only projectId is required.

mutation ExportRecords {
  exportRecords(input: { projectId: "project_123" })
}

projectId accepts a workspace ID or slug.

A workspace can hold more than one database (table). By default the export covers every database in the workspace, and the worker builds one CSV per database: a single-database workspace gets one file, as before, while a multi-database workspace gets one CSV per database — the email lists a download link for each, and the progress event’s fileUrl points at one combined CSV whose first two columns, Source Table ID and Source Table, say which database each row came from. Pass databaseId to export a single database instead.

Parameters

ExportRecordsInput

TodosFilter

Combine any of these fields to narrow the export. Unless noted, fields are ANDed together.

FilterLogicalOperator

Custom-field filters

Each entry in the fields array must include a type — the query layer routes on it, and entries without type are silently dropped. The most common type is CUSTOM_FIELD:

[
  {
    "type": "CUSTOM_FIELD",
    "customFieldId": "field_123",
    "customFieldType": "CHECKBOX",
    "op": "IS",
    "values": true
  }
]

Other valid type values are TIME_IN_LIST, RELATIVE_DUEDATE, and FIELD. The operators available per customFieldType depend on the field type.

Response

exportRecords returns a bare boolean — true once the job is queued. The CSV is generated in the background and emailed to the requesting user; the API never returns the file or a URL.

{ "data": { "exportRecords": true } }

Returns

Full example

Export incomplete records assigned to two users, tagged, due in Q1, matching a search term and a custom-field value:

mutation ExportFilteredRecords {
  exportRecords(
    input: {
      projectId: "project_123"
      filter: {
        companyIds: ["company_123"]
        done: false
        assigneeIds: ["user_123", "user_456"]
        tagIds: ["tag_123"]
        dueStart: "2026-01-01T00:00:00Z"
        dueEnd: "2026-03-31T23:59:59Z"
        q: "launch"
        fields: [
          {
            type: "CUSTOM_FIELD"
            customFieldId: "field_123"
            customFieldType: "SELECT_SINGLE"
            op: "IS"
            values: ["option_123"]
          }
        ]
        op: AND
      }
    }
  )
}

Export a report

Use the exportReport mutation to export records across every workspace referenced by a report’s data sources. The export combines the records from all of those workspaces and applies any report-level filters; like exportRecords, it returns true and delivers the CSV by email.

mutation ExportReport {
  exportReport(input: { reportId: "report_123" })
}

{ "data": { "exportReport": true } }

ExportReportInput

Export a chart

Use the exportChartCSV mutation to export the underlying data of a dashboard chart as a CSV file. It returns true and emails the file to the requesting user.

mutation ExportChart {
  exportChartCSV(chartId: "chart_123", filter: { assigneeIds: ["user_123"], showCompleted: false })
}

{ "data": { "exportChartCSV": true } }

TodoFilterInput

The chart filter is a different type from TodosFilter (which exportRecords uses). TodoFilterInput has no companyIds, todoIds, search, startedAt, duedAt, coordinates, or excludeArchivedProjects; instead it uses colors, and adds completed-date and last-updated-by axes. Fields shared with TodosFilter (assigneeIds, tagIds, showCompleted, q, …) behave the same — but a key like companyIds is not accepted here.

Track export progress

Subscribe to subscribeToImportExportProgress to receive real-time progress for the current user’s imports and exports. The subscription filters server-side by userId, so pass the ID of the user who started the export.

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

The subscription resolves a JSON payload. For exports, the worker publishes events shaped like this:

{
  "data": {
    "subscribeToImportExportProgress": {
      "type": "EXPORT",
      "userId": "user_123",
      "username": "Casey",
      "projectName": "Q1 Launch",
      "status": "COMPLETE",
      "progress": 100,
      "fileUrl": "https://api.blue.app/uploads/export-1234/q1-launch-export-1430290126.csv",
      "totalCount": 482
    }
  }
}

On failure the event carries "status": "ERROR", "progress": 0, and an error message instead of fileUrl/totalCount. See the Import/Export overview for the import-side payload.

Errors

exportReport also throws a generic (untyped) error — No valid projects found in report data sources — when the report’s data sources resolve to zero accessible workspaces. This surfaces with no extensions.code.

Permissions

Notes

• Delivery is email-only. Every export here returns a bare true; the CSV is generated in the background and a download link is emailed to the requesting user. There is no programmatic way to fetch the file from the API.
• Exports respect record and field visibility. exportRecords builds each database’s CSV through the exporting user’s permission-filtered read: a record or a field the caller’s role cannot view is silently left out of the file.
• Checklists are included. The exportTodos CSV carries a Checklists column (after Project, before custom-field columns) holding each record’s checklist items, with [x] for done items and [ ] for open ones — for example Topics: Acid-Base [x], Blood Product [ ]. Records with no checklists leave the cell empty. This applies to the CSV export only; the PDF export is unaffected.
• Chart export deduplication. exportChartCSV sets a lock keyed by (chartId, userId) for 6 hours (21,600 s) on each accepted request. A repeat request for the same chart by the same user inside that window is rejected with CHART_ALREADY_EXPORTING. The 6-hour window restarts from the most recently accepted export.
• Report exports combine data sources. exportReport resolves every workspace referenced by the report’s data sources (permission-checked against the report creator’s access) and queues one export that applies each data source’s own workspace scope and filter. A report over archived workspaces only still exports them.

Related

• Export CSV template — download a blank CSV with the workspace’s columns.
• Import/Export overview — import records and the full progress-event reference.
• List records — read records through the API instead of exporting.
• Dashboards — create the charts that exportChartCSV exports.