Export session events

Pull recorded events across all sessions for reporting and periodic syncs, with optional date ranges, message type filters, and cursor pagination.

GET /chat/sessions/events

Export session events

cURL

curl --request GET \
  --url http://localhost:8080/chat/sessions/events \
  --header 'Authorization: Bearer <token>'

200

{
  "items": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created_at": "2023-11-07T05:31:56Z",
      "event": {
        "type": "unmapped_event",
        "message_type": "agent_assigned_by_integration",
        "content": {
          "type": "text",
          "text": "<string>"
        }
      },
      "session_id": "<string>",
      "contact_id": "<string>",
      "message_type": "agent_assigned_by_integration",
      "actor": {
        "type": "human",
        "id": "<string>",
        "workflow_run_id": "<string>"
      },
      "details": {
        "message": "<string>",
        "target": {
          "type": "human",
          "id": "<string>"
        },
        "sub_status_id": "<string>",
        "workflow_id": "<string>",
        "workflow_run_id": "<string>",
        "edited_at": "<string>",
        "deleted_at": "<string>"
      }
    }
  ],
  "next": "<string>"
}

Export recorded activity across all sessions in your organization, including messages, internal notes, and system events. Requires an API key with chat-sessions:read.

Use created_after and created_before to select a date window. Both accept ISO 8601 timestamps with a timezone and are optional. The lower bound is inclusive; the upper bound is exclusive and must be later than the lower bound.

Use include_message_types to select recorded types, such as agent_reopened_session,agent_comment, or exclude_message_types to omit types, such as message,agent_message. Both accept comma-separated values. include_message_types takes precedence when both are provided. With neither filter, all recorded types are returned.

Results are ordered oldest first by created_at, then by event id when timestamps match. The default limit is 100 events; it accepts whole numbers from 1 to 250. Pass the response’s next value as cursor to continue, keeping the same organization, date window, and type filters until next is null. Deduplicate overlapping exports by event id.

Each item uses the same id, created_at, and typed event format as session history, with session_id, contact_id, message_type, actor, and details added for exports. The session and contact IDs can be null when unavailable.

Filter on message_type, which is the recorded type. It can differ from the normalized event.type. For example, agent_reopened_session can return {"type":"human_agent_reopened_session","human_agent_id":77} in event.

Use actor to identify who performed the action:

Type	Identifier
human	Human user ID in actor.id, as a string. Typed event payloads can use numeric human IDs.
contact	Contact ID when recorded.
workflow	Workflow ID and workflow_run_id when recorded.
ai	AI actor; no human user ID.
api, system, integration	Source of the recorded action.
unknown	The historical actor could not be identified.

The assignment recipient is separate from the actor: details.target describes a human, ai, team, or none target with an optional string id. details also contains recorded message text, sub_status_id, workflow_id, workflow_run_id, edited_at, and deleted_at. Unavailable values are null.

Events without a history mapping are retained as event.type: "unmapped_event", with their recorded message_type and text content when available. State checkpoint events return payload: null.

Date filters use the original event time, including microsecond precision. Historical imports can arrive later, and edits do not change the original creation time. Re-export earlier windows to reconcile late imports and edits. This endpoint exports recorded history; it does not capture every session or contact attribute change or reconstruct missing historical identities.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

created_after · string<date-time>

Inclusive event timestamp lower bound.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

created_before · string<date-time>

Exclusive event timestamp upper bound.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

include_message_types · string string[]

Comma-separated types to include. When present, exclude_message_types is ignored.

exclude_message_types · string string[]

Comma-separated types to exclude. With neither filter, all event types are returned.

limit · integer · default: 100

Required range: 1 <= x <= 250

cursor · string

Maximum string length: 4096

Response

200

application/json

Default Response

items · object[] · required

Show child attributes

next · string | null · required