> ## Documentation Index > Fetch the complete documentation index at: https://trigger.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve session > Retrieve a single session by its friendly id (`session_…`) or your `externalId`. The response includes `triggerConfig` and the friendly `currentRunId` of the live run, if any. ## OpenAPI ````yaml v3-openapi GET /api/v1/sessions/{session} openapi: 3.1.0 info: title: Trigger.dev v3 REST API description: >- The REST API lets you trigger and manage runs on Trigger.dev. You can trigger a run, get the status of a run, and get the results of a run. version: 2024-04 license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.trigger.dev description: Trigger.dev API security: [] paths: /api/v1/sessions/{session}: parameters: - $ref: '#/components/parameters/session' get: tags: - sessions summary: Retrieve a session description: >- Retrieve a single session by its friendly id (`session_…`) or your `externalId`. The response includes `triggerConfig` and the friendly `currentRunId` of the live run, if any. operationId: retrieve_session_v1 responses: '200': description: Successful request content: application/json: schema: $ref: '#/components/schemas/SessionObject' '401': description: Unauthorized request '404': description: Session not found security: - secretKey: [] - publicAccessToken: [] x-codeSamples: - lang: typescript label: Retrieve a session source: |- import { sessions } from "@trigger.dev/sdk"; const session = await sessions.retrieve(chatId); console.log(session.currentRunId, session.tags, session.closedAt); components: parameters: session: in: path name: session required: true schema: type: string description: >- The session's friendly ID (`session_…`) or your `externalId`. The server disambiguates by the `session_` prefix. example: session_abc123 schemas: SessionObject: type: object description: A session row. required: - id - type - taskIdentifier - tags - createdAt - updatedAt properties: id: type: string description: The session's friendly ID, prefixed with `session_`. example: session_abc123 externalId: type: string nullable: true description: Your stable identity for the session, if one was set. example: chat_1234 type: type: string description: The session type discriminator. example: chat.agent taskIdentifier: type: string description: The task this session triggers runs against. example: my-chat triggerConfig: $ref: '#/components/schemas/SessionTriggerConfig' currentRunId: type: string nullable: true description: >- Friendly ID of the live run for this session, if any. Prefixed with `run_`. Omitted on list rows. example: run_def456 tags: type: array items: type: string description: Tags on the session row. example: - chat:1234 metadata: type: object additionalProperties: true nullable: true description: Arbitrary JSON metadata, or `null` if unset. closedAt: type: string format: date-time nullable: true description: When the session was closed, or `null` if open. closedReason: type: string nullable: true description: The optional reason recorded when the session was closed. expiresAt: type: string format: date-time nullable: true description: The session's retention deadline, or `null` if none. createdAt: type: string format: date-time updatedAt: type: string format: date-time SessionTriggerConfig: type: object description: >- Trigger options applied to every run a session schedules. `basePayload` is the wire payload merged into each run; the remaining fields map onto the standard trigger options. required: - basePayload properties: basePayload: type: object additionalProperties: true description: >- Base payload passed to every run this session triggers. For `chat.agent` this carries `{ chatId, ...clientData }`. machine: type: string description: Machine preset for each run, e.g. `small-1x`. example: small-1x queue: type: string maxLength: 128 description: Queue to schedule runs on. tags: type: array maxItems: 5 items: type: string maxLength: 128 description: Tags applied to every run this session triggers. maxAttempts: type: integer minimum: 1 maximum: 10 description: Maximum retry attempts per run. maxDuration: type: integer minimum: 1 description: Per-run wall-clock cap in seconds. lockToVersion: type: string description: Pin every run to a specific worker version. example: '20240523.1' region: type: string description: Region to schedule runs in. idleTimeoutInSeconds: type: integer minimum: 1 maximum: 3600 description: Idle timeout surfaced to `chat.agent` via the wire payload. securitySchemes: secretKey: type: http scheme: bearer description: > Use a named environment API key. It starts with `tr_dev_sk_`, `tr_prod_sk_`, `tr_stg_sk_`, etc. Create a named API key in the API Keys section of your Trigger.dev project dashboard. Choose the narrowest access preset that supports your integration. Our TypeScript SDK will default to using the value of the `TRIGGER_SECRET_KEY` environment variable if it is set. If you are using the SDK in a different environment, you can set the key using the `configure` function. ```typescript import { configure } from "@trigger.dev/sdk"; configure({ accessToken: "tr_dev_sk_1234" }); ``` publicAccessToken: type: http scheme: bearer description: > A short-lived JWT scoped to specific resources, returned as `publicAccessToken` from APIs such as `wait.createToken()` / `POST /api/v1/waitpoints/tokens` and `sessions.start()` / `POST /api/v1/sessions`, or minted directly with `auth.createPublicToken()`. This token is safe to embed in frontend clients — it can only act on the resources its scopes grant (e.g. `read:sessions:{id}`, `write:sessions:{id}`) and cannot be used for any other API operations. For session tokens see the [session scopes](/management/authentication#session-scopes). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.