> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elizaos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Session Messages

> Retrieve messages from a conversation session with cursor-based pagination

<Note>
  Messages are returned in reverse chronological order (newest first) by default. Use the cursor values for efficient pagination through large conversation histories.
</Note>

## Path Parameters

<ParamField path="sessionId" type="string" required>
  The unique identifier of the session
</ParamField>

## Query Parameters

<ParamField query="limit" type="number">
  Number of messages to retrieve (1-100). Default: 50
</ParamField>

<ParamField query="before" type="number">
  Timestamp to get messages before (for older messages)
</ParamField>

<ParamField query="after" type="number">
  Timestamp to get messages after (for newer messages)
</ParamField>

## Response

<ResponseField name="messages" type="array">
  Array of messages in the conversation

  <Expandable title="Message Properties">
    <ResponseField name="id" type="string">
      Unique message identifier
    </ResponseField>

    <ResponseField name="content" type="string">
      Message content
    </ResponseField>

    <ResponseField name="authorId" type="string">
      UUID of the message author
    </ResponseField>

    <ResponseField name="isAgent" type="boolean">
      Whether the message is from the agent
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO timestamp of message creation
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Message metadata including agent thoughts and actions
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Whether more messages are available
</ResponseField>

<ResponseField name="cursors" type="object">
  Pagination cursors for fetching additional messages

  <Expandable title="Cursor Properties">
    <ResponseField name="before" type="number">
      Use this timestamp to get older messages
    </ResponseField>

    <ResponseField name="after" type="number">
      Use this timestamp to get newer messages
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Usage

<CodeGroup>
  ```javascript Initial Fetch theme={null}
  // Get the most recent 20 messages
  const response = await fetch(
    '/api/messaging/sessions/abc-123/messages?limit=20'
  );

  const { messages, hasMore, cursors } = await response.json();
  ```

  ```javascript Pagination - Older theme={null}
  // Get older messages using the 'before' cursor
  const olderMessages = await fetch(
    `/api/messaging/sessions/abc-123/messages?before=${cursors.before}&limit=20`
  );
  ```

  ```javascript Pagination - Newer theme={null}
  // Get newer messages using the 'after' cursor
  const newerMessages = await fetch(
    `/api/messaging/sessions/abc-123/messages?after=${cursors.after}&limit=20`
  );
  ```

  ```javascript Range Query theme={null}
  // Get messages between two timestamps
  const rangeMessages = await fetch(
    `/api/messaging/sessions/abc-123/messages?after=1704614400000&before=1704618000000`
  );
  ```
</CodeGroup>


## OpenAPI

````yaml get /api/messaging/sessions/{sessionId}/messages
openapi: 3.1.0
info:
  title: Eliza OS API
  description: >-
    API documentation for Eliza OS v1.2.0 - A flexible and scalable AI agent
    framework.


    This API is designed to be used with a locally running Eliza instance.
    Endpoints allow for creating,

    managing, and interacting with AI agents through a REST interface.


    The API is organized into the following domains:

    - **System**: System-wide operations and environment management

    - **Agents**: Agent lifecycle and management operations

    - **Memory**: Agent memory and room management

    - **Messaging**: Message handling, channels, and servers

    - **Audio**: Audio processing and speech synthesis

    - **Media**: File upload and media management

    - **TEE**: Trusted Execution Environment operations

    - **WebSocket**: Real-time communication via Socket.IO
  version: 1.2.0
  contact:
    name: Eliza OS Community
    url: https://github.com/elizaos/eliza
servers:
  - url: http://localhost:3000
    description: Local development server
security: []
tags:
  - name: system
    description: System-wide operations and environment management
  - name: agents
    description: Operations for managing AI agents
  - name: memory
    description: Operations for managing agent memories
  - name: rooms
    description: Operations for managing rooms
  - name: messaging
    description: Operations for messages, channels, and servers
  - name: audio
    description: Operations for speech and audio processing
  - name: media
    description: Operations for file uploads and media management
  - name: logs
    description: Operations for accessing system and agent logs
  - name: tee
    description: Trusted Execution Environment operations
  - name: websocket
    description: Real-time WebSocket communication
paths:
  /api/messaging/sessions/{sessionId}/messages:
    get:
      tags:
        - messaging
      summary: Get session messages
      description: Retrieve messages from a session with pagination support
      operationId: getSessionMessages
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
          description: ID of the session
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 100
          description: Maximum number of messages to return
        - name: before
          in: query
          schema:
            type: string
            format: date-time
          description: Get messages before this timestamp
        - name: after
          in: query
          schema:
            type: string
            format: date-time
          description: Get messages after this timestamp
      responses:
        '200':
          description: Messages retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        content:
                          type: string
                        authorId:
                          type: string
                          format: uuid
                        isAgent:
                          type: boolean
                        createdAt:
                          type: string
                          format: date-time
                        metadata:
                          type: object
                  hasMore:
                    type: boolean
                    description: Whether there are more messages available
                  cursors:
                    type: object
                    description: Pagination cursors for fetching additional messages
                    properties:
                      before:
                        type: integer
                        description: Use this timestamp to get older messages
                      after:
                        type: integer
                        description: Use this timestamp to get newer messages
        '404':
          description: Session not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Session has expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code
            message:
              type: string
              description: Error message
            details:
              type: string
              description: Detailed error information

````