Skip to content

List events

GET
/events
curl --request GET \
--url 'https://optlo.com/api/v1/events?limit=50&type=user.email_captured&order=desc' \
--header 'Authorization: Bearer <token>'

Returns immutable snapshots ordered by workspace ingestion sequence. Only events permitted by the key’s read scopes are visible. Explicitly requesting an unauthorized type returns 403. Events are retained for 30 days after ingestion. An expired cursor returns 410 and requires resource resynchronization. In ascending order, always retain nextCursor, including on empty pages; caught-up cursors renew their validity for another 30 days.

limit
integer
default: 50 >= 1 <= 100

Maximum number of resources to return on one page.

cursor
string

Opaque cursor bound to workspace, order, type selection and effective event visibility; survives key rotation. Keep the latest nextCursor when polling in ascending order, including on empty pages.

type
string
Allowed values: user.email_captured conversation.created conversation.closed conversation.reopened conversation.escalated message.created note.created

Return only this event type. Omit to include all types permitted by the key’s read scopes.

order
string
default: desc
Allowed values: desc asc

Order by workspace ingestion sequence. Use asc to poll for new events.

Success

Media typeapplication/json
Show child attributesHide child attributes
data
required

Resources on this page.

array
dictionary

One of:

user.email_captured
Show child attributesHide child attributes
id
required

Unique identifier for the event. Use it to deduplicate webhook deliveries.

string
version
required

Version of the event envelope format.

Allowed value: 1
createdAt
required

Time the event occurred.

string format: date-time
workspaceId
required

ID of the workspace where the event occurred.

string
origin
required

Channel that caused the event.

string
Allowed values: web dashboard api email system
actor
required

Participant or API key that caused the event. For assistant activity in response to a message, the participant who sent that message. Null for activity without an attributed actor.

nullable dictionary
Show child attributesHide child attributes
role
required

Type of participant or API key that caused the event.

string
Allowed values: user operator assistant apiKey
id
required

Unique identifier for the actor.

string
causationId
required

Identifier linking the event to its originating operation, when available.

nullable string
type
required

A user’s email address was captured.

Allowed value: user.email_captured
data
required

Snapshot of the user at the time of the event.

dictionary
Show child attributesHide child attributes
user
required

User whose email address was captured.

dictionary
Show child attributesHide child attributes
id
required

Unique identifier for the user.

string
email
required

Email address captured for the user.

string
conversation.created
Show child attributesHide child attributes
id
required

Unique identifier for the event. Use it to deduplicate webhook deliveries.

string
version
required

Version of the event envelope format.

Allowed value: 1
createdAt
required

Time the event occurred.

string format: date-time
workspaceId
required

ID of the workspace where the event occurred.

string
origin
required

Channel that caused the event.

string
Allowed values: web dashboard api email system
actor
required

Participant or API key that caused the event. For assistant activity in response to a message, the participant who sent that message. Null for activity without an attributed actor.

nullable dictionary
Show child attributesHide child attributes
role
required

Type of participant or API key that caused the event.

string
Allowed values: user operator assistant apiKey
id
required

Unique identifier for the actor.

string
causationId
required

Identifier linking the event to its originating operation, when available.

nullable string
type
required

A conversation was created.

Allowed value: conversation.created
data
required

Snapshot of the conversation at the time of the event.

dictionary
Show child attributesHide child attributes
conversation
required

Newly created conversation.

dictionary
Show child attributesHide child attributes
id
required

Unique identifier for the conversation.

string
userId
required

ID of the user the conversation belongs to.

string
createdAt
required

Time the conversation was created.

string format: date-time
conversation.closed or conversation.reopened
Show child attributesHide child attributes
id
required

Unique identifier for the event. Use it to deduplicate webhook deliveries.

string
version
required

Version of the event envelope format.

Allowed value: 1
createdAt
required

Time the event occurred.

string format: date-time
workspaceId
required

ID of the workspace where the event occurred.

string
origin
required

Channel that caused the event.

string
Allowed values: web dashboard api email system
actor
required

Participant or API key that caused the event. For assistant activity in response to a message, the participant who sent that message. Null for activity without an attributed actor.

nullable dictionary
Show child attributesHide child attributes
role
required

Type of participant or API key that caused the event.

string
Allowed values: user operator assistant apiKey
id
required

Unique identifier for the actor.

string
causationId
required

Identifier linking the event to its originating operation, when available.

nullable string
type
required

A conversation was closed or reopened.

string
Allowed values: conversation.closed conversation.reopened
data
required

Snapshot of the conversation’s new state.

dictionary
Show child attributesHide child attributes
conversation
required

Conversation whose open or closed state changed.

dictionary
Show child attributesHide child attributes
id
required

Unique identifier for the conversation.

string
userId
required

ID of the user the conversation belongs to.

string
closedAt
required

Time the conversation was closed. Null for a reopened conversation.

nullable string format: date-time
conversation.escalated
Show child attributesHide child attributes
id
required

Unique identifier for the event. Use it to deduplicate webhook deliveries.

string
version
required

Version of the event envelope format.

Allowed value: 1
createdAt
required

Time the event occurred.

string format: date-time
workspaceId
required

ID of the workspace where the event occurred.

string
origin
required

Channel that caused the event.

string
Allowed values: web dashboard api email system
actor
required

Participant or API key that caused the event. For assistant activity in response to a message, the participant who sent that message. Null for activity without an attributed actor.

nullable dictionary
Show child attributesHide child attributes
role
required

Type of participant or API key that caused the event.

string
Allowed values: user operator assistant apiKey
id
required

Unique identifier for the actor.

string
causationId
required

Identifier linking the event to its originating operation, when available.

nullable string
type
required

A conversation was escalated to an operator.

Allowed value: conversation.escalated
data
required

Snapshot of the conversation and its escalation.

dictionary
Show child attributesHide child attributes
conversation
required

Conversation that was escalated.

dictionary
Show child attributesHide child attributes
id
required

Unique identifier for the conversation.

string
userId
required

ID of the user the conversation belongs to.

string
escalation
required

Details of the escalation.

dictionary
Show child attributesHide child attributes
id
required

Unique identifier for the escalation.

string
assistantId
required

ID of the assistant that escalated the conversation.

string
sequence
required

Position of the escalation in the conversation’s event sequence.

number
message.created or note.created
Show child attributesHide child attributes
id
required

Unique identifier for the event. Use it to deduplicate webhook deliveries.

string
version
required

Version of the event envelope format.

Allowed value: 1
createdAt
required

Time the event occurred.

string format: date-time
workspaceId
required

ID of the workspace where the event occurred.

string
origin
required

Channel that caused the event.

string
Allowed values: web dashboard api email system
actor
required

Participant or API key that caused the event. For assistant activity in response to a message, the participant who sent that message. Null for activity without an attributed actor.

nullable dictionary
Show child attributesHide child attributes
role
required

Type of participant or API key that caused the event.

string
Allowed values: user operator assistant apiKey
id
required

Unique identifier for the actor.

string
causationId
required

Identifier linking the event to its originating operation, when available.

nullable string
type
required

A customer-visible message or internal note was created.

string
Allowed values: message.created note.created
data
required

Snapshot of the message at the time of the event.

dictionary
Show child attributesHide child attributes
message
required

Newly created message or internal note.

dictionary
Show child attributesHide child attributes
id
required

Unique identifier for the message or note.

string
conversationId
required

ID of the conversation containing this message.

string
kind
required

Whether this is a customer-visible message or an internal note.

string
Allowed values: message note
content
required

Markdown text of the message or note. Literal characters typed by users are backslash-escaped.

string
sender
required

Participant who sent the message.

dictionary
Show child attributesHide child attributes
id
required

Unique identifier for the sender.

string
role
required

Type of participant who sent the message.

string
Allowed values: user operator assistant
createdAt
required

Time the message was created.

string format: date-time
sequence
required

Position of the message in the conversation’s event sequence.

number
replyToMessageId
required

ID of the message being replied to, if any.

nullable string
nextCursor
required

Pass this cursor to retrieve the next page. Null when no further page is available. When polling events in ascending order, retain the cursor even on empty pages.

nullable string

Example

{
"data": [
{
"id": "evnt_n5p8r2k6m4x9q3v7b1c0dfgh",
"version": 1,
"type": "message.created",
"createdAt": "2026-10-13T09:10:00.000Z",
"workspaceId": "ws_B8kN4pR6xZ2",
"origin": "api",
"actor": {
"role": "apiKey",
"id": "key_pL6rT3mN9xB2vQ8k_B8kN4pR6xZ2"
},
"causationId": "op_r4k7m2p9x6n8q3v5b1c0dfgh",
"data": {
"message": {
"id": "msg_h7m4k2r9p6x8n3q5v1z0bcdf",
"conversationId": "conv_B8kN4pR6xZ2_kR7mP3xB9nQ2vL5z",
"kind": "message",
"content": "Hi Sam, your workspace is ready. Can I help you get started?",
"sender": {
"id": "acc_tQ8nL4zR6mB2xP7k",
"role": "operator"
},
"createdAt": "2026-10-13T09:10:00.000Z",
"sequence": 1,
"replyToMessageId": null
}
}
}
],
"nextCursor": null
}