> ## 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.

# Evaluate multiple sessions in one call

> Batch-evaluate existing sessions in a single call. Pick exactly one mode: (a) `sessionIds` — explicit list of session IDs; (b) `versionId` — every session attached to that version. Each selected session is evaluated by the same logic as `POST /evaluations/fromSession`, so the traces that already live on the session are scored. Unlike `POST /evaluations/fromVersion`, this endpoint does NOT require a conversation endpoint connection on the version — use it when the traces already exist (e.g. imported ones). Metric scope: if you send `metrics`, they are applied to every session. If you do not send `metrics`, each session is scored only by the metrics of its own originating specification (the spec that produced its test case), never the union of all the product's metrics. A session with no spec of its own (for example an imported one) is scored with the metrics of every spec of its product. When you send `specificationIds`, a session whose own spec is in the list is scored with that spec's metrics, and a session whose own spec is not in the list is skipped. A session with no spec of its own is then scored with the metrics of the listed specs of its own product, each metric once, and is skipped when there are none. Skipped sessions are reported in `message`. Use `POST /evaluations/fromSession` for a single session. See [Evaluations](https://docs.galtea.ai/concepts/product/version/session/evaluation).

> [!WARNING]
>
> You are reading the docs of Galtea 5.10. [Read this page in the latest version](https://docs.galtea.ai/api-reference/evaluations/evaluate-multiple-sessions-in-one-call.md).


## OpenAPI

````yaml /v5.10/openapi.json post /evaluations/fromSessions
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:
  /evaluations/fromSessions:
    post:
      tags:
        - evaluations
      summary: Evaluate multiple sessions in one call
      description: >-
        Batch-evaluate existing sessions in a single call. Pick exactly one
        mode: (a) `sessionIds` — explicit list of session IDs; (b) `versionId` —
        every session attached to that version. Each selected session is
        evaluated by the same logic as `POST /evaluations/fromSession`, so the
        traces that already live on the session are scored. Unlike `POST
        /evaluations/fromVersion`, this endpoint does NOT require a conversation
        endpoint connection on the version — use it when the traces already
        exist (e.g. imported ones). Metric scope: if you send `metrics`, they
        are applied to every session. If you do not send `metrics`, each session
        is scored only by the metrics of its own originating specification (the
        spec that produced its test case), never the union of all the product's
        metrics. A session with no spec of its own (for example an imported one)
        is scored with the metrics of every spec of its product. When you send
        `specificationIds`, a session whose own spec is in the list is scored
        with that spec's metrics, and a session whose own spec is not in the
        list is skipped. A session with no spec of its own is then scored with
        the metrics of the listed specs of its own product, each metric once,
        and is skipped when there are none. Skipped sessions are reported in
        `message`. Use `POST /evaluations/fromSession` for a single session. See
        [Evaluations](https://docs.galtea.ai/concepts/product/version/session/evaluation).
      operationId: createEvaluationsFromSessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEvaluationsFromSessionsBody'
      responses:
        '200':
          description: Batch evaluation processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluateSessionsResult'
        '400':
          description: >-
            Bad request — malformed input (e.g. both sessionIds and versionId
            provided, neither provided, empty sessionIds, wrong types, or a
            runId in the body) or a versionId that exists but has zero sessions
            to evaluate. A mistake in explicit `metrics` (an unknown metric, a
            metric of another organization than the product's, or a self-hosted
            metric without a score) is also a 400, with no run or evaluation
            written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The caller may not create evaluations on a product of these sessions
            (for example a READER). No evaluation is written.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            One or more of the requested entities was not found: the versionId
            does not exist or is not visible to the caller, or one or more
            sessionIds do not exist or are not visible to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateEvaluationsFromSessionsBody:
      type: object
      properties:
        sessionIds:
          type: array
          nullable: true
          items:
            type: string
          example:
            - ses_123
            - ses_456
          description: >-
            Explicit list of session IDs to evaluate. Mutually exclusive with
            versionId.
        versionId:
          type: string
          nullable: true
          example: ver_123
          description: >-
            Evaluate every session attached to this version. Mutually exclusive
            with sessionIds.
        metrics:
          type: array
          nullable: true
          items:
            type: object
            properties:
              id:
                type: string
                example: id_123
              name:
                type: string
                example: Example Name
              score:
                type: number
                example: 0.95
          description: >-
            Metrics to evaluate. When provided, these exact metrics are applied
            to every session and per-specification scoping is bypassed.
            Optional: if omitted, each session is scored by the metrics of its
            own originating specification.
        specificationIds:
          type: array
          nullable: true
          items:
            type: string
          description: >-
            Specification IDs used to scope evaluation. If `metrics` is omitted,
            a session whose own specification is in the list is evaluated with
            that specification's linked metrics, and a session whose own
            specification is not in the list is skipped. A session with no
            specification of its own (for example an imported one) is evaluated
            with the linked metrics of the listed specifications of its own
            product, each metric once, and is skipped when there are none. If
            `metrics` is also provided, the explicit metrics apply to every
            session and these specs' metrics are merged in (additive), with no
            per-session scoping.
    EvaluateSessionsResult:
      type: object
      properties:
        sessionsEvaluated:
          type: integer
          description: >-
            Number of sessions whose evaluations were dispatched successfully.
            Sessions skipped during per-specification scoping are counted in
            neither this nor sessionsFailed.
        sessionsFailed:
          type: integer
          description: Number of sessions whose evaluation failed.
        evaluationsCreated:
          type: integer
          description: >-
            Total number of Evaluation records created across all successful
            sessions.
        failures:
          type: array
          items:
            type: object
            properties:
              sessionId:
                type: string
              error:
                type: string
            required:
              - sessionId
              - error
          description: Per-session failure details.
        message:
          type: string
          description: >-
            Human-readable summary. Reports how many sessions were evaluated,
            failed, and skipped during per-specification scoping, naming each
            skip cause with its own count and reason, plus any truncation note.
        totalSessionsAvailable:
          type: integer
          nullable: true
          description: >-
            Total sessions matching the request (versionId mode only). When
            greater than the count actually evaluated the response was truncated
            to the first 1000 rows. `null` in sessionIds mode.
        truncated:
          type: boolean
          description: >-
            True when the version had more sessions than the per-request page
            limit (1000).
        runIds:
          type: array
          items:
            type: string
          description: >-
            The runs this launch is attributed to, one per product the sessions
            belong to.
      required:
        - sessionsEvaluated
        - sessionsFailed
        - evaluationsCreated
        - failures
        - message
        - totalSessionsAvailable
        - truncated
        - runIds
    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.