---
title: "Read the session's conversation"
method: GET
path: "/api/v2/projects/{projectId}/sessions/{sessionId}/messages"
tags: ["Sessions"]
---

# Read the session's conversation

`GET /api/v2/projects/{projectId}/sessions/{sessionId}/messages`

## Request

- Base URL: `https://davinci-app.com`
- URL: `https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}/messages`
- Auth: HTTP bearer

The transcript: your prompts, the agent's replies and reasoning, and every tool
it used with the result.

`source` tells you where the answer came from. `live` is the running agent's own
copy and is current. `persisted` is the saved copy, which is written when a run
ends — so it is complete for a finished run but behind for a running one. `none`
means there is no conversation yet.

Entries are ordered oldest to newest and `limit` takes the most recent, which is
usually what you want after a run.

## Query parameters

- `limit` integer

## Response `200`

The conversation.

- AgentTranscript
  - `sessionId` string, uuid, required
  - `taskId` string, required
  - `source` 'live' | 'persisted' | 'none', required: Where the answer came from. `live` is current; `persisted` is the copy saved when a run ended, and so lags a run in progress.
  - `status` 'no_session' | 'project_not_running' | 'idle' | 'starting' | 'running' | 'paused' | 'completed' | 'failed' | 'unknown', required: - `no_session` — the machine has no record of this session; it lapsed or the project restarted. Create a new one. - `project_not_running` — the session is known but its project has unloaded. - `idle` — the session is live and no run has been started. - `starting` — a run is being set up. - `running` — a run is in progress. - `paused` — a run was stopped and can be continued with a new prompt. - `completed` — the run finished. - `failed` — the run ended in an error. `agent.error` says why, as does the transcript. - `unknown` — the machine could not be reached for this field. Retry; anything else in the same response is still valid. `paused`, `completed`, and `failed` are terminal for a run.
  - `entryCount` integer, required: Entries in the whole conversation, not just the returned window.
  - `messages` AgentMessage[], required: Oldest first. Bounded by `limit`, taken from the end.
    - `index` integer, required: Position in the whole conversation, so a window can be placed.
    - `role` 'user' | 'agent', required
    - `kind` string, required: `text` for what was said, `thought` for the agent's reasoning, `tool` for a tool it used, `error` for a failure it hit. Treat an unrecognized value as informational rather than as a problem — new kinds can appear.
    - `text` string: The content. For a `tool` entry, the tool's name.
    - `timestamp` integer, nullable: Milliseconds since the epoch.
    - `messageId` string: Present on your own prompts, matching what you sent.
    - `tool` AgentToolUse: Present only on entries whose `kind` is `tool`.
      - `name` string, nullable
      - `status` string, nullable: `working` while it runs, `complete` when it succeeded, otherwise the severity of what went wrong.
      - `params` unknown
      - `result` unknown
      - `error` string: Present when the tool failed.

## Other responses

- `400`: `limit` is out of range. Error code is `INVALID_LIMIT`.
- `401`: No credential was supplied, or the supplied credential is malformed, expired, or revoked. A credential that is present but unusable is never downgraded to an anonymous request.
- `403`: Authenticated but not authorized. Either the acting user lacks the required resource permission, the key's scope ceiling excludes it, or the endpoint rejects this credential type (`CREDENTIAL_NOT_PERMITTED`).
- `404`: No such session, it belongs to another user, or it belongs to a different project than the one in the path. Error code is `SESSION_NOT_FOUND`.
- `429`: Request rate exceeded, either globally or for this key.
- `500`: Unexpected server error.

## Changes

- **2026-09-15** (v2) `67c8b8616dbb`: 6 info
  - the `success` response property const value `false` was added for the status `400`
  - the `success` response property const value `false` was added for the status `401`
  - the `success` response property const value `false` was added for the status `403`
  - the `success` response property const value `false` was added for the status `404`
  - …2 more
- **2026-09-15** (v2) `48948af37797`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/changes/api/v2/projects/:projectId/sessions/:sessionId/messages/get.md)

---

[API](https://skmtc.dev/celedon-solutions/apis/davinci-public-api.md) - [All operations](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/revisions/279218ca2e8d?raw)