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

# Read History

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

Reads the conversation history for a replica with pagination from the end (bottom-up). Optionally filter by chat ID. If the workspace is sleeping or archived, it will be woken and the response will indicate this with `waking: true`. Retry in 30-90 seconds when waking.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `chat_id` string
- `limit` integer
- `offset` integer

## 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, 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.
      - 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.
  - `total` integer, required — Total number of events
  - `has_more` boolean, required — Whether there are more events available
  - `coding_agent` 'claude' | 'codex' | 'cursor' | 'opencode' | 'pi' | 'null', nullable — Currently active coding agent
  - `waking` boolean, nullable — Whether the workspace was just woken from a sleeping or archived state. Retry in 30-90 seconds.
  - `codexAspTranscript` object, nullable — Native Codex ASP transcript when available
  - `senders` ChatMessageSender[] — Sender attribution records for user messages in this chat. In team workspaces, each sendMessage call records the authenticated user; clients can use this to label messages with the actual sender's name instead of "You".
    - `senderUserId` string, required — Identifier of the user who sent the message.
    - `senderEmail` string, required — Email of the user who sent the message.
    - `recordedAt` 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.net/tryreplicas/apis/replica-api.md) · [All operations](https://skmtc.net/tryreplicas/apis/replica-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryreplicas/replica-api/versions/aa3b4c932f7a/schema)