> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryreplicas.com/llms.txt > Use this file to discover all available pages before exploring further. # Read 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. ## OpenAPI ````yaml /openapi.json get /v1/replica/{id}/history openapi: 3.1.0 info: title: Replica API version: 2.0.0 description: >- The Replica API allows you to programmatically manage cloud workspaces for AI agents. Use this API to manage environments (the org-scoped primitive workspaces are created from — including variables, files, skills, MCPs, warm hooks, start hooks, and warm pools), create and manage replicas, send messages, manage chats, stream events, read connected repositories and repository sets, and configure automations. servers: - url: https://api.tryreplicas.com description: Production API security: - apiKey: [] tags: - name: Environments description: >- Manage environments — the primitive that workspaces are created from. Variables, files, skills, MCPs, warm-hooks, and warm-pools are all scoped to an environment. Every organization has a singleton Global environment whose values apply to every workspace. Personal environments are scoped to the authenticated user and can be standalone or source-backed by a team environment. - name: Repository description: >- Read repositories and repository sets connected to your organization. Repositories are the underlying GitHub-connection layer; bind them to an environment to use them in workspaces. - name: Replica description: Manage replicas (workspaces) for AI agents - name: Terminal description: Manage interactive terminal sessions in active workspaces - name: Preview description: Manage public preview URLs for workspace ports - name: Profile description: Read and update the authenticated user's profile - name: Credentials description: >- Manage coding-agent credentials for an organization or the authenticated user - name: Google Search Console description: >- Read Search Console properties, performance, sitemaps, and URL inspection results through a connected Google account - name: Slack description: Connect Slack identities and route threads to Replicas workspaces - name: Linear description: Connect Linear identities to Replicas accounts - name: Automation description: >- Create and manage automations that trigger replicas on a schedule or in response to events - name: Downloads description: Download Replicas applications - name: Analytics description: >- Read aggregated activity and usage metrics for your organization: compute minutes, workspaces created by source, and pull request throughput over a time range. - name: Presence description: >- Read and report ephemeral member presence: who is online, where they are (environment or workspace), and whether they are typing. Presence is backed by short-lived keys rather than the database and broadcast to other members over the events stream. paths: /v1/replica/{id}/history: get: tags: - Replica summary: Read History description: >- 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. operationId: readReplicaHistory parameters: - name: id in: path description: The unique identifier of the replica required: true schema: type: string format: uuid - name: chat_id in: query description: Filter history to a specific chat required: false schema: type: string - name: limit in: query description: Maximum number of events to return required: false schema: type: integer minimum: 1 - name: offset in: query description: Number of events to skip from the end required: false schema: type: integer default: 0 minimum: 0 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ReadReplicaHistoryResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' '502': $ref: '#/components/responses/BadGateway' components: schemas: ReadReplicaHistoryResponse: type: object description: Response containing paginated conversation history properties: thread_id: type: - string - 'null' description: Thread/session ID events: type: array items: $ref: '#/components/schemas/HistoryEvent' description: History events (paginated from the end) total: type: integer description: Total number of events has_more: type: boolean description: Whether there are more events available coding_agent: type: - string - 'null' description: Currently active coding agent enum: - claude - codex - cursor - opencode - pi - null waking: type: - boolean - 'null' description: >- Whether the workspace was just woken from a sleeping or archived state. Retry in 30-90 seconds. codexAspTranscript: type: - object - 'null' description: Native Codex ASP transcript when available senders: type: array items: $ref: '#/components/schemas/ChatMessageSender' description: >- 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". required: - thread_id - events - total - has_more HistoryEvent: type: object description: A conversation history event properties: timestamp: type: string format: date-time description: When the event occurred type: type: string description: >- Type of event (e.g., 'claude-user', 'claude-assistant', 'codex-user', 'cursor-assistant') payload: $ref: '#/components/schemas/AgentEvent' description: Event payload — see AgentEvent for the full discriminated schema required: - timestamp - type - payload ChatMessageSender: type: object description: >- Records who sent a user message in a chat. Server-recorded from the authenticated user at send time. properties: senderUserId: type: string description: Identifier of the user who sent the message. senderEmail: type: string description: Email of the user who sent the message. recordedAt: type: string format: date-time description: When the sender was recorded by the engine. required: - senderUserId - senderEmail - recordedAt Error: type: object properties: error: type: string description: Error message details: type: - string - 'null' description: Additional error details required: - error AgentEvent: description: >- 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. oneOf: - $ref: '#/components/schemas/ClaudeAgentEvent' - $ref: '#/components/schemas/CodexAgentEvent' - $ref: '#/components/schemas/CursorAgentEvent' - $ref: '#/components/schemas/OpencodeAgentEvent' - $ref: '#/components/schemas/PiAgentEvent' discriminator: propertyName: type mapping: claude-assistant: $ref: '#/components/schemas/ClaudeAgentEvent' claude-user: $ref: '#/components/schemas/ClaudeAgentEvent' claude-result: $ref: '#/components/schemas/ClaudeAgentEvent' claude-system: $ref: '#/components/schemas/ClaudeAgentEvent' event_msg: $ref: '#/components/schemas/CodexAgentEvent' response_item: $ref: '#/components/schemas/CodexAgentEvent' cursor-assistant: $ref: '#/components/schemas/CursorAgentEvent' cursor-thinking: $ref: '#/components/schemas/CursorAgentEvent' cursor-tool_call: $ref: '#/components/schemas/CursorAgentEvent' cursor-task: $ref: '#/components/schemas/CursorAgentEvent' cursor-status: $ref: '#/components/schemas/CursorAgentEvent' cursor-error: $ref: '#/components/schemas/CursorAgentEvent' opencode-message.updated: $ref: '#/components/schemas/OpencodeAgentEvent' opencode-session.idle: $ref: '#/components/schemas/OpencodeAgentEvent' opencode-error: $ref: '#/components/schemas/OpencodeAgentEvent' opencode-part-text: $ref: '#/components/schemas/OpencodeAgentEvent' opencode-part-reasoning: $ref: '#/components/schemas/OpencodeAgentEvent' opencode-part-tool: $ref: '#/components/schemas/OpencodeAgentEvent' pi-agent_start: $ref: '#/components/schemas/PiAgentEvent' pi-message_update: $ref: '#/components/schemas/PiAgentEvent' pi-tool_execution_start: $ref: '#/components/schemas/PiAgentEvent' pi-tool_execution_update: $ref: '#/components/schemas/PiAgentEvent' pi-tool_execution_end: $ref: '#/components/schemas/PiAgentEvent' pi-error: $ref: '#/components/schemas/PiAgentEvent' ClaudeAgentEvent: type: object description: >- A streaming event from the Claude Code agent. The `type` field is prefixed with `claude-` followed by the SDK message type. properties: timestamp: type: string format: date-time description: When the event occurred type: type: string enum: - claude-assistant - claude-user - claude-result - claude-system description: >- 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: $ref: '#/components/schemas/ClaudeEventPayload' required: - timestamp - type - payload CodexAgentEvent: type: object description: >- A streaming event from the Codex CLI agent. Uses either `event_msg` for high-level messages or `response_item` for structured response items. properties: timestamp: type: string format: date-time description: When the event occurred type: type: string enum: - event_msg - response_item description: >- `event_msg` carries high-level messages (user input, reasoning). `response_item` carries structured responses (assistant messages, function calls, tool calls). payload: $ref: '#/components/schemas/CodexEventPayload' required: - timestamp - type - payload CursorAgentEvent: type: object description: >- A streaming event from the Cursor agent. Cursor events are normalized with a `cursor-` prefixed type and a provider payload. properties: timestamp: type: string format: date-time description: When the event occurred type: type: string enum: - cursor-assistant - cursor-thinking - cursor-tool_call - cursor-task - cursor-status - cursor-error description: >- 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: type: object description: >- Cursor event payload. Shape depends on the parent event `type`; Cursor payload sub-shapes are not yet formally specified. additionalProperties: true required: - timestamp - type - payload OpencodeAgentEvent: type: object description: >- A streaming event from the Opencode agent. Opencode events are normalized with an `opencode-` prefixed type and an open provider payload. properties: timestamp: type: string format: date-time description: When the event occurred type: type: string pattern: ^opencode- description: >- Opencode event type. Common values include `opencode-message.updated`, `opencode-session.idle`, `opencode-error`, and `opencode-part-*` events. payload: type: object description: >- Opencode event payload. Shape depends on the parent event `type`; Opencode payload sub-shapes are not yet formally specified. additionalProperties: true required: - timestamp - type - payload PiAgentEvent: type: object description: >- A streaming event from the Pi coding agent. Pi events expose session lifecycle, text and reasoning updates, tool execution, and errors. properties: timestamp: type: string format: date-time description: When the event occurred type: type: string pattern: ^pi- description: >- 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: type: object description: Pi event payload. Shape depends on the parent event type. additionalProperties: true required: - timestamp - type - payload ClaudeEventPayload: type: object description: Payload of a Claude Code agent event, wrapping the Claude SDK message. properties: type: type: string description: Original SDK message type (e.g. `assistant`, `user`, `result`) subtype: type: string description: >- 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: type: - string - 'null' description: >- If this message is the result of a sub-agent tool call, the parent tool_use ID message: $ref: '#/components/schemas/ClaudeMessage' is_error: type: boolean description: >- Present on `claude-result` events; true if the turn ended with an error errors: type: array items: type: string description: >- Array of error messages, present on `claude-result` events when `is_error` is true additionalProperties: true CodexEventPayload: description: >- Payload of a Codex CLI agent event. Shape depends on the parent event `type`. oneOf: - $ref: '#/components/schemas/CodexEventMsgPayload' - $ref: '#/components/schemas/CodexResponseItemPayload' discriminator: propertyName: type mapping: user_message: $ref: '#/components/schemas/CodexEventMsgPayload' agent_reasoning: $ref: '#/components/schemas/CodexEventMsgPayload' message: $ref: '#/components/schemas/CodexResponseItemPayload' function_call: $ref: '#/components/schemas/CodexResponseItemPayload' function_call_output: $ref: '#/components/schemas/CodexResponseItemPayload' custom_tool_call: $ref: '#/components/schemas/CodexResponseItemPayload' custom_tool_call_output: $ref: '#/components/schemas/CodexResponseItemPayload' ClaudeMessage: type: object description: A Claude SDK message containing an array of content blocks. properties: content: type: array description: Ordered list of content blocks produced or consumed by the model. items: $ref: '#/components/schemas/ClaudeContentBlock' CodexEventMsgPayload: type: object description: Payload for `event_msg` events — high-level user or reasoning messages. properties: type: type: string enum: - user_message - agent_reasoning description: >- `user_message` for user input, `agent_reasoning` for the agent's chain-of-thought message: type: string description: User message text (present when type is `user_message`) text: type: string description: Reasoning text (present when type is `agent_reasoning`) required: - type CodexResponseItemPayload: type: object description: >- Payload for `response_item` events — structured items from the Codex response stream. oneOf: - type: object title: AssistantMessage description: A text message from the Codex agent. properties: type: type: string const: message role: type: string const: assistant content: type: array items: type: object properties: type: type: string const: output_text text: type: string description: The text content required: - type - text required: - type - role - content - type: object title: FunctionCall description: A function call by the Codex agent (shell commands, plan updates). properties: type: type: string const: function_call call_id: type: string description: >- Unique ID for this call, referenced by the corresponding `function_call_output` name: type: string enum: - shell - shell_command - exec_command - update_plan description: Function name arguments: type: string description: >- JSON-encoded arguments (e.g. `{"command": "ls -la"}` for shell commands, `{"plan": [...]}` for plan updates) required: - type - call_id - name - arguments - type: object title: FunctionCallOutput description: Output from a previously invoked function call. properties: type: type: string const: function_call_output call_id: type: string description: ID of the function_call this output corresponds to output: type: string description: >- Raw output string. For shell commands this may include exit codes and stdout/stderr. required: - type - call_id - output - type: object title: CustomToolCall description: A custom tool invocation (e.g. `apply_patch` for file edits). properties: type: type: string const: custom_tool_call call_id: type: string description: Unique ID for this call name: type: string description: Tool name (e.g. `apply_patch`) input: type: string description: Tool input (e.g. patch content for `apply_patch`) status: type: string enum: - in_progress - completed - failed description: Current execution status required: - type - call_id - name - input - type: object title: CustomToolCallOutput description: Output from a custom tool call. properties: type: type: string const: custom_tool_call_output call_id: type: string description: ID of the custom_tool_call this output corresponds to output: type: string description: JSON-encoded output with optional `metadata.exit_code` required: - type - call_id - output discriminator: propertyName: type ClaudeContentBlock: type: object description: A single content block within a Claude message. Discriminated by `type`. oneOf: - type: object title: TextBlock description: A text response from the model. properties: type: type: string const: text text: type: string description: The text content required: - type - text - type: object title: ThinkingBlock description: An extended-thinking block showing the model's reasoning. properties: type: type: string const: thinking text: type: string description: The thinking/reasoning content required: - type - text - type: object title: ToolUseBlock description: >- A tool invocation by the model (e.g. Bash, Edit, Write, Grep, Glob, Read, WebSearch, TaskCreate, Skill). properties: type: type: string const: tool_use id: type: string description: >- Unique ID for this tool use, referenced by subsequent tool_result blocks name: type: string description: >- Tool name (e.g. `Bash`, `Edit`, `Write`, `Read`, `Grep`, `Glob`, `WebSearch`, `TaskCreate`, `Skill`) input: type: object additionalProperties: true description: Tool-specific input parameters required: - type - id - name - input - type: object title: ToolResultBlock description: >- The result of a tool invocation, sent back to the model in `claude-user` events. properties: type: type: string const: tool_result tool_use_id: type: string description: ID of the tool_use block this result corresponds to content: description: >- Tool output — either a plain string or an array of text/image blocks. oneOf: - type: string - type: array items: type: object properties: type: type: string enum: - text - image text: type: string source: type: object properties: type: type: string media_type: type: string data: type: string description: Base64-encoded image data is_error: type: boolean description: Whether the tool execution resulted in an error required: - type - tool_use_id discriminator: propertyName: type responses: BadRequest: description: Bad request - Missing or invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' BadGateway: description: >- Bad gateway - The workspace is unreachable or returned an invalid response content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: http scheme: bearer description: >- API key authentication. Obtain your API key from the Replicas dashboard under Organization → Settings → API Keys. ````