> ## 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. # Update session > Update a session's `tags` or `metadata`. Pass `metadata: null` to clear it. Requires a secret key — a session public token cannot update a session. `externalId` is read-only after create: it cannot be changed or cleared. Sending a value different from the current one (including `null` when one is set) returns `422`; sending the same value is accepted as a no-op. ## OpenAPI ````yaml v3-openapi PATCH /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' patch: tags: - sessions summary: Update a session description: >- Update a session's `tags` or `metadata`. Pass `metadata: null` to clear it. Requires a secret key — a session public token cannot update a session. `externalId` is read-only after create: it cannot be changed or cleared. Sending a value different from the current one (including `null` when one is set) returns `422`; sending the same value is accepted as a no-op. operationId: update_session_v1 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSessionRequestBody' responses: '200': description: Session updated successfully content: application/json: schema: $ref: '#/components/schemas/SessionObject' '401': description: Unauthorized request '404': description: Session not found '422': description: >- Validation failed — for example an attempt to change `externalId` to a different value, or a body exceeding 32KB. content: application/json: schema: $ref: '#/components/schemas/ErrorWithDetailsResponse' security: - secretKey: [] x-codeSamples: - lang: typescript label: Update a session source: |- import { sessions } from "@trigger.dev/sdk"; const session = await sessions.update(chatId, { tags: ["priority"], metadata: { lastSeenBy: "support" }, }); 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: UpdateSessionRequestBody: type: object description: >- Body for `PATCH /api/v1/sessions/{session}`. The whole body must be 32KB or smaller. Every field is optional; omitted fields are left unchanged. properties: tags: type: array maxItems: 10 items: type: string maxLength: 128 description: Replaces the tags on the session row. metadata: type: object additionalProperties: true nullable: true description: Replaces the metadata. Pass `null` to clear it. externalId: type: string nullable: true minLength: 1 maxLength: 256 description: >- Read-only after create: cannot be changed or cleared. Sending a value different from the current one (including `null` when one is set) returns `422`; sending the same value is idempotent. 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 ErrorWithDetailsResponse: type: object properties: error: type: string example: Query Error details: type: array items: type: object required: - code - message properties: code: type: string description: The error code example: custom message: type: string description: The error message example: 'Invalid status values: FOOBAR' path: type: array items: type: string description: The relevant path in the request example: - filter[status] required: - error 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" }); ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.