---
title: "POST /evaluations/batch-evaluate"
method: POST
path: "/evaluations/batch-evaluate"
---

# POST /evaluations/batch-evaluate

`POST /evaluations/batch-evaluate`

Starts a batch evaluation job that evaluates agent performance across multiple sessions. Batch evaluations pull agent traces from CloudWatch Logs or an existing online evaluation configuration and run specified evaluators and insights against them.

## Request body

- object
  - `batchEvaluationName` string, required — A human-readable name for a batch evaluation.
  - `evaluators` Evaluator[] — The list of evaluators to apply during the batch evaluation. Can include both built-in evaluators and custom evaluators. Maximum of 10 evaluators.
    - `evaluatorId` string, required — The unique identifier of the evaluator. Can reference built-in evaluators (e.g., <code>Builtin.Helpfulness</code>) or custom evaluators.
  - `insights` Insight[] — The list of insight analyses to run against sessions during the batch evaluation. Maximum of 10 insights.
    - `insightId` string, required — The unique identifier of the insight to run.
  - `dataSourceConfig` object, required — Configuration for the data source used in evaluation.
    - `cloudWatchLogs` object — Configuration for pulling agent session traces from CloudWatch Logs.
      - `serviceNames` String[], required — The list of agent service names to filter traces within the specified log groups.
      - `logGroupNames` String[], required — The list of CloudWatch log group names to read agent traces from. Maximum of 5 log groups.
      - `filterConfig` object — Optional filter configuration to narrow down which sessions to evaluate.
        - `sessionIds` String[] — A list of specific session IDs to evaluate. If specified, only these sessions are included in the evaluation.
        - `timeRange` object — The time range filter for selecting sessions to evaluate.
          - `startTime` string, date-time — The start time of the time range. Only sessions with activity at or after this timestamp are included.
          - `endTime` string, date-time — The end time of the time range. Only sessions with activity before this timestamp are included.
    - `onlineEvaluationConfigSource` object — Reference an existing OnlineEvaluationConfig as session source
      - `onlineEvaluationConfigArn` string, required — The Amazon Resource Name (ARN) of the online evaluation configuration to use as the session source.
      - `timeRange` object — Optional session filter configuration to narrow down which sessions from the online evaluation configuration to include.
        - `startTime` string, date-time — The start time of the time range. Only sessions with activity at or after this timestamp are included.
        - `endTime` string, date-time — The end time of the time range. Only sessions with activity before this timestamp are included.
  - `clientToken` string — A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If this token matches a previous request, the service ignores the request, but does not return an error.
  - `evaluationMetadata` object — Metadata for the evaluation, including session-specific ground truth data.
    - `sessionMetadata` SessionMetadataShape[] — A list of session metadata entries containing ground truth data and test scenario identifiers for specific sessions.
      - `sessionId` string, required — The unique identifier of the session this metadata applies to.
      - `testScenarioId` string — An optional test scenario identifier for categorizing and tracking evaluation results.
      - `groundTruth` object — The ground truth data for this session, including expected responses and assertions.
        - `inline` object — Inline ground truth data provided directly in the request.
          - `assertions` EvaluationContent[] — Assertions for evaluation, reuses common model EvaluationContentList.
            - `text` string — The text content of the ground truth data. Used for expected response text and assertion statements.
          - `expectedTrajectory` object — The expected tool call sequence for trajectory evaluation.
            - `toolNames` EvaluationToolName[] — The list of tool names representing the expected tool call sequence.
          - `turns` GroundTruthTurn[] — A list of per-turn ground truth data, each containing an input prompt and expected response.
            - `input` object — The input for this conversation turn.
              - …
            - `expectedResponse` object — The expected response for this conversation turn.
              - …
      - `metadata` object — Additional key-value metadata associated with this session.
  - `tags` object — A map of tag keys and values to associate with the batch evaluation.
  - `kmsKeyArn` string — The ARN of the KMS key used to encrypt evaluation data. If provided, customer data is encrypted at rest with the specified key.
  - `description` string — The description of the batch evaluation.

## Response `202`

Success

- StartBatchEvaluationResponse
  - `batchEvaluationId` string, required — The unique identifier of the created batch evaluation.
  - `batchEvaluationArn` string, required — The Amazon Resource Name (ARN) of the created batch evaluation.
  - `batchEvaluationName` string, required — The name of the batch evaluation.
  - `evaluators` Evaluator[] — The list of evaluators applied during the batch evaluation.
    - `evaluatorId` string, required — The unique identifier of the evaluator. Can reference built-in evaluators (e.g., <code>Builtin.Helpfulness</code>) or custom evaluators.
  - `insights` Insight[] — The list of insight analyses applied during the batch evaluation.
    - `insightId` string, required — The unique identifier of the insight to run.
  - `status` 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'STOPPING' | 'STOPPED' | 'DELETING', required — The status of the batch evaluation.
  - `createdAt` string, date-time, required — The timestamp when the batch evaluation was created.
  - `outputConfig` object — The output configuration specifying where evaluation results are written.
    - `cloudWatchConfig` object — The CloudWatch Logs configuration for writing evaluation results.
      - `logGroupName` string, required — The name of the CloudWatch log group where evaluation results will be written.
      - `logStreamName` string, required — The name of the CloudWatch log stream where evaluation results will be written.
  - `tags` object — The tags associated with the batch evaluation.
  - `kmsKeyArn` string — The ARN of the KMS key used to encrypt evaluation data.
  - `description` string — The description of the batch evaluation.

## Other responses

- `480` — ServiceQuotaExceededException
- `481` — UnauthorizedException
- `482` — ValidationException
- `483` — AccessDeniedException
- `484` — ConflictException
- `485` — ThrottlingException
- `486` — InternalServerException

---

[API](https://skmtc.net/aws/apis/bedrock-agentcore.md) · [All operations](https://skmtc.net/aws/apis/bedrock-agentcore/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/bedrock-agentcore/versions/79623b33d495/schema)