> ## 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. # List sessions > List sessions in the current environment, newest first. Filter by type, tags, task identifier, external id, status, and creation window. Use cursor-based pagination with `page[after]` and `page[before]` to navigate pages. List rows omit `triggerConfig`; retrieve a single session to read it. ## OpenAPI ````yaml v3-openapi GET /api/v1/sessions 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: get: tags: - sessions summary: List sessions description: >- List sessions in the current environment, newest first. Filter by type, tags, task identifier, external id, status, and creation window. Use cursor-based pagination with `page[after]` and `page[before]` to navigate pages. List rows omit `triggerConfig`; retrieve a single session to read it. operationId: list_sessions_v1 parameters: - $ref: '#/components/parameters/sessionsCursorPagination' - $ref: '#/components/parameters/sessionsFilter' responses: '200': description: Successful request content: application/json: schema: $ref: '#/components/schemas/ListSessionsResult' '400': description: Invalid query parameters content: application/json: schema: $ref: '#/components/schemas/ErrorWithDetailsResponse' '401': description: Unauthorized request security: - secretKey: [] - publicAccessToken: [] x-codeSamples: - lang: typescript label: List sessions source: |- import { sessions } from "@trigger.dev/sdk"; for await (const session of sessions.list({ type: "chat.agent", status: "ACTIVE", limit: 50, })) { console.log(session.id, session.externalId, session.createdAt); } components: parameters: sessionsCursorPagination: in: query name: page style: deepObject explode: true description: > Paginate the results. Specify the number of sessions per page, and the ID of the session to start the page after or before. For object fields like `page`, use the "form" encoding style. For example, to get the next page, use `page[after]=session_1234`. schema: type: object properties: size: type: integer maximum: 100 minimum: 1 default: 20 description: Number of sessions per page. Maximum is 100. after: type: string description: >- The ID of the session to start the page after. Sets the pagination direction to forward. before: type: string description: >- The ID of the session to start the page before. Sets the pagination direction to backward. sessionsFilter: in: query name: filter style: deepObject explode: true description: > Use this parameter to filter the sessions. You can filter by type, tags, task identifier, external id, status, and created at. For array fields, you can provide multiple values to filter by using a comma-separated list. For example, to get ACTIVE and CLOSED sessions, you can use `filter[status]=ACTIVE,CLOSED`. For object fields, you should use the "form" encoding style. For example, to filter by the period, you can use `filter[createdAt][period]=1d`. schema: $ref: '#/components/schemas/SessionsFilter' schemas: ListSessionsResult: type: object properties: data: type: array items: $ref: '#/components/schemas/SessionObject' pagination: type: object properties: next: type: string description: >- The session ID to start the next page after. Pass it as the `page[after]` parameter on the next request. example: session_abc123 previous: type: string description: >- The session ID to start the previous page before. Pass it as the `page[before]` parameter on the next request. example: session_xyz789 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 SessionsFilter: type: object properties: type: type: array items: type: string description: The session type(s) to filter by. example: - chat.agent tags: type: array items: type: string description: The tags to filter by. taskIdentifier: type: array items: type: string description: The task identifier(s) to filter by. externalId: type: string description: Exact match on your `externalId`. status: type: array items: type: string enum: - ACTIVE - CLOSED - EXPIRED description: The lifecycle status(es) to filter by. createdAt: type: object properties: from: type: string format: date-time description: The start date to filter the sessions by. to: type: string format: date-time description: The end date to filter the sessions by. period: type: string description: The period to filter the sessions by. example: 1d 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). ````