> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Export for sessions, macros and fields

> Export filtered sessions to CSV with the columns, custom data and chat history you choose, and download your macros and Structured Fields as CSV files.

Data Export turns a filtered set of sessions into a CSV file with the columns you choose, including custom data and the full chat history. The same page downloads your macros and your Structured Fields as CSV files.

> [!NOTE]
>
> **Reports & Apps → Data Export** in your [OpenCX dashboard](https://platform.open.cx/reports/data-export). Requires **Reports: Read** in [Roles](https://docs.open.cx/security/roles.md), plus access to view sessions (**Inbox**, **Team sessions** or **Assigned sessions**: Read) to export them. It isn't in the sidebar until someone adds it; see [Reports & Apps](https://docs.open.cx/reports/overview.md).

## Export sessions

![On Data export, turning on Include chat history, Notify me when it's ready already on, selecting Export 214 sessions, and the export processing at the top of Export history](https://mintcdn.com/openchat/fVh-H-7YLqGS1Ks3/images/workspace/data-export.gif?s=54f38c794ec20f0205db59ecc212dcd1)

Turn on Include chat history, keep Notify me when it's ready on, and start the export: it builds in Export history.

**1. Filter the sessions**

**Session filters** uses the same filters as the inbox. A date range is always applied: the last 7 days by default. You can change it but not remove it, and day-based dates use your browser's time zone. **Clear all** returns to the default.

**2. Set the options**

Under **Options**, turn on **Include chat history** to add the transcript, then pick a **History format**. **Notify me when it's ready** is on by default.

**3. Choose the columns**

Tick the columns you want under **Columns**. Select a column's name to rename its CSV header; the original name stays beside it. **Reset** restores the default columns and headers and removes custom data columns. At least one column always stays selected.

**4. Review the export**

**Review export** shows how many sessions match, how many columns the file will have, and a sample of matching sessions. **CSV layout** previews the headers and cell formatting of the file.

**5. Start the export**

Select **Export … sessions**. The file is built in the background and appears in **Export history**. You can leave the page.

An export contains only the sessions you can see. A member whose role is limited to team or assigned sessions exports only those.

## Choose columns

These columns are selected by default: **Session ID**, **Status**, **Channel**, **Created At**, **Last Message At**, **AI Closure Type**, **Handoff Reason**, **Handoff Explanation**, **Title**, **Contact Name**, **Phone Number**, **Contact Email**, **Classification**, **Sentiment**, **Language**, **External Session ID**, **Session Tags**, **CSAT Score** and **CSAT Comment**.

| Column | Contains |
| - | - |
| **AI Closure Type** | The AI's outcome for the session, as defined on the [Impact Dashboard](https://docs.open.cx/reports/impact-dashboard.md#what-each-outcome-means). Empty when the AI has no outcome. |
| **Handoff Reason** / **Handoff Explanation** | The reasons the AI recorded when it handed the session off, comma-separated, and its explanation. |
| **External Session ID** | The session's ID in a connected helpdesk or CRM, such as the Zendesk ticket or Salesforce case. |
| **Session Tags** | The session's tags, comma-separated. |
| **Created At** / **Last Message At** | Date and time in UTC. |

These columns are off by default. Tick them to add them:

| Column | Contains |
| - | - |
| **History** | The chat history. Available only with **Include chat history** on, which selects it. |
| **Client IP** | The visitor's IP address. Off by default because it is personal data. |
| **Sessions From IP** / **Contacts From IP** | How many sessions and contacts in this export share the session's IP address. Counted across the exported sessions only, so a narrower date range lowers them. |
| **Phone Waits For Agent**, **Phone First Wait (s)**, **Phone First Answered By**, **Phone Answer SLA** | Phone answer time per session. See [Phone answer-time SLA](https://docs.open.cx/phone/answer-time-sla.md). |
| **Phone Agent Handles**, **Phone Talk (s)**, **Phone Hold (s)**, **Phone After-Call Work (s)**, **Phone AHT (s)** | Phone handle time per session. |

### Add custom data columns

Under **Custom data columns**, select **Add**, choose **Session custom data** or **Contact custom data**, pick a **Data key**, and set the **CSV header**. The header fills in with the key name until you change it. A row without both a key and a header is left out of the file.

### Include the chat history

| History format | What the file gets |
| - | - |
| **Single JSON column** | The whole transcript of each session in the **History** column, as JSON. |
| **One column per message** | **Message 1**, **Message 2** and so on, up to the number of messages in the longest exported session. |

## Track and download exports

**Export history** lists your organization's exports, newest first. Members limited to team or assigned sessions see only the exports they started.

| Status | Meaning |
| - | - |
| **Queued** | Waiting to start. |
| **Processing** | Building the file, with sessions done out of the total, a percentage and the estimated time left. |
| **Ready** | Done. Shows the number of records and the file size. |
| **Failed** | The export stopped. Hover the status to read why. |

Open a row's **⋯** menu to **Download CSV** or **Delete** it. Deleting permanently removes the file. Export files are kept until someone deletes them; see [Data retention](https://docs.open.cx/security/data-retention.md).

With **Notify me when it's ready** on, you get a dashboard notification when your export finishes or fails. Opening it takes you to that export in **Export history**.

## Export macros and Structured Fields

Both download immediately in your browser, ignore the session filters, and don't appear in **Export history**.

> [tab] Macros
>
> In the **Macros** section, select **Export CSV**, then **Download CSV**. Requires **Settings: Read** or **Macros settings: Read**.
>
> The file has one row per macro: shared macros, and your personal versions in place of the shared originals they replace. Other people's personal macros are not included. Attachments are listed as links; the files themselves are not included.
>
> Columns: `id`, `title`, `category`, `content_html`, `visibility` (`shared` or `personal`), `owner_user_id`, `overrides_macro_id`, `custom_variables` (the custom variables the macro uses, including variables used inside them, with their content), `options`, `attachments`, `exclude_from_suggestions`, `created_at`, `updated_at`.

> [tab] Structured Fields
>
> In the **Structured Fields** section, select **Export CSV**, then **Download CSV**. Requires **Structured Fields: Read**.
>
> The file has one row per choice, with nested choices pointing to their parent through `parent_variant_value` and `depth` (0 for the top level). A field with a typed value has one row carrying it in `field_value`, and a field with no choices still gets one row.
>
> Columns: `field_key`, `field_name`, `field_description`, `field_type`, `field_value`, `variant_value`, `variant_name`, `variant_description`, `parent_variant_value`, `depth`. See [Structured Fields](https://docs.open.cx/ticketing/structured-fields.md).

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| **Add filters to preview** and the export button is disabled | No session filter is set | Set a date range or another filter under **Session filters**. |
| **No sessions match** | The filters exclude every session | Widen the date range or relax other filters. |
| An export shows **Failed** with **Export timed out before processing started. Please retry.** or **Export stopped updating and is considered failed. Please retry.** | It didn't start, or stopped making progress, for 30 minutes | Start the export again. If it keeps failing, contact support. |
| The **Macros** or **Structured Fields** section is missing | Your role lacks the read access each one needs | Ask an admin to grant it in [Roles](https://docs.open.cx/security/roles.md). |

***

## Related Documentation

> [card] [Impact Dashboard](https://docs.open.cx/reports/impact-dashboard.md)
>
> What AI Closure Type means

> [card] [Inbox](https://docs.open.cx/inbox/intro.md)
>
> The same session filters

> [card] [Data retention](https://docs.open.cx/security/data-retention.md)
>
> How long exports are kept

> [card] [Phone answer-time SLA](https://docs.open.cx/phone/answer-time-sla.md)
>
> Phone columns explained


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.