---
title: Get Message
description: Fetches a single message in a chat.
docs_index: /docs/llms.txt
lastUpdated: 2026-10-27
badge: "GET"
---

> For an index of all documentation, see [/docs/llms.txt](/docs/llms.txt).

Fetches a single message in a chat.

#### `GET /v2/chats/{chatId}/messages/{messageId}`

## Usage

```typescript
import { v0 } from 'v0'

const result = await v0.messages.get({
  chatId: 'chat_abc123',
  messageId: 'msg_xyz789',
})

console.log(result)
```

```bash
curl -X GET "https://api.v0.dev/v2/chats/chat_abc123/messages/chat_abc123"   -H "Authorization: Bearer $V0_API_KEY"   -H "Content-Type: application/json"
```

## API Signature

### Request

#### Path Parameters

- `chatId: string` The unique identifier of the chat.
  - **Minimum length:** 1
- `messageId: string` The unique identifier of the message.
  - **Minimum length:** 1

### Response

- `id: string` Unique message identifier.
- `chatId: string` ID of the chat this message belongs to.
- `role: 'user' | 'assistant'` Who produced this message.
- `createdAt: string` ISO timestamp when the message was created.
- `updatedAt: string` ISO timestamp when the message was last updated.
- `content: string` The trailing prose of the message — the agent’s closing summary, or the user’s message text. Empty string when there is no closing prose.
- `parts: ('text' | 'thinking' | 'file-read' | 'file-edit' | 'search' | 'bash' | 'tool-call' | 'agent-action')[]` Ordered list of parts that make up the message. Iterate to render the full narrative including thinking, file operations, tool calls, and prose.
  - **text** A block of text output by the agent.
    - `type: 'text'`
    - `text: string` Markdown prose written by the agent or user.
    - `startedAt?: string` ISO timestamp when this part began.
    - `finishedAt?: string` ISO timestamp when this part completed.
  - **thinking** Extended thinking output by the agent.
    - `type: 'thinking'`
    - `text: string` The agent's reasoning trace.
    - `startedAt?: string` ISO timestamp when this part began.
    - `finishedAt?: string` ISO timestamp when this part completed.
  - **file-read** Files read by the agent.
    - `type: 'file-read'`
    - `paths: string[]` The file paths the agent read in this step.
    - `startedAt?: string` ISO timestamp when this part began.
    - `finishedAt?: string` ISO timestamp when this part completed.
  - **file-edit** The agent created, modified, deleted, renamed, or patched a file.
    - `type: 'file-edit'`
    - `operation: 'create' | 'update' | 'delete' | 'rename' | 'patch'` The type of file edit performed.
    - `path: string` The target file path.
    - `toPath?: string` The new path when operation is "rename".
    - `startedAt?: string` ISO timestamp when this part began.
    - `finishedAt?: string` ISO timestamp when this part completed.
  - **search** The agent searched for something.
    - `type: 'search'`
    - `scope: 'repo' | 'web'` Whether the agent searched the repository or the web.
    - `query: string` The search query.
    - `startedAt?: string` ISO timestamp when this part began.
    - `finishedAt?: string` ISO timestamp when this part completed.
  - **bash** The agent ran a shell command.
    - `type: 'bash'`
    - `command: string` The shell command that was executed.
    - `output?: string` Combined stdout/stderr captured from the terminal. May be empty if the command produced no output.
    - `exitCode?: integer | null` Process exit code, when available. Reserved for future use; currently always omitted.
    - `isDangerous?: boolean` True if the command was flagged as potentially dangerous and required explicit user approval.
    - `timeoutMs?: integer` Command timeout in milliseconds, when configured.
    - `startedAt?: string` ISO timestamp when this part began.
    - `finishedAt?: string` ISO timestamp when this part completed.
  - **tool-call** The agent invoked a tool (MCP, integration, or other dynamic tool). For shell commands, use the "bash" part instead.
    - `type: 'tool-call'`
    - `name: string` The identifier the tool was invoked under. For MCP/integration tools this is a normalized identifier derived from the tool name — prefer `toolDisplayName` for display when present.
    - `toolDisplayName?: string | null` The tool's original human-readable name (an MCP/integration tool's server-side name), when `name` is a normalized identifier. Display-only.
    - `input?: unknown` The arguments passed to the tool. Schema depends on the specific tool.
    - `output?: unknown` The result returned by the tool. Schema depends on the specific tool.
    - `status: 'ok' | 'error'` Whether the tool call succeeded or returned an error.
    - `suggestedPermissions?: object[]` Present when the agent is blocked waiting for you to approve this tool call (for example, running a setup or migration script). Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task to approve. Omitted once the tool has run.
      - `item: object` A permission the agent is waiting for you to grant. Pass these objects back unchanged as the `permissions` of a `confirmed-permissions` task.
        - `type: 'ALLOW_DYNAMIC_TOOL_STRICT'` Permission grant type.
        - `toolName: string` The tool this permission authorizes.
        - `input?: unknown` The tool input this permission authorizes. Pass back unchanged when resolving.
        - `toolDisplayName?: string | null` The tool's original human-readable name (an MCP/integration tool's server name), when `toolName` is a normalized identifier. Display-only; pass back unchanged.
        - `taskNameActive?: string | null` Internal label for the in-progress task. Pass back unchanged.
        - `taskNameComplete?: string | null` Internal label for the completed task. Pass back unchanged.
        - `userMessage?: string` Optional message associated with the permission.
    - `startedAt?: string` ISO timestamp when this part began.
    - `finishedAt?: string` ISO timestamp when this part completed.
  - **agent-action** A typed escape hatch for agent actions that don’t fit the other part types. Forward-compatible: new action types may appear without API version changes.
    - `type: 'agent-action'`
    - `name: string` Stable identifier for the action (e.g. "generate\_image", "manage\_todos", "diagnostics"). See documentation for the registry of known names.
    - `summary: string` A short human-readable summary of what happened. Always populated so clients can render something even without knowing the action name.
    - `data?: object | object | object | object | object | object` Structured payload for input-requesting actions. Present on `ask_user_questions`, `exit_plan_mode`, `get_or_request_integration`, and `configure_vercel_connect` parts when the agent is waiting on you; narrow by the part `name`. Omitted for actions that do not carry structured data.
      - `questions: object[]` The questions the agent is waiting for answers to. Resolve with an `answered-questions` task.
        - `item: object`
          - `id: string` Question identifier. Pass back as `questionId` when resolving with an `answered-questions` task.
          - `question: string` The full question text.
          - `header: string` Short label for the question.
          - `multiSelect: boolean` Whether more than one option may be selected.
          - `options: object[]` The available answer options.
            - `item: object`
              - `id: string` Option identifier.
              - `label: string` Display label. Pass matching labels back in `selectedLabels` when resolving.
              - `description?: string` Optional longer explanation of the option.
    - `startedAt?: string` ISO timestamp when this part began.
    - `finishedAt?: string` ISO timestamp when this part completed.
- `finishReason: 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other' | null` Why generation ended. Null while the agent is still generating; once non-null, the message is final and safe to consume.
- `restorable: boolean` True when this is an assistant message that produced restorable code and is not the currently active code.
- `attachments?: object[]` Files attached to this message.
  - `item: object`
    - `url: string` URL to the attachment.
    - `name?: string` Original filename, when available.
    - `contentType?: string` MIME type.
    - `size?: integer` Size in bytes.
- `authorId: string | null` ID of the user who authored a user message; null for assistant messages.
- `usage: object` Model identifier, token usage, and credit cost. Token and credit values are zero on user messages and on assistant messages that have not yet generated tokens.
  - `model: string | null` Model identifier used for the assistant message, or null when not applicable or unavailable.
  - `tokens: object` Token counts for this message.
    - `input: number` Prompt input value (non-cached).
    - `output: number` Completion output value.
    - `cacheRead: number` Cache-read input value.
    - `cacheWrite: number` Cache-write input value.
    - `total: number` Sum of input, output, cacheRead, and cacheWrite.
  - `creditsCost: object` Credit cost for this message.
    - `input: number` Prompt input value (non-cached).
    - `output: number` Completion output value.
    - `cacheRead: number` Cache-read input value.
    - `cacheWrite: number` Cache-write input value.
    - `total: number` Sum of input, output, cacheRead, and cacheWrite.

---

For a semantic overview of all documentation, see [/docs/sitemap.md](/docs/sitemap.md)

For an index of all available documentation, see [/docs/llms.txt](/docs/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/docs/agents.md](/docs/agents.md)