> ## 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: a session's specifications are the specifications its dataset links now. If you send `metrics`, they are applied to every session. If you do not send `metrics`, each session is scored by the metrics linked to its own specifications, each metric once, never the union of all the product's metrics. A session with no specification (for example an imported one) is scored with the metrics of every specification of its product. When you send `specificationIds`, a session is scored with the metrics of its specifications that are in the list, and a session with none of them in the list is skipped. A session with no specification is then scored with the metrics of the listed specifications 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.13. [Read this page in the latest version](https://docs.galtea.ai/api-reference/evaluations/evaluate-multiple-sessions-in-one-call.md).


## OpenAPI

````yaml /v5.13/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: a session's specifications are
        the specifications its dataset links now. If you send `metrics`, they
        are applied to every session. If you do not send `metrics`, each session
        is scored by the metrics linked to its own specifications, each metric
        once, never the union of all the product's metrics. A session with no
        specification (for example an imported one) is scored with the metrics
        of every specification of its product. When you send `specificationIds`,
        a session is scored with the metrics of its specifications that are in
        the list, and a session with none of them in the list is skipped. A
        session with no specification is then scored with the metrics of the
        listed specifications 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 linked
            to the specifications its dataset links now, each metric once.
        specificationIds:
          type: array
          nullable: true
          items:
            type: string
          description: >-
            Specification IDs used to scope evaluation. If `metrics` is omitted,
            a session is evaluated with the linked metrics of its specifications
            that are in the list, and a session with none of them in the list is
            skipped. A session with no specification (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.