> ## 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. # Close session > Close a session. Closing is terminal and idempotent — closing an already-closed session returns the existing row unchanged. A closed session cannot be reopened, and reusing its `externalId` on create returns `409`. Requires a secret key — a session public token cannot close a session. ## OpenAPI ````yaml v3-openapi POST /api/v1/sessions/{session}/close 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}/close: parameters: - $ref: '#/components/parameters/session' post: tags: - sessions summary: Close a session description: >- Close a session. Closing is terminal and idempotent — closing an already-closed session returns the existing row unchanged. A closed session cannot be reopened, and reusing its `externalId` on create returns `409`. Requires a secret key — a session public token cannot close a session. operationId: close_session_v1 requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/CloseSessionRequestBody' responses: '200': description: Session closed successfully. Returns the session row. content: application/json: schema: $ref: '#/components/schemas/SessionObject' '401': description: Unauthorized request '404': description: Session not found security: - secretKey: [] x-codeSamples: - lang: typescript label: Close a session source: |- import { sessions } from "@trigger.dev/sdk"; await sessions.close(chatId, { reason: "user signed out" }); 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: CloseSessionRequestBody: type: object description: Body for `POST /api/v1/sessions/{session}/close`. Up to 1KB. properties: reason: type: string maxLength: 256 description: Optional reason recorded on the session row. example: user signed out 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" }); ``` ````