> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galtea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get sessions

> Get list of sessions with pagination and filtering. See [Sessions](https://docs.galtea.ai/concepts/product/version/session).

> [!WARNING]
>
> You are reading the docs of Galtea 5.15. [Read this page in the latest version](https://docs.galtea.ai/api-reference/sessions/get-sessions.md).


## OpenAPI

````yaml /v5.15/openapi.json get /sessions
openapi: 3.0.0
info:
  version: 1.0.0
  title: Product Management Service API
  description: API documentation for Product Management Service
  contact:
    name: Galtea AI
servers:
  - url: https://api.galtea.ai
security:
  - bearerAuth: []
tags: []
externalDocs:
  description: Galtea Platform Documentation
  url: https://docs.galtea.ai
paths:
  /sessions:
    get:
      tags:
        - sessions
      summary: Get sessions
      description: >-
        Get list of sessions with pagination and filtering. See
        [Sessions](https://docs.galtea.ai/concepts/product/version/session).
      operationId: getSessions
      parameters:
        - schema:
            type: array
            items:
              type: string
            description: Filter by session IDs
          required: false
          description: Filter by session IDs
          style: form
          explode: true
          name: ids
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by session custom IDs
          required: false
          description: Filter by session custom IDs
          style: form
          explode: true
          name: customIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by product IDs
          required: false
          description: Filter by product IDs
          style: form
          explode: true
          name: productIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by test IDs (include only). Use an empty string ("") to
              select sessions without a test
          required: false
          description: >-
            Filter by test IDs (include only). Use an empty string ("") to
            select sessions without a test
          style: form
          explode: true
          name: testIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Omit sessions linked to the specified test IDs. Use an empty
              string ("") to omit sessions without a test
          required: false
          description: >-
            Omit sessions linked to the specified test IDs. Use an empty string
            ("") to omit sessions without a test
          style: form
          explode: true
          name: excludeTestIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by version IDs
          required: false
          description: Filter by version IDs
          style: form
          explode: true
          name: versionIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by monitor IDs (returns only sessions scored by the given
              monitors)
          required: false
          description: >-
            Filter by monitor IDs (returns only sessions scored by the given
            monitors)
          style: form
          explode: true
          name: monitorIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by monitor alert IDs (returns only the sessions the alert
              linked when it opened (its bad sessions, or its sessions with no
              score); a session deleted since is left out). At most 10 IDs.
            maxItems: 10
          required: false
          description: >-
            Filter by monitor alert IDs (returns only the sessions the alert
            linked when it opened (its bad sessions, or its sessions with no
            score); a session deleted since is left out). At most 10 IDs.
          style: form
          explode: true
          name: monitorAlertIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by the specifications a session relates to. A session
              relates to a specification in two ways, and either one matches: it
              runs a test case of a test linked to that specification, or it
              carries an evaluation whose metric is linked to that
              specification. Multiple values combine as OR.
          required: false
          description: >-
            Filter by the specifications a session relates to. A session relates
            to a specification in two ways, and either one matches: it runs a
            test case of a test linked to that specification, or it carries an
            evaluation whose metric is linked to that specification. Multiple
            values combine as OR.
          style: form
          explode: true
          name: specificationIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by the specifications a session failed, with the rule of
              the analytics reads: the session carries a scored evaluation of a
              metric linked to the specification that did not pass the metric's
              threshold, where a reviewer's score wins over the judge's. Metrics
              excluded from analytics and versions that are deleted, or of
              another product than the specification's, do not count. Multiple
              values combine as OR. At most 25 IDs. Answers 400 when the
              specifications failed more than 10000 sessions within the caller's
              read scope, `ids`, `productIds`, `versionIds`, `isProduction`,
              `fromCreatedAt` and `toCreatedAt`, so narrow the period. Deleted
              sessions do not count, and seed sessions count only when named in
              `ids`.
            maxItems: 25
          required: false
          description: >-
            Filter by the specifications a session failed, with the rule of the
            analytics reads: the session carries a scored evaluation of a metric
            linked to the specification that did not pass the metric's
            threshold, where a reviewer's score wins over the judge's. Metrics
            excluded from analytics and versions that are deleted, or of another
            product than the specification's, do not count. Multiple values
            combine as OR. At most 25 IDs. Answers 400 when the specifications
            failed more than 10000 sessions within the caller's read scope,
            `ids`, `productIds`, `versionIds`, `isProduction`, `fromCreatedAt`
            and `toCreatedAt`, so narrow the period. Deleted sessions do not
            count, and seed sessions count only when named in `ids`.
          style: form
          explode: true
          name: failedSpecificationIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by the id of the user who launched the session. A
              production session has no launcher and never matches this filter.
              An OTel-ingested session is production unless its spans name a
              test case; that one records the user of the API key that sent the
              traces, so it does match.
          required: false
          description: >-
            Filter by the id of the user who launched the session. A production
            session has no launcher and never matches this filter. An
            OTel-ingested session is production unless its spans name a test
            case; that one records the user of the API key that sent the traces,
            so it does match.
          style: form
          explode: true
          name: userIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by the runs that CREATED the sessions. A session created
              outside a launch (production traffic, an imported trace) has no
              run and never matches. To also reach the sessions a run only
              scored, use `involvedInRunIds`.
          required: false
          description: >-
            Filter by the runs that CREATED the sessions. A session created
            outside a launch (production traffic, an imported trace) has no run
            and never matches. To also reach the sessions a run only scored, use
            `involvedInRunIds`.
          style: form
          explode: true
          name: runIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by the runs a session relates to either way, as an OR: the
              run created the session, or the run scored it through one of its
              evaluations. This is the set a run reports as its session count.
          required: false
          description: >-
            Filter by the runs a session relates to either way, as an OR: the
            run created the session, or the run scored it through one of its
            evaluations. This is the set a run reports as its session count.
          style: form
          explode: true
          name: involvedInRunIds
          in: query
        - schema:
            type: array
            items:
              type: string
            description: Filter by test case IDs
          required: false
          description: Filter by test case IDs
          style: form
          explode: true
          name: testCaseIds
          in: query
        - schema:
            type: boolean
            description: >-
              Filter by the session's `isProduction` flag. Prefer this over the
              legacy `testIds`/`excludeTestIds` empty-string trick.
          required: false
          description: >-
            Filter by the session's `isProduction` flag. Prefer this over the
            legacy `testIds`/`excludeTestIds` empty-string trick.
          name: isProduction
          in: query
        - schema:
            type: array
            items:
              type: string
              enum:
                - PENDING
                - COMPLETED
                - FAILED
            description: Filter by session statuses. Multiple values combine as OR.
          required: false
          description: Filter by session statuses. Multiple values combine as OR.
          style: form
          explode: true
          name: statuses
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Filter by comment state. `__any__` matches sessions with at least
              one comment, `__none__` matches sessions with no comment, and any
              other value matches sessions with a comment carrying that label.
              All values combine as OR, so `__none__` plus a label returns
              sessions that have no comment OR carry that label.
          required: false
          description: >-
            Filter by comment state. `__any__` matches sessions with at least
            one comment, `__none__` matches sessions with no comment, and any
            other value matches sessions with a comment carrying that label. All
            values combine as OR, so `__none__` plus a label returns sessions
            that have no comment OR carry that label.
          style: form
          explode: true
          name: commentLabels
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Sort instructions (field and direction pairs). A sort that names
              `turnCount` may name only these fields: `turnCount`, `createdAt`,
              `id`, `stoppingReason`, `testCaseId`, `versionId`, `context`. It
              answers 400 when more than 50000 sessions match the filters.
          required: false
          description: >-
            Sort instructions (field and direction pairs). A sort that names
            `turnCount` may name only these fields: `turnCount`, `createdAt`,
            `id`, `stoppingReason`, `testCaseId`, `versionId`, `context`. It
            answers 400 when more than 50000 sessions match the filters.
          style: form
          explode: true
          name: sort
          in: query
        - schema:
            type: integer
            minimum: 0
            maximum: 9007199254740991
            default: 10000
            description: Maximum number of results
          required: false
          description: Maximum number of results
          name: limit
          in: query
        - schema:
            type: integer
            minimum: 0
            default: 0
            description: Number of results to skip
          required: false
          description: Number of results to skip
          name: offset
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Filter sessions created at or after this timestamp (ISO 8601
              format)
          required: false
          description: Filter sessions created at or after this timestamp (ISO 8601 format)
          name: fromCreatedAt
          in: query
        - schema:
            type: string
            format: date-time
            description: >-
              Filter sessions created at or before this timestamp (ISO 8601
              format)
          required: false
          description: >-
            Filter sessions created at or before this timestamp (ISO 8601
            format)
          name: toCreatedAt
          in: query
      responses:
        '200':
          description: Sessions retrieved successfully
          headers:
            Content-Range:
              schema:
                type: string
                description: Pagination range as `sessions <offset>-<upperBound>/<total>`.
              required: true
              description: Pagination range as `sessions <offset>-<upperBound>/<total>`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SessionListItem'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    SessionListItem:
      type: object
      properties:
        id:
          type: string
          example: session_123
        customId:
          type: string
          nullable: true
          example: custom_session_123
        versionId:
          type: string
          example: ver_123
        userId:
          type: string
          nullable: true
          example: user_123
        testCaseId:
          type: string
          nullable: true
          example: tc_123
        context:
          type: object
          nullable: true
          additionalProperties:
            nullable: true
          description: >-
            Structured context data. For plain text context, format is { value:
            "..." }
          example:
            value: Session context information
        stoppingReason:
          type: string
          nullable: true
          example: GOAL_ACHIEVED
        recordingUri:
          type: string
          nullable: true
          description: >-
            Storage URI of the full-call recording for a telephony-evaluation
            session, returned under `STORAGE_PUBLIC_BASE_URL` when the
            deployment configures one. Null for non-telephony sessions or before
            the recording is processed. Resolve to a playable URL via GET
            /storage?uri=.
          example: https://files.galtea.ai/audio/org_123/session_abc-recording.mp3
        error:
          type: string
          nullable: true
          example: >-
            External API responded with HTTP 422: Unprocessable Entity —
            {"detail":"model not found"}
        status:
          type: string
          enum:
            - PENDING
            - COMPLETED
            - FAILED
          example: PENDING
        isProduction:
          type: boolean
          description: >-
            True when the session represents real production traffic (no
            associated test case).
          example: false
        isSeed:
          type: boolean
          readOnly: true
          description: >-
            True when the session holds the predefined conversation of a test
            case and is never executed. Server-managed and read-only.
          example: false
        metadata:
          nullable: true
          description: >-
            Arbitrary metadata, returned as stored. Usually an object, but any
            JSON value is accepted.
          example:
            key: value
        runId:
          type: string
          nullable: true
          description: >-
            The run that created this session. Null for a session created
            outside a launch (production traffic, an imported trace). A session
            a run only scored names no run here; filter with `involvedInRunIds`
            to reach those too.
          example: run_123
        createdAt:
          type: string
          format: date-time
        deletedAt:
          type: string
          format: date-time
          nullable: true
        turnCount:
          type: integer
          readOnly: true
          description: >-
            Number of turns in the session, not counting deleted ones. Sort by
            it with `sort=turnCount&sort=desc` (or `asc`).
          example: 3
      required:
        - id
        - customId
        - versionId
        - userId
        - testCaseId
        - context
        - stoppingReason
        - recordingUri
        - error
        - status
        - isProduction
        - isSeed
        - runId
        - deletedAt
        - turnCount
    Error:
      type: object
      properties:
        error:
          type: string
          example: Error type
        message:
          type: string
          example: Error message description
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key authorization. Pass your API key in the Authorization header as
        a Bearer token. Both new (`gsk_*`) and legacy (`gsk-`) API keys are
        accepted, e.g. `Authorization: Bearer gsk_...` or `Authorization: Bearer
        gsk-...`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.