---
title: "Read history"
method: GET
path: "/v1/replica/{id}/history"
tags: ["Replica"]
---

# Read history

`GET /v1/replica/{id}/history`

## Request

- Base URL: `https://api.replicas.dev`
- URL: `https://api.replicas.dev/v1/replica/{id}/history`
- Auth: HTTP bearer

Reads history from the newest event. Omit `limit` for everything. To page back, pass the previous `before_cursor` until it is `null`. Sleeping and archived replicas return retained history without waking. Returns `409` when a suspended replica has no retained history.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `chat_id` string
- `limit` integer
- `before_event` integer
- `before_turn` integer
- `before_cursor` string

## Headers

- `X-Replicas-Api-Version` '2026-10-07'

## Response `200`

Successful response

- ReadReplicaHistoryResponse: Response containing paginated conversation history
  - `thread_id` string, nullable, required: Thread/session ID
  - `events` HistoryEvent[], required: History events (paginated from the end)
    - `timestamp` string, date-time, required: When the event occurred
    - `type` string, required: Type of event (e.g., 'claude-user', 'claude-assistant', 'codex-user', 'cursor-assistant')
    - `payload` union, required: A raw event from the coding agent, streamed as part of `chat.turn.delta` events. The shape depends on the coding agent provider. Use the `type` field to discriminate between Claude, Codex, Cursor, Muse Server Protocol, Opencode, and Pi events.
      - ClaudeAgentEvent: A streaming event from the Claude Code agent. The `type` field is prefixed with `claude-` followed by the SDK message type.
        - `timestamp` string, date-time, required: When the event occurred
        - `type` 'claude-assistant' | 'claude-user' | 'claude-result' | 'claude-system', required: Claude event type. `claude-assistant` contains model output (text, thinking, tool use). `claude-user` contains tool results. `claude-result` signals turn completion or errors. `claude-system` contains system-level messages.
        - `payload` ClaudeEventPayload, required: Payload of a Claude Code agent event, wrapping the Claude SDK message.
          - `type` string: Original SDK message type (e.g. `assistant`, `user`, `result`)
          - `subtype` string: Present on `claude-result` events; `success` indicates a clean turn completion. Any other value (e.g. `error`) signals a failed turn even when `is_error` is false.
          - `parent_tool_use_id` string, nullable: If this message is the result of a sub-agent tool call, the parent tool_use ID
          - `message` ClaudeMessage: A Claude SDK message containing an array of content blocks.
            - `content` ClaudeContentBlock[]: Ordered list of content blocks produced or consumed by the model.
              - …
          - `is_error` boolean: Present on `claude-result` events; true if the turn ended with an error
          - `errors` string[]: Array of error messages, present on `claude-result` events when `is_error` is true
      - CodexAgentEvent: A streaming event from the Codex CLI agent. Uses either `event_msg` for high-level messages or `response_item` for structured response items.
        - `timestamp` string, date-time, required: When the event occurred
        - `type` 'event_msg' | 'response_item', required: `event_msg` carries high-level messages (user input, reasoning). `response_item` carries structured responses (assistant messages, function calls, tool calls).
        - `payload` union, required: Payload of a Codex CLI agent event. Shape depends on the parent event `type`.
          - CodexEventMsgPayload: Payload for `event_msg` events — high-level user or reasoning messages.
            - `type` 'user_message' | 'agent_reasoning', required: `user_message` for user input, `agent_reasoning` for the agent's chain-of-thought
            - `message` string: User message text (present when type is `user_message`)
            - `text` string: Reasoning text (present when type is `agent_reasoning`)
          - union: Payload for `response_item` events — structured items from the Codex response stream.
            - object: A text message from the Codex agent.
              - …
            - object: A function call by the Codex agent (shell commands, plan updates).
              - …
            - object: Output from a previously invoked function call.
              - …
            - object: A custom tool invocation (e.g. `apply_patch` for file edits).
              - …
            - object: Output from a custom tool call.
              - …
      - CursorAgentEvent: A streaming event from the Cursor agent. Cursor events are normalized with a `cursor-` prefixed type and a provider payload.
        - `timestamp` string, date-time, required: When the event occurred
        - `type` 'cursor-assistant' | 'cursor-thinking' | 'cursor-tool_call' | 'cursor-task' | 'cursor-status' | 'cursor-error', required: Cursor event type. `cursor-assistant` contains model output, `cursor-thinking` contains reasoning text, `cursor-tool_call` contains tool progress/results, `cursor-task` contains task updates, `cursor-status` contains run status, and `cursor-error` contains failure details.
        - `payload` object, required: Cursor event payload. Shape depends on the parent event `type`; Cursor payload sub-shapes are not yet formally specified.
      - MuseAgentEvent: A streaming event from Muse Code over Muse Server Protocol.
        - `timestamp` string, date-time, required: When the event occurred
        - `type` string, required: Muse event type. Item events carry assistant, reasoning, and tool updates; session events report usage; turn completion and error events describe terminal state.
        - `payload` object, required: Muse event payload. Shape depends on the parent event type.
      - OpencodeAgentEvent: A streaming event from the Opencode agent. Opencode events are normalized with an `opencode-` prefixed type and an open provider payload.
        - `timestamp` string, date-time, required: When the event occurred
        - `type` string, required: Opencode event type. Common values include `opencode-message.updated`, `opencode-session.idle`, `opencode-error`, and `opencode-part-*` events.
        - `payload` object, required: Opencode event payload. Shape depends on the parent event `type`; Opencode payload sub-shapes are not yet formally specified.
      - PiAgentEvent: A streaming event from the Pi coding agent. Pi events expose session lifecycle, text and reasoning updates, tool execution, and errors.
        - `timestamp` string, date-time, required: When the event occurred
        - `type` string, required: Pi event type. Common values include pi-message_update, pi-tool_execution_start, pi-tool_execution_update, pi-tool_execution_end, and pi-error.
        - `payload` object, required: Pi event payload. Shape depends on the parent event type.
  - `removed_message_ids` string[]: IDs of canceled queued messages omitted from the history
  - `events_start_index` integer: Index of the first returned event within the full history. Pass it back as `before_event` to fetch the preceding page. Absent when the full history was returned.
  - `turns_start_index` integer: Index of the first returned Codex transcript turn, used with `before_turn`. Present only when the response includes `codex_asp_transcript`.
  - `before_cursor` string, nullable: Opaque cursor for the next earlier page of events and Codex turns. Null when no earlier page exists.
  - `total` integer, required: Total number of events when known; otherwise the number of events in this page
  - `has_more` boolean, required: Whether earlier events exist before this page
  - `coding_agent` 'claude' | 'codex' | 'cursor' | 'muse' | 'opencode' | 'pi' | 'null', nullable: Currently active coding agent
  - `waking` boolean, nullable: Whether the workspace was just woken from a sleeping state. Retry in 30-90 seconds.
  - `codex_asp_transcript` object, nullable: Native Codex ASP transcript when available
  - `senders` ChatMessageSender[]: Who sent each user message, for workspaces shared by several people.
    - `message_id` string: Identifier of the user message associated with this sender.
    - `sender_user_id` string, required: Identifier of the user who sent the message.
    - `sender_email` string, required: Email of the user who sent the message.
    - `recorded_at` string, date-time, required: When the sender was recorded by the engine.

## Other responses

- `400`: Bad request - Missing or invalid parameters
- `401`: Unauthorized - Invalid or missing API key
- `404`: Resource not found
- `500`: Internal server error
- `502`: Bad gateway - The workspace is unreachable or returned an invalid response

---

[API](https://skmtc.dev/replicas/apis/replicas-api.md) - [All operations](https://skmtc.dev/replicas/apis/replicas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/replicas/apis/replicas-api/revisions/2703ac1c9cb7?raw)