Session Messages

Session messages represent the MCP protocol messages exchanged during a session. This read-only resource provides visibility into the communication between clients and providers.

Session Messages object

Attributes

object

String

String representing the object's type

id

String

Unique session message identifier

type

String

Message type

status

String

Message status

source

String

Message source

session_id

String

Parent session ID

session_provider_id

StringNullable

Session provider ID

connection_id

StringNullable

Connection ID

provider_run_id

StringNullable

Provider run ID

hierarchy

Object

Message hierarchy information

transport

Object

Transport information

input

ObjectNullable

Input message data

output

ObjectNullable

Output message data

tool_call

ObjectNullable

sender_participant

Object

responder_participant

ObjectNullable

error

ObjectNullable

created_at

Date

Timestamp when created

{
  "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"
}

List session messages

Returns a paginated list of messages 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 message type(s)

source

UnionOptional

Filter by message source(s)

hierarchy

UnionOptional

Filter by message hierarchy

id

UnionOptional

Filter by message 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)

error_id

UnionOptional

Filter by error ID(s)

participant_id

UnionOptional

Filter by participant ID(s)

parent_message_id

UnionOptional

Filter by parent message ID(s)

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

Get session message

Retrieves a specific message from a session.

URL Parameters

session_message_id

String

The unique identifier for the session_message

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