---
title: "Get session messages"
method: GET
path: "/api/session/{sessionID}/message"
tags: ["session"]
---

# Get session messages

`GET /api/session/{sessionID}/message`

## Request

- Base URL: `https://opencode.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://opencode.ai/api/session/{sessionID}/message`
- Auth: none required

Retrieve projected messages for a session, optionally filtered by type. Items keep the requested order across pages; use cursor.next or cursor.previous to move through the ordered timeline, passing the same type filter on each page.

## Path parameters

- `sessionID` string, required

## Query parameters

- `limit` string, nullable: Maximum number of messages to return. When omitted, the endpoint returns its default page size.
- `order` 'asc' | 'desc', nullable: Message order for the first page. Use desc for newest first or asc for oldest first.
- `cursor` string, nullable: Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response. Do not combine with order.
- `type` 'agent-switched' | 'model-switched' | 'location-switched' | 'user' | 'synthetic' | 'system' | 'skill' | 'shell' | 'assistant' | 'compaction' | 'idle', nullable: Filter by message type before pagination. When omitted, all message types are returned. Pass the same type when following cursors.

## Response `200`

SessionMessagesResponse

- SessionMessagesResponse
  - `data` SessionMessageInfo[], required
    - union
      - SessionMessageAgentSelected
        - `id` string, required
        - `metadata` object
        - `time` object, required
          - `created` number, required
        - `type` 'agent-switched', required
        - `agent` string, required
        - `previous` string
      - SessionMessageModelSelected
        - `id` string, required
        - `metadata` object
        - `time` object, required
          - `created` number, required
        - `type` 'model-switched', required
        - `model` ModelRef, required
          - `id` string, required
          - `providerID` string, required
          - `variant` string
        - `previous` ModelRef
          - `id` string, required
          - `providerID` string, required
          - `variant` string
      - SessionMessageLocationSwitched
        - `id` string, required
        - `metadata` object
        - `time` object, required
          - `created` number, required
        - `type` 'location-switched', required
        - `projectID` string
        - `subpath` string
        - `location` LocationPublicRef, required
          - `directory` string, required
        - `previous` object, nullable
          - `location` LocationPublicRef, required
            - `directory` string, required
          - `projectID` string
          - `subpath` string
      - SessionMessageUser
        - `id` string, required
        - `metadata` object
        - `time` object, required
          - `created` number, required
        - `text` string, required
        - `files` PromptFileAttachment[]
          - `data` string, required
          - `mime` string, required
          - `source` union, required
            - object
              - …
            - object
              - …
          - `name` string
          - `description` string
          - `mention` PromptMention
            - `start` number, required
            - `end` number, required
            - `text` string, required
        - `agents` PromptAgentAttachment[]
          - `name` string, required
          - `mention` PromptMention
            - `start` number, required
            - `end` number, required
            - `text` string, required
        - `skills` PromptSkillAttachment[]
          - `id` string, required
          - `name` string, required
          - `text` string
          - `mention` PromptMention
            - `start` number, required
            - `end` number, required
            - `text` string, required
        - `type` 'user', required
      - SessionMessageSynthetic
        - `id` string, required
        - `metadata` object
        - `time` object, required
          - `created` number, required
        - `text` string, required
        - `description` string
        - `type` 'synthetic', required
      - SessionMessageSystem
        - `id` string, required
        - `metadata` object
        - `time` object, required
          - `created` number, required
        - `type` 'system', required
        - `text` string, required
        - `description` string
      - SessionMessageSkill
        - `id` string, required
        - `metadata` object
        - `time` object, required
          - `created` number, required
        - `type` 'skill', required
        - `skill` string, required
        - `name` string, required
        - `text` string, required
      - SessionMessageShell
        - `id` string, required
        - `metadata` object
        - `time` object, required
          - `created` number, required
          - `completed` number
        - `type` 'shell', required
        - `shellID` string, required
        - `command` string, required
        - `status` 'running' | 'exited' | 'timeout' | 'killed', required
        - `exit` union
          - number
          - 'Infinity' | '-Infinity' | 'NaN'
        - `output` object
          - `output` string, required
          - `cursor` integer, required
          - `size` integer, required
          - `truncated` boolean, required
      - SessionMessageAssistant
        - `id` string, required
        - `metadata` object
        - `time` object, required
          - `created` number, required
          - `streamed` number
          - `completed` number
        - `type` 'assistant', required
        - `agent` string, required
        - `model` ModelRef, required
          - `id` string, required
          - `providerID` string, required
          - `variant` string
        - `content` union[], required
          - union
            - SessionMessageAssistantText
              - …
            - SessionMessageAssistantReasoning
              - …
            - SessionMessageAssistantTool
              - …
        - `snapshot` object
          - `start` string
          - `end` string
          - `files` RelativePath[]
        - `finish` 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'unknown'
        - `rawFinish` string
        - `native` SessionMessageNative3
        - `cost` number
        - `tokens` TokenUsageInfo
          - `input` number, required
          - `output` number, required
          - `reasoning` number, required
          - `cache` object, required
            - `read` number, required
            - `write` number, required
        - `error` SessionStructuredError
          - `type` string, required
          - `message` string, required
          - `status` integer
          - `response` object
            - `body` string, required
          - `retryAfterMs` integer
        - `retry` SessionMessageAssistantRetry
          - `attempt` integer, required
          - `at` number, required
          - `error` SessionStructuredError, required
            - `type` string, required
            - `message` string, required
            - `status` integer
            - `response` object
              - …
            - `retryAfterMs` integer
      - union
        - SessionMessageCompactionRunning
          - `type` 'compaction', required
          - `id` string, required
          - `metadata` object
          - `time` object, required
            - `created` number, required
          - `status` 'running', required
          - `reason` 'auto' | 'manual', required
          - `summary` string, required
        - SessionMessageCompactionCompleted
          - `type` 'compaction', required
          - `id` string, required
          - `metadata` object
          - `time` object, required
            - `created` number, required
          - `status` 'completed', required
          - `reason` 'auto' | 'manual', required
          - `model` ModelRef
            - `id` string, required
            - `providerID` string, required
            - `variant` string
          - `native` SessionMessageNative4
          - `summary` string, required
          - `cost` number
          - `tokens` TokenUsageInfo
            - `input` number, required
            - `output` number, required
            - `reasoning` number, required
            - `cache` object, required
              - …
        - SessionMessageCompactionFailed
          - `type` 'compaction', required
          - `id` string, required
          - `metadata` object
          - `time` object, required
            - `created` number, required
          - `status` 'failed', required
          - `reason` 'auto' | 'manual', required
          - `error` SessionStructuredError, required
            - `type` string, required
            - `message` string, required
            - `status` integer
            - `response` object
              - …
            - `retryAfterMs` integer
          - `cost` number
          - `tokens` TokenUsageInfo
            - `input` number, required
            - `output` number, required
            - `reasoning` number, required
            - `cache` object, required
              - …
      - SessionMessageIdle
        - `id` string, required
        - `metadata` object
        - `time` object, required
          - `created` number, required
        - `type` 'idle', required
        - `outcome` 'succeeded' | 'failed' | 'interrupted', required
        - `error` SessionStructuredError
          - `type` string, required
          - `message` string, required
          - `status` integer
          - `response` object
            - `body` string, required
          - `retryAfterMs` integer
  - `cursor` object, required
    - `previous` string, nullable
    - `next` string, nullable

## Other responses

- `400`: InvalidCursorError | InvalidRequestError
- `401`: UnauthorizedError
- `404`: SessionNotFoundError
- `500`: UnknownError

## Changes

> 50 revisions in range; 1 not diffed.

- **2026-10-24** `1c30ec162e7f`: 1 warning
  - removed the optional property `data/items/anyOf[#/components/schemas/Session.Message.Assistant]/allowance` from the response with the `200` status
- **2026-10-24** `231ec98d2d97`: 1 info
  - added the optional property `data/items/anyOf[#/components/schemas/Session.Message.Assistant]/allowance` to the response with the `200` status
- **2026-10-21** `7709eeb4cfb8`: 5 info
  - added the optional property `data/items/anyOf[#/components/schemas/Session.Message.Assistant]/content/items/anyOf[#/components/schemas/Session.Message.Assistant.Tool]/state/anyOf[#/components/schemas/Session.Message.ToolState.Error]/error/retryAfterMs` to the response with the `200` status
  - added the optional property `data/items/anyOf[#/components/schemas/Session.Message.Assistant]/error/retryAfterMs` to the response with the `200` status
  - added the optional property `data/items/anyOf[#/components/schemas/Session.Message.Assistant]/retry/error/retryAfterMs` to the response with the `200` status
  - added the optional property `data/items/anyOf[#/components/schemas/Session.Message.Compaction]/anyOf[#/components/schemas/Session.Message.Compaction.Failed]/error/retryAfterMs` to the response with the `200` status
  - …1 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/kaaass/apis/opencode/changes/api/session/:sessionID/message/get.md)

---

[API](https://skmtc.dev/kaaass/apis/opencode.md) - [All operations](https://skmtc.dev/kaaass/apis/opencode/llms.txt) - [OpenAPI document](https://skmtc.dev/kaaass/apis/opencode/revisions/4e083d954707?raw)