> ## 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 your project-specific Secret API key. Will start with `tr_dev_`, `tr_prod`, `tr_stg`, etc. You can find your Secret API key in the API Keys section of your Trigger.dev project dashboard. 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_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). ````