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
| Action | Who can do it |
|---|---|
| Export your own chat | Any member |
| Export another member's chat | Members 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:
| Format | Extension | Best for |
|---|---|---|
| JSONL | .jsonl | Complete fidelity — metadata, tool calls, and reasoning; one JSON object per line |
| CSV | .csv | Spreadsheets, filtering, and pivot tables |
| Markdown | .md | Reading, pasting into documents, and diffs |
| Plain Text | .txt | Reading and archiving without markup |
All four carry the same messages; only the serialization differs.
From the UI
- Go to Chats and open the chat you want to export.
- Click the download button in the chat header.
- Pick a format from the list.
- 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, andtool_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
- Go to Chats.
- Apply any filters you want (channel, date range, workflow, labels, etc.).
- Click the Export button in the Chats table toolbar.
- The browser downloads a
.csvfile.
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 OKeven 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 withEXPORT_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.
Related
- Chats — Managing chats
- Chat Filters — Save and reuse filter combinations for repeatable exports
- Generating Summaries — Create AI-powered summaries before exporting