Skip to main content

Exporting Chats

Gravity Rail lets you export chat data in two ways:

  • Single chat — download one chat as JSONL, CSV, Markdown, or plain text (the transcript with messages, metadata, and tool calls; staff notes are omitted unless you ask for the admin mode below)
  • Bulk export — download all chats (or a filtered subset) as a CSV file

Both export types are useful for compliance, legal hold, records management, and offline analysis.

PHI notice: Exported files may contain Protected Health Information. Handle and store them according to your organization's data handling policies. Do not share export files through unprotected channels.

Permissions​

ActionWho can do it
Export your own chatAny member
Export another member's chatMembers with the chats:admin scope; private Chats also require participation
Bulk export (CSV)Members with the chats:read scope

If you cannot see the export option, ask your workspace admin to check your role permissions.

Exporting a Single Chat​

A single-chat export contains the chat transcript — chat metadata followed by every message in chronological order. You must participate in a private Chat to export it, even if you have chats:admin.

Staff notes are not in a default export. Notes staff write beside a chat (see Staff Notes) are private admin context, never messages to the member, so neither the download button nor GET …/export includes them by default. The admin mode is the API parameter includeStaffNotes=true: it requires the chats:admin scope and access to the chat (a private chat's notes stay participant-only), and it labels each note as a staff note rather than a message. It is an API-only mode; the UI download never sets it.

Choosing a format​

The download button opens a list of four formats:

FormatExtensionBest for
JSONL.jsonlComplete fidelity — metadata, tool calls, and reasoning; one JSON object per line
CSV.csvSpreadsheets, filtering, and pivot tables
Markdown.mdReading, pasting into documents, and diffs
Plain Text.txtReading and archiving without markup

All four carry the same messages; only the serialization differs.

From the UI​

  1. Go to Chats and open the chat you want to export.
  2. Click the download button in the chat header.
  3. Pick a format from the list.
  4. The browser downloads a file named after the chat title and timestamp.

The same list appears on every chat download button.

Via the API​

GET /api/v2/w/{workspace_id}/chats/{chat_id}/export?format=jsonl

format is one of jsonl (the default), csv, markdown, or txt. Add includeStaffNotes=true for the admin mode described above; without it the export never contains staff notes. The response is a downloadable attachment with the matching content type: application/x-ndjson, text/csv, text/markdown, or text/plain.

JSONL file format​

The first line is the chat record:

{"type": "chat", "id": 123, "title": "Support enquiry", "channel": "sms", "chat_type": "assignment", "created_at": "2026-01-15T10:00:00", "archived": false, "is_test": false}

Each subsequent line is a message:

{"type": "message", "id": 456, "message_id": "msg-abc123", "role": "user", "content": "Hello, I need help.", "channel": "sms", "received_at": "2026-01-15T10:00:05"}
{"type": "message", "id": 457, "message_id": "msg-def456", "role": "assistant", "content": "Hi! How can I help you today?", "channel": "sms", "received_at": "2026-01-15T10:00:08", "model": "claude-sonnet-4-6"}

Optional fields (model, call_id, tool_calls, reasoning_content) appear only when they have values.

CSV, Markdown, and plain text​

  • CSV has one row per message with the columns chat_id, chat_title, message_id, role, content, received_at, channel, and tool_calls.
  • Markdown starts with the chat title and metadata, then one ## <role> — <timestamp> section per message.
  • Plain text starts with the chat title and metadata, then one block per message separated by a rule.

Bulk-Exporting Chats (CSV)​

The bulk export downloads all chats that match the filters currently applied to the Chats table.

From the UI​

  1. Go to Chats.
  2. Apply any filters you want (channel, date range, workflow, labels, etc.).
  3. Click the Export button in the Chats table toolbar.
  4. The browser downloads a .csv file.

The CSV includes chat metadata and participant information. Message content is not included in the CSV — use the single-chat export when you need full transcripts; it offers JSONL, CSV, Markdown, and plain text.

Via the API​

GET /api/v2/w/{workspace_id}/chats/export

Supports all the same query parameters as the chat list endpoint (sortBy, sortOrder, mine, archived, channel, chatType, memberId, search, filters, isTest).

Size limit​

Bulk CSV exports are capped at 500 MB. If a result set would exceed this limit, the export is truncated and the last row of the file will be:

EXPORT_TRUNCATED,"Result truncated at 500 MB limit. Re-export with narrower filters."

API clients: the response status code is 200 OK even when the export is truncated. The size cap is enforced mid-stream, after headers have been sent, so it cannot be signalled via the status code. Detect truncation by checking whether the final CSV row begins with EXPORT_TRUNCATED — do not rely on the status code alone.

Use date range, channel, or other filters to narrow the export and retrieve the remaining records.