Export Records as PDF

Use the exportRecordsPdf mutation to export the records of a workspace as one PDF, rendered from a Portable Document template. The mutation is asynchronous: it returns true once the job is queued, the finished PDF is emailed to the requesting user, and progress streams over the subscribeToImportExportProgress subscription. Records are Record objects, a workspace is a Workspace, a record table is a RecordDatabase, and a template is a PortableDocument in the API.

mutation ──► export-pdf queue ──► worker renders one PDF (one page set per record)
                                      │
                                      ├─► progress events ──► subscription + exportPdfProgress query
                                      └─► uploaded file ──► "Download PDF" email

Request

Export every record of a workspace through a template:

mutation ExportRecordsPdf {
  exportRecordsPdf(input: { projectId: "project_123", pdfId: "clm4n8qwx000008l0g4oxdqn7" })
}

projectId must be the workspace ID — a slug is not accepted and fails with PROJECT_NOT_FOUND. pdfId is the template’s id (the CUID returned by the portableDocuments query), not its pdf_… uid. The template must be active and belong to that workspace.

Parameters

ExportRecordsPdfInput

The template’s table link

A template fills its overlay placements from a table’s fields through the link created with setPortableDocumentDatabaseLinks. With databaseId set, the template must have a link to that table, and the mutation validates the link against the live template placements and the table fields you can see before queueing the job. A template that is not linked to the selected table, or a mapping that no longer fits, fails with BAD_USER_INPUT before the job is queued. See Link a template to record tables for the mapping rules and the field types the renderer covers.

With databaseId omitted, each matching record still renders through the table it was selected from, using that table’s link when the template has one.

RecordsFilter

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

Filter conditions resolve against each exported table’s mounted fields, so a condition on a custom field matches the records of every table that mounts a field it resolves to.

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

exportRecordsPdf returns a bare boolean — true once the job is queued. The PDF is generated in the background and emailed to the requesting user.

{ "data": { "exportRecordsPdf": true } }

Returns

Full example

Export the records of one table — incomplete, assigned to two users, tagged, due in Q1, matching a search term and a custom-field value — through a linked template:

mutation ExportFilteredRecordsPdf {
  exportRecordsPdf(
    input: {
      projectId: "project_123"
      pdfId: "clm4n8qwx000008l0g4oxdqn7"
      databaseId: "clm4n8qwx000008l0t9table1"
      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
      }
    }
  )
}

Which records are selected

• With databaseId — only that table’s records are considered.
• Without databaseId — every live table of the workspace is walked in table order. Each matching record prints through the table it was selected from, and a record that sits in several tables prints once.

The selection runs through the exporting user’s live record and field policy: a record, or a field on a record, that your role cannot view is left out of the PDF. An empty result fails the job — there is no “0 pages” PDF (see Job-time failures).

Delivery

The worker uploads the finished PDF and publishes a COMPLETE progress event carrying the download URL, then emails the requesting user a Download PDF link for the file. The URL is a signed export link, so it expires; the email is the durable delivery, and the same URL is available from the progress channel below.

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 TrackPdfExportProgress {
  subscribeToImportExportProgress(projectId: "project_123", userId: "user_123")
}

PDF export events carry type: "EXPORT_PDF":

{
  "data": {
    "subscribeToImportExportProgress": {
      "type": "EXPORT_PDF",
      "status": "IN_PROGRESS",
      "userId": "user_123",
      "projectId": "project_123",
      "projectName": "Q1 Launch",
      "current": 120,
      "total": 250,
      "progress": 48
    }
  }
}

Live events are fire-and-forget: a client that navigates away or refreshes misses everything sent in between. The exportPdfProgress query reads the durable server-side snapshot (kept for about 1 hour, scoped to the calling user) to re-sync on mount:

query ExportPdfProgress {
  exportPdfProgress(projectId: "project_123")
}

{
  "data": {
    "exportPdfProgress": {
      "status": "COMPLETE",
      "current": 250,
      "total": 250,
      "fileUrl": "https://api.blue.app/exports/eyJ...",
      "updatedAt": "2026-05-29T14:03:02.000Z"
    }
  }
}

The snapshot’s status is GENERATING, COMPLETE, or ERROR; on ERROR it carries error instead of fileUrl.

Errors

Job-time failures

Everything above rejects the mutation itself. The queued job can still fail; the failure surfaces as an ERROR progress event plus a failure email to the requesting user, never as a GraphQL error:

Permissions

There is no batch or multi-workspace PDF export — one call covers one workspace.

Notes

• One PDF, not one per table. Unlike the CSV export, which builds a file per database, exportRecordsPdf appends every matching record’s pages to a single document.
• The template must be built first. Create and place fields on the template as described in Build Portable Document templates, and print a single record with printPortableDocument to check the layout before exporting hundreds of records.
• Rate limit and tier limits stack. The per-operation 1-per-50-seconds limit runs inside GraphQL on top of the tier limits described in Rate Limits.
• Imports and CSV exports are covered elsewhere. See the Import/Export overview and Export records.

Related

• Export records — the CSV equivalent, with the full filter behavior
• Build Portable Document templates — create the template and link it to record tables
• Map fields and print Portable Documents — place overlay fields and print one record
• Export a CSV template — download the workspace’s columns before importing
• Rate Limits