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

# Run evaluations

> Queues an evaluation for each listed session using the agent's current evaluation configuration.
Sessions that are not finished, do not belong to the agent, or already have an evaluation queued or running are skipped and reported.
Each queued evaluation consumes credits when it runs. A new result replaces the previous result for that session.

Requires edit access on the agent and a plan with evaluations enabled.




## OpenAPI

````yaml post /agents/{agent_id}/evaluations/run
openapi: 3.0.0
info:
  title: Public API
  version: 1.0.0
servers:
  - url: https://api.gumloop.com/api/v1
security: []
paths:
  /agents/{agent_id}/evaluations/run:
    post:
      tags:
        - Evaluations
      summary: Run evaluations
      description: >
        Queues an evaluation for each listed session using the agent's current
        evaluation configuration.

        Sessions that are not finished, do not belong to the agent, or already
        have an evaluation queued or running are skipped and reported.

        Each queued evaluation consumes credits when it runs. A new result
        replaces the previous result for that session.


        Requires edit access on the agent and a plan with evaluations enabled.
      operationId: runEvaluations
      parameters:
        - in: path
          name: agent_id
          required: true
          schema:
            type: string
          description: ID of the agent that owns the sessions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - session_ids
              properties:
                session_ids:
                  type: array
                  minItems: 1
                  maxItems: 200
                  items:
                    type: string
                  description: Sessions to evaluate. Duplicates are ignored.
            example:
              session_ids:
                - int_xyz789
                - int_abc123
      responses:
        '202':
          description: Evaluations queued.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - queued
                  queued:
                    type: integer
                    description: Number of evaluations queued.
                  skipped:
                    type: object
                    properties:
                      ineligible:
                        type: array
                        items:
                          type: string
                        description: >-
                          Sessions that are unfinished, incognito, or not owned
                          by this agent.
                      in_flight:
                        type: array
                        items:
                          type: string
                        description: >-
                          Sessions that already have an evaluation queued or
                          running.
              example:
                status: queued
                queued: 1
                skipped:
                  ineligible:
                    - int_abc123
                  in_flight: []
        '400':
          description: >-
            Invalid request, evaluations not configured for this agent
            (`evaluations_not_configured`), or no eligible sessions
            (`no_valid_interactions`).
        '401':
          description: Unauthorized — missing or invalid credentials.
        '402':
          description: Not enough credits to run the requested evaluations.
        '403':
          description: >-
            Forbidden — insufficient permissions on this agent, or evaluations
            are not available on your plan.
        '404':
          description: Agent not found.
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >
            curl -X POST
            'https://api.gumloop.com/api/v1/agents/AGENT_ID/evaluations/run' \
              -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{"session_ids": ["SESSION_ID_1", "SESSION_ID_2"]}'
        - lang: python
          label: Python
          source: |
            import requests

            response = requests.post(
                "https://api.gumloop.com/api/v1/agents/AGENT_ID/evaluations/run",
                headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
                json={"session_ids": ["SESSION_ID_1", "SESSION_ID_2"]},
            )
            data = response.json()
            print(data["queued"], data["skipped"])
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A personal API key or an [OAuth 2.0](/api-reference/oauth) access token.
        Personal API keys also require the `x-auth-key` header with your user
        ID.

````