MetorialDocs

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.

The Session Message object

session_message.json
{
  "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",
    "parent_message_id": "example_parent_message_id",
    "child_message_ids": [
      "example_child_message_ids"
    ]
  },
  "transport": {
    "object": "session.message.transport",
    "type": "mcp",
    "mcp": {
      "object": "session.message.transport.mcp",
      "id": "example_Option 1",
      "protocol_version": "example_protocol_version",
      "transport": "unknown"
    },
    "tool_call": {
      "object": "session.message.transport.tool_call",
      "id": "example_id"
    }
  },
  "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",
    "sender_participant": {
      "object": "session.participant",
      "id": "spt_5eFgHjKlMnPqRsTu",
      "type": "unknown",
      "identifier": "claude-desktop",
      "name": "Claude Desktop",
      "data": {
        "identifier": "claude-desktop",
        "name": "Claude Desktop"
      },
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "connection_type": "mcp",
      "agent_id": "example_agent_id",
      "agent_instance_id": "example_agent_instance_id",
      "identity_actor_id": "example_identity_actor_id",
      "identity_id": "example_identity_id",
      "agent_actor_id": "example_agent_actor_id",
      "agent_client_id": "example_agent_client_id",
      "consumer_id": "example_consumer_id",
      "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": {
        "identifier": "claude-desktop",
        "name": "Claude Desktop"
      },
      "provider_id": "pro_5gHjKlMnPqRsTuVw",
      "connection_type": "mcp",
      "agent_id": "example_agent_id",
      "agent_instance_id": "example_agent_instance_id",
      "identity_actor_id": "example_identity_actor_id",
      "identity_id": "example_identity_id",
      "agent_actor_id": "example_agent_actor_id",
      "agent_client_id": "example_agent_client_id",
      "consumer_id": "example_consumer_id",
      "created_at": "2025-09-15T10:30:00.000Z"
    },
    "tool": {
      "object": "provider.tool",
      "id": "pto_5jKlMnPqRsTuVwXy",
      "key": "create_issue",
      "name": "Create Issue",
      "description": "Creates a new issue in a GitHub repository",
      "capabilities": {},
      "constraints": [
        "example_constraints"
      ],
      "instructions": [
        "example_instructions"
      ],
      "input_schema": {
        "type": "json_schema",
        "schema": {}
      },
      "output_schema": {
        "type": "json_schema",
        "schema": {}
      },
      "tags": {
        "destructive": false,
        "read_only": false
      },
      "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": {},
      "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": {
      "identifier": "claude-desktop",
      "name": "Claude Desktop"
    },
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "connection_type": "mcp",
    "agent_id": "example_agent_id",
    "agent_instance_id": "example_agent_instance_id",
    "identity_actor_id": "example_identity_actor_id",
    "identity_id": "example_identity_id",
    "agent_actor_id": "example_agent_actor_id",
    "agent_client_id": "example_agent_client_id",
    "consumer_id": "example_consumer_id",
    "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": {
      "identifier": "claude-desktop",
      "name": "Claude Desktop"
    },
    "provider_id": "pro_5gHjKlMnPqRsTuVw",
    "connection_type": "mcp",
    "agent_id": "example_agent_id",
    "agent_instance_id": "example_agent_instance_id",
    "identity_actor_id": "example_identity_actor_id",
    "identity_id": "example_identity_id",
    "agent_actor_id": "example_agent_actor_id",
    "agent_client_id": "example_agent_client_id",
    "consumer_id": "example_consumer_id",
    "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": {},
    "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"
}
object"session.message"required
idstringrequired
type"tool_call" | "mcp_control" | "mcp_message" | "unknown"required
status"waiting_for_response" | "failed" | "succeeded"required
source"client" | "provider"required
session_idstringrequired
session_provider_idstringrequirednullable
connection_idstringrequirednullable
provider_run_idstringrequirednullable
inputRecord<string, any>requirednullable
outputRecord<string, any>requirednullable
created_atdaterequired

Endpoints

List session messages

GET/session-messages

Returns a paginated list of messages for a session.

Query parameters

type"unknown" | "tool_call" | "mcp_control" | "mcp_message" or "unknown" | "tool_call" | "mcp_control" | "mcp_message"[]optional

Filter by message type(s)

source"provider" | "client" or "provider" | "client"[]optional

Filter by message source(s)

hierarchy"child" | "parent" or "child" | "parent"[]optional

Filter by message hierarchy

idstring or string[]optional

Filter by message ID(s)

session_idstring or string[]optional

Filter by session ID(s)

session_provider_idstring or string[]optional

Filter by session provider ID(s)

session_connection_idstring or string[]optional

Filter by session connection ID(s)

provider_run_idstring or string[]optional

Filter by provider run ID(s)

error_idstring or string[]optional

Filter by error ID(s)

participant_idstring or string[]optional

Filter by participant ID(s)

parent_message_idstring or string[]optional

Filter by parent message ID(s)

Example request

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

Get session message

GET/session-messages/:session_message_id

Retrieves a specific message from a session.

Path parameters

session_message_idstringrequired

The unique identifier for the session_message

Example request

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