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.

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.
• 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 (with per-user permission checks) and merges their filters before queuing one export.

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.