--- title: "Read a session, refresh its grant, and check the agent" method: GET path: "/api/v2/projects/{projectId}/sessions/{sessionId}" tags: ["Sessions"] --- # Read a session, refresh its grant, and check the agent `GET /api/v2/projects/{projectId}/sessions/{sessionId}` ## Request - Base URL: `https://davinci-app.com` - URL: `https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}` - Auth: HTTP bearer Returns the session with a **new** grant and revokes the previous one, so a leaked grant stops working at the next poll rather than at its expiry. This is also the keepalive, for both clocks that matter: the grant's expiry and the machine's idle timer. Call it well before `dataPlane.expiresAt` — the SDKs do this for you. `agent.status` is how you follow a run started with `sendAgentMessage`. It is reported here rather than on a route of its own precisely so that one poll keeps the session alive and tells you where the run is. `completed`, `failed`, and `paused` are terminal; `paused` is what a `stopAgent` produces. `unknown` means the machine could not be reached for this field alone — the grant in the same response is still good, so retry rather than recreating the session. ## Response `200` The session, with a freshly minted grant. - Session - `sessionId` string, uuid, required - `projectId` string, required: Bare project id, without the branch suffix. - `branchName` string, required - `ownerId` string, required: Account or organization that owns the project. Files live under the owner's storage namespace, not the caller's, which is why a shared or org-owned project needs this rather than your own user id. - `dataPlane` DataPlaneAccess, required: Everything needed to address the data plane: where to send, what to send with, and the path parameters that are not obvious from the project id alone. - `url` string, uri, required: Base URL for data-plane operations. Names no specific machine, so it stays valid if the project moves. - `token` string, required: The grant, `dav_gr_…`. Returned only here and only once — it is not stored in recoverable form, so a lost grant is replaced by refreshing the session rather than looked up. - `expiresAt` string, date-time, required - `connectionId` string, required: Pass as the `connectionId` path parameter on upload. - `ownerId` string, required: Pass as the `ownerId` path parameter. - `userId` string, required: Pass as the `userId` path parameter on upload. - `projectKey` string, required: Pass as the `projectId` path parameter. Compound form `{projectId}--{branchName}`, since the data plane addresses a branch. - `operations` string[], required: Data-plane operations this grant authorizes. - `agent` AgentState: What the session's agent is doing. Present on a session read, absent on create because nothing has been asked of the agent yet. - `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. - `taskId` string, nullable: Identifies the run. Also names the stored conversation. - `lastMessageId` string, nullable: The `messageId` of the most recent prompt the agent took. - `error` AgentFailure: Why the run failed. Present only while `status` is `failed`, so the read that tells you the run is over also tells you why — closing the session afterwards loses nothing. - `message` string, required: What went wrong, as the transcript records it. - `category` string, nullable: The model provider's error category when the failure came from the provider, such as `context_window`, `rate_limit`, or `unavailable`; otherwise null. ## Other responses - `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, or it belongs to another user. Error code is `SESSION_NOT_FOUND`. - `409`: The project this session opened is no longer running. Error code is `PROJECT_NOT_RUNNING`; create a new session. - `429`: Request rate exceeded, either globally or for this key. - `500`: Unexpected server error. ## Changes - **2026-11-04** (v2) `8663bb3e802f`: 1 info - added the optional property `agent/error` to the response with the `200` status - **2026-09-15** (v2) `67c8b8616dbb`: 6 info - 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` - the `success` response property const value `false` was added for the status `409` - …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/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)