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

String

Event type

session_id

String

Parent session ID

connection

ObjectNullable

provider_run

ObjectNullable

message

ObjectNullable

error

ObjectNullable

warning

ObjectNullable

created_at

Date

Timestamp when created

{
  "object": "session.event",
  "id": "sev_8hJkLmNpQrStUvWx",
  "type": "connection.opened",
  "session_id": "ses_4dEfGhJkLmNpQrSt",
  "connection": {
    "object": "session.connection",
    "id": "scn_8hJkLmNpQrStUvWx",
    "status": "active",
    "connection_state": "connected",
    "transport": "mcp",
    "usage": {},
    "mcp": {
      "capabilities": {},
      "protocol_version": "2024-11-05",
      "transport": "sse"
    },
    "session_id": "ses_4dEfGhJkLmNpQrSt",
    "participant": {
      "object": "session.participant",
      "id": "spt_5eFgHjKlMnPqRsTu",
      "type": "unknown",
      "identifier": "claude-desktop",
      "name": "Claude Desktop",
      "data": {
        "client_version": "1.2.3"
      },
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "created_at": "2025-09-15T10:30:00.000Z"
    },
    "created_at": "2025-09-15T10:30:00.000Z",
    "last_message_at": "2025-09-15T10:30:00.000Z",
    "last_active_at": "2025-09-15T10:30:00.000Z"
  },
  "provider_run": {
    "object": "session.provider_run",
    "id": "prn_8hJkLmNpQrStUvWx",
    "status": "running",
    "session_id": "ses_4dEfGhJkLmNpQrSt",
    "session_provider_id": "spr_3cDeFgHjKlMnPqRs",
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "connection_id": "scn_8hJkLmNpQrStUvWx",
    "completed_at": "2025-09-15T10:30:05.000Z",
    "created_at": "2025-09-15T10:30:00.000Z",
    "updated_at": "2026-01-10T14:45:00.000Z"
  },
  "message": {
    "object": "session.message",
    "id": "smg_8hJkLmNpQrStUvWx",
    "type": "tool_call",
    "status": "waiting_for_response",
    "source": "client",
    "session_id": "ses_4dEfGhJkLmNpQrSt",
    "session_provider_id": "spr_3cDeFgHjKlMnPqRs",
    "connection_id": "scn_2bCdEfGhJkLmNpQr",
    "provider_run_id": "prn_8hJkLmNpQrStUvWx",
    "hierarchy": {
      "object": "session.message.hierarchy",
      "type": "child"
    },
    "transport": {
      "object": "session.message.transport",
      "type": "mcp",
      "mcp": {
        "object": "session.message.transport#mcp",
        "transport": "unknown"
      },
      "tool_call": {
        "object": "session.message.transport#tool_call"
      }
    },
    "input": {},
    "output": {},
    "tool_call": {
      "object": "session.tool_call",
      "id": "tcl_8hJkLmNpQrStUvWx",
      "tool_key": "create_issue",
      "type": "tool_call",
      "status": "waiting_for_response",
      "source": "client",
      "transport": "tool_call",
      "session_id": "ses_4dEfGhJkLmNpQrSt",
      "message_id": "smg_3cDeFgHjKlMnPqRs",
      "session_provider_id": "spr_3cDeFgHjKlMnPqRs",
      "connection_id": "scn_2bCdEfGhJkLmNpQr",
      "provider_run_id": "prn_8hJkLmNpQrStUvWx",
      "tool": {
        "object": "provider.tool",
        "id": "pto_5jKlMnPqRsTuVwXy",
        "key": "create_issue",
        "name": "Create Issue",
        "description": "Creates a new issue in a GitHub repository",
        "capabilities": {},
        "input_schema": {
          "type": "json_schema",
          "schema": {}
        },
        "output_schema": {
          "type": "json_schema",
          "schema": {}
        },
        "tags": {},
        "specification_id": "psp_9gHjKlMnPqRsTuVw",
        "provider_id": "pro_5gHjKlMnPqRsTuVw",
        "created_at": "2025-09-15T10:30:00.000Z",
        "updated_at": "2026-01-10T14:45:00.000Z"
      },
      "error": {
        "object": "session.error",
        "id": "ser_6fGhJkLmNpQrStUv",
        "code": "CONNECTION_TIMEOUT",
        "message": "Connection timed out after 30 seconds",
        "data": {
          "timeout_ms": 30000
        },
        "status": "processing",
        "session_id": "ses_4dEfGhJkLmNpQrSt",
        "provider_run_id": "prn_8hJkLmNpQrStUvWx",
        "connection_id": "scn_8hJkLmNpQrStUvWx",
        "group_id": "seg_7gHjKlMnPqRsTuVw",
        "similar_error_count": 5,
        "created_at": "2025-09-15T10:30:00.000Z"
      },
      "input": {},
      "output": {},
      "created_at": "2025-09-15T10:30:00.000Z"
    },
    "sender_participant": {
      "object": "session.participant",
      "id": "spt_5eFgHjKlMnPqRsTu",
      "type": "unknown",
      "identifier": "claude-desktop",
      "name": "Claude Desktop",
      "data": {
        "client_version": "1.2.3"
      },
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "created_at": "2025-09-15T10:30:00.000Z"
    },
    "responder_participant": {
      "object": "session.participant",
      "id": "spt_5eFgHjKlMnPqRsTu",
      "type": "unknown",
      "identifier": "claude-desktop",
      "name": "Claude Desktop",
      "data": {
        "client_version": "1.2.3"
      },
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "created_at": "2025-09-15T10:30:00.000Z"
    },
    "error": {
      "object": "session.error",
      "id": "ser_6fGhJkLmNpQrStUv",
      "code": "CONNECTION_TIMEOUT",
      "message": "Connection timed out after 30 seconds",
      "data": {
        "timeout_ms": 30000
      },
      "status": "processing",
      "session_id": "ses_4dEfGhJkLmNpQrSt",
      "provider_run_id": "prn_8hJkLmNpQrStUvWx",
      "connection_id": "scn_8hJkLmNpQrStUvWx",
      "group_id": "seg_7gHjKlMnPqRsTuVw",
      "similar_error_count": 5,
      "created_at": "2025-09-15T10:30:00.000Z"
    },
    "created_at": "2025-09-15T10:30:00.000Z"
  },
  "error": {
    "object": "session.error",
    "id": "ser_6fGhJkLmNpQrStUv",
    "code": "CONNECTION_TIMEOUT",
    "message": "Connection timed out after 30 seconds",
    "data": {
      "timeout_ms": 30000
    },
    "status": "processing",
    "session_id": "ses_4dEfGhJkLmNpQrSt",
    "provider_run_id": "prn_8hJkLmNpQrStUvWx",
    "connection_id": "scn_8hJkLmNpQrStUvWx",
    "group_id": "seg_7gHjKlMnPqRsTuVw",
    "similar_error_count": 5,
    "created_at": "2025-09-15T10:30:00.000Z"
  },
  "warning": {
    "object": "session.warning",
    "id": "ser_6fGhJkLmNpQrStUv",
    "code": "CONNECTION_TIMEOUT",
    "message": "Connection timed out after 30 seconds",
    "data": {
      "timeout_ms": 30000
    },
    "session_id": "ses_4dEfGhJkLmNpQrSt",
    "connection_id": "scn_8hJkLmNpQrStUvWx",
    "created_at": "2025-09-15T10:30:00.000Z"
  },
  "created_at": "2025-09-15T10:30:00.000Z"
}

List session events

Returns a paginated list of events for a 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

UnionOptional

Filter by event type(s)

id

UnionOptional

Filter by session event ID(s)

session_id

UnionOptional

Filter by session ID(s)

session_provider_id

UnionOptional

Filter by session provider ID(s)

session_connection_id

UnionOptional

Filter by session connection ID(s)

provider_run_id

UnionOptional

Filter by provider run ID(s)

session_message_id

UnionOptional

Filter by session message ID(s)

session_error_id

UnionOptional

Filter by session error ID(s)

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

Get session event

Retrieves a specific event from a session.

URL Parameters

session_event_id

String

The unique identifier for the session_event

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