List Messages

Retrieve all messages in a session

GET /v1/sessions//messages

List all messages in a session, including user messages, agent responses, and tool results.

Path Parameters

session_id · string · required

The unique identifier of the session

Response

Returns a non-paginated list of all messages in the session.

data · array

Array of message objects

data[].id · string

Message identifier (UUID v7)

data[].role · string

Message role: user, agent, or tool

data[].content · array

Array of content parts. Can include text, tool calls, and tool results.

data[].created_at · string

ISO 8601 timestamp

data[].controls · object

Optional control parameters (present on user messages if provided)

data[].metadata · object

Optional message metadata

total · integer

Total number of messages

Example Request

curl https://api.everruns.com/v1/sessions/{session_id}/messages \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "data": [
    {
      "id": "01937abc-def0-7000-8000-000000000001",
      "role": "user",
      "content": [
        { "type": "text", "text": "What is the weather in Tokyo?" }
      ],
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "01937abc-def0-7000-8000-000000000002",
      "role": "agent",
      "content": [
        { "type": "text", "text": "I'll check the weather for you." },
        {
          "type": "tool_call",
          "id": "call_123",
          "name": "get_weather",
          "arguments": { "city": "Tokyo" }
        }
      ],
      "created_at": "2024-01-15T10:30:01.000Z"
    },
    {
      "id": "01937abc-def0-7000-8000-000000000003",
      "role": "tool",
      "content": [
        {
          "type": "tool_result",
          "tool_call_id": "call_123",
          "content": [
            { "type": "text", "text": "Temperature: 22C, Sunny" }
          ]
        }
      ],
      "created_at": "2024-01-15T10:30:02.000Z"
    },
    {
      "id": "01937abc-def0-7000-8000-000000000004",
      "role": "agent",
      "content": [
        { "type": "text", "text": "The current weather in Tokyo is sunny with a temperature of 22°C." }
      ],
      "created_at": "2024-01-15T10:30:03.000Z"
    }
  ],
  "total": 4
}

Message Reconstruction

Messages are reconstructed from events. The following event types contribute to the message list:

Event Type	Role	Content Source
input.message	user	data.message.content
output.message.completed	agent	data.message.content (may include tool calls)
tool.completed	tool	data.result (tool execution results)

Content Types

Text Content

{ "type": "text", "text": "Message text" }

Image File Content

{
  "type": "image_file",
  "image_id": "01933b5a-...",
  "filename": "photo.png"
}

Tool Call Content

{
  "type": "tool_call",
  "id": "call_123",
  "name": "get_weather",
  "arguments": { "city": "Tokyo" }
}

Tool Result Content

{
  "type": "tool_result",
  "tool_call_id": "call_123",
  "content": [
    { "type": "text", "text": "Result data" }
  ]
}

Error Responses

error · string

Error message

status · integer

HTTP status code

Common Errors

• 404 Not Found: Session does not exist
• 500 Internal Server Error: Server error during retrieval