Export and retention

An export reconstructs one conversation as a single JSON document for a compliance reviewer or an auditor: every message on every branch, every config version that answered, every tool event, every guardrail decision, and every annotation that has not been retracted. Retention is the instance setting that deletes conversation content after a period of inactivity.

Export a conversation

GET /api/v1/conversation-instances/{instance_slug}/conversations/{conversation_id}/export?end_user=... Credential: an organization API key, or a scoped key with conversations:export. conversations:use alone is not enough, because an export is a bulk disclosure rather than a conversational read. The end_user must match the conversation; a mismatch is 404 conversation_not_found.

curl "https://api.usenexio.com/api/v1/conversation-instances/workspace-assistant/conversations/9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93/export?end_user=u_dana_ortiz" \
  -H "Authorization: Bearer $NEXIO_API_KEY" \
  -o conversation-export.json

import os
import json
import requests

resp = requests.get(
    "https://api.usenexio.com/api/v1/conversation-instances/workspace-assistant/conversations/9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93/export",
    headers={"Authorization": "Bearer " + os.environ["NEXIO_API_KEY"]},
    params={"end_user": "u_dana_ortiz"},
)
resp.raise_for_status()
with open("conversation-export.json", "w") as fh:
    json.dump(resp.json(), fh, indent=2)

import { writeFile } from "node:fs/promises"

const resp = await fetch(
  "https://api.usenexio.com/api/v1/conversation-instances/workspace-assistant/conversations/9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93/export?end_user=u_dana_ortiz",
  { headers: { Authorization: `Bearer ${process.env.NEXIO_API_KEY}` } },
)
if (!resp.ok) throw new Error(`export: ${resp.status}`)
await writeFile("conversation-export.json", JSON.stringify(await resp.json(), null, 2))

Response 200:

{
  "export_version": "1",
  "generated_at": "2026-09-23T17:00:12.004381Z",
  "conversation": {
    "id": "9e4c7a12-5b3d-4f81-a6e0-2d8b1c4f7a93",
    "org_id": "2c7e4a19-8d3b-4f60-a5e1-9b0d6c3f7a28",
    "environment": "live",
    "instance_id": "3b9d2f4e-8a1c-4e57-9f02-6c1d8e7a5b34",
    "end_user": "u_dana_ortiz",
    "title": "Getting started",
    "status": "active",
    "created_at": "2026-09-23T14:02:11.482913Z",
    "updated_at": "2026-09-23T14:10:44.912305Z"
  },
  "messages": [
    {
      "id": "c7d1e5a3-2f84-4b6c-9e0a-1b3d5f7a9c28",
      "role": "user",
      "content": [{ "type": "text", "text": "Summarize the runs that failed today." }],
      "turn_id": "5f2a8c61-3e7b-4d09-b1c4-8a6e2f9d0c75",
      "config_version_hash": "4f1c9a7e2b8d3065",
      "created_at": "2026-09-23T14:02:13.118402Z",
      "parent_message_id": null
    },
    {
      "id": "d91a6c38-4e2f-4b75-8a0d-5c3e7b1f2a96",
      "role": "assistant",
      "content": [{ "type": "tool_use", "id": "call_Rk3v8QmT2xLp", "name": "runs.list", "input": { "status": "FAILED" }, "execution": "platform" }],
      "turn_id": "5f2a8c61-3e7b-4d09-b1c4-8a6e2f9d0c75",
      "config_version_hash": "4f1c9a7e2b8d3065",
      "created_at": "2026-09-23T14:02:15.640217Z",
      "parent_message_id": "c7d1e5a3-2f84-4b6c-9e0a-1b3d5f7a9c28"
    }
  ],
  "config_versions": [
    { "hash": "4f1c9a7e2b8d3065", "released_version": "1" }
  ],
  "tool_events": [
    {
      "id": "6b0e2d57-9a3c-4f18-b7e4-1c5a8d3f0e62",
      "turn_id": "5f2a8c61-3e7b-4d09-b1c4-8a6e2f9d0c75",
      "tool_name": "runs.list",
      "execution": "platform",
      "outcome": "ok",
      "duration_ms": 184,
      "created_at": "2026-09-23T14:02:15.829441Z"
    }
  ],
  "guardrail_events": [],
  "annotations": []
}

The messages array above is shortened to two entries for this page; a real export holds every message.

Document fields

Field	Meaning
`export_version`	Contract version of this document. Currently `"1"`.
`generated_at`	When the export was built.
`conversation`	The header: `id`, `org_id`, `environment`, `instance_id`, `end_user`, `title`, `status`, `created_at`, `updated_at`.
`messages`	Every message in insertion order, on every branch. Unlike the conversation GET, there is no 500-message window and no served-branch filter. `parent_message_id` shows how versions relate. Messages have no `branch` field here.
`config_versions`	Every config hash that answered a message, with `released_version` (the integer version as a string) when that hash was released.
`tool_events`	One row per recorded tool outcome, so a confirm-gated call has a `pending_confirmation` row and another row once the user decides. A call to a tool name the assistant does not have gets no row. Fields: `tool_name`, `execution` (`platform` or `client`), `outcome` (`ok`, `error`, `invalid_input`, `pending_confirmation`, `denied`, `approved`), `duration_ms`.
`guardrail_events`	Every guardrail decision: `rule_id`, `decision` (`refused`, `escalated`, `output_check_triggered`), and the `config_version_hash` in force.
`annotations`	Every annotation on the conversation that has not been retracted.

Internal bookkeeping blocks never appear in message content, the same as on every other read. Errors: 400 invalid_request (missing end_user), 401 unauthorized, 403 insufficient_capability, 403 instance_archived, 404 instance_not_found, 404 conversation_not_found.

Retention

retention.conversation_days in the instance config sets how long an inactive conversation is kept. See Instance configuration.

Setting	Effect
`null` (default)	Conversations are kept.
A positive integer `N`	A conversation whose last activity is more than `N` days old is deleted.

How deletion works:

The policy is read from the instance’s latest published version. An instance that has never been published has no policy in force. A follower uses the policy of the instance it follows.
A deletion pass runs once a day.
Deletion is permanent: the conversation and its messages are removed.
Audit records are kept: tool events, guardrail events, usage records, and annotations survive the deletion of the conversation content.
An archived conversation is still subject to retention.

Attachments have their own clock. attachments.retention_days removes a file after that many days; null makes it follow the conversation. After a conversation is deleted, its remaining attachments are swept right after, in the same daily pass. Stored bytes become eligible for removal one hour after an attachment is deleted, and the next daily pass removes them. See Attachments.

Export a conversation (API reference)

The generated endpoint contract.

Data use and subprocessors

Where conversation data goes and why.

Start here

Engines

Conversations

Connections and data

Records

Events and webhooks

Platform

Reference

Export and retention

Export a conversation

Document fields

Retention

Export a conversation (API reference)

Data use and subprocessors

​Export a conversation

​Document fields

​Retention

Export a conversation (API reference)

Data use and subprocessors

Export a conversation

Document fields

Retention