Session Events

Session events represent significant occurrences during a session, such as errors or state changes. This read-only resource provides visibility into session activity.

Session Events object

Attributes

object

String

String representing the object's type

id

String

Unique session event identifier

type

StringNullable

Event type

name

StringNullable

Event name

message

StringNullable

Event message

data

ObjectNullable

Event data

metadata

ObjectNullable

Custom key-value pairs

session_id

String

Parent session ID

session_provider_id

StringNullable

Session provider ID

provider_run_id

StringNullable

Provider run ID

created_at

Date

Timestamp when created

{
  "object": "session.event",
  "id": "sev_8hJkLmNpQrStUvWx",
  "type": "error",
  "name": "tool_execution_failed",
  "message": "Tool execution timed out",
  "data": {
    "tool_name": "search_files",
    "error_code": "TIMEOUT"
  },
  "metadata": {
    "severity": "high"
  },
  "session_id": "ses_4dEfGhJkLmNpQrSt",
  "session_provider_id": "spr_3cDeFgHjKlMnPqRs",
  "provider_run_id": "prn_8hJkLmNpQrStUvWx",
  "created_at": "2025-09-15T10:30:00.000Z"
}

List session events

Returns a paginated list of events for a session.

URL Parameters

session_id

String

The unique identifier for the session

Query Parameters

limit

NumberOptional

Maximum number of items to return (1-100)

after

StringOptional

Return items after this ID

before

StringOptional

Return items before this ID

cursor

StringOptional

Pagination cursor from a previous response

order

EnumOptional

Sort order for results

type

StringOptional

Filter by event type

session_provider_id

UnionOptional

Filter by session provider ID(s)

provider_run_id

UnionOptional

Filter by provider run ID(s)

GEThttp://api.metorial.com/sessions/:session_id/events
curl -X GET "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY/events" \
  -H "Authorization: Bearer metorial_sk_..."

Get session event

Retrieves a specific event from a session.

URL Parameters

session_id

String

The unique identifier for the session

session_event_id

String

The unique identifier for the session_event

GEThttp://api.metorial.com/sessions/:session_id/events/:session_event_id
curl -X GET "https://api.metorial.com/sessions/ses_Rm4Mnheq2bfEPhBhP7SY/events/ses_Rm4Mnheq2bfEPhBhP7SY" \
  -H "Authorization: Bearer metorial_sk_..."