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

# Evaluate a dataset

> Run one evaluator across a saved dataset and record the result against an experiment. Name the dataset by slug and the evaluator the same way the evaluate endpoints do; results are grouped under `experimentSlug`, or under a generated batch id when you omit it.



## OpenAPI

````yaml POST /api/dataset/evaluate
openapi: 3.1.0
info:
  title: LangWatch API
  version: 1.0.0
  description: LangWatch openapi spec
servers:
  - url: https://app.langwatch.ai
security:
  - project_api_key: []
paths:
  /api/dataset/evaluate:
    post:
      tags:
        - Datasets
      summary: Evaluate a dataset
      description: >-
        Run one evaluator across a saved dataset and record the result against
        an experiment. Name the dataset by slug and the evaluator the same way
        the evaluate endpoints do; results are grouped under `experimentSlug`,
        or under a generated batch id when you omit it.
      operationId: postApiDatasetEvaluate
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                evaluation:
                  type: string
                  description: >-
                    Which evaluator to run, addressed the same way the evaluate
                    endpoints address it
                datasetSlug:
                  type: string
                  description: The saved dataset to evaluate
                experimentSlug:
                  type: string
                  description: >-
                    Groups the results under an experiment. Omit it and a batch
                    id is generated instead.
                batchId:
                  type: string
                  description: Older name for experimentSlug, used when that is absent
                data:
                  type: object
                  additionalProperties: {}
                  nullable: true
                  description: Extra fields merged into every row before evaluating
                settings:
                  type: object
                  additionalProperties: {}
                  nullable: true
                  description: Per-call overrides of the evaluator's settings
              required:
                - evaluation
                - datasetSlug
              additionalProperties: false
      responses:
        '200':
          description: The evaluator ran; branch on `status`
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      status:
                        type: string
                        const: processed
                      score:
                        type: number
                      passed:
                        type: boolean
                      label:
                        type: string
                      details:
                        type: string
                      cost:
                        type: object
                        properties:
                          currency:
                            type: string
                          amount:
                            type: number
                        required:
                          - currency
                          - amount
                        description: What running the evaluator cost
                      raw_response:
                        description: The evaluator's own output, unprocessed
                    required:
                      - status
                  - type: object
                    properties:
                      status:
                        type: string
                        const: skipped
                      details:
                        type: string
                        description: Why the evaluator declined to score this input
                      passed:
                        type: boolean
                        description: >-
                          Always true in guardrail mode, so a skip does not
                          block
                    required:
                      - status
                  - type: object
                    properties:
                      status:
                        type: string
                        const: error
                      error_type:
                        type: string
                        const: EVALUATOR_ERROR
                        description: 'Constant: the evaluator''s own type is not exposed'
                      details:
                        type: string
                      passed:
                        type: boolean
                        description: >-
                          Always true in guardrail mode, so a failure does not
                          block
                    required:
                      - status
                      - error_type
                      - details
        '400':
          description: >-
            The body was not valid JSON, failed validation, or named an
            evaluator that does not exist
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Set when the request was rejected before validation
                  error:
                    type: string
                    description: Set when the body parsed and then failed validation
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Set when the request was rejected before validation
                  error:
                    type: string
                    description: Set when the body parsed and then failed validation
        '403':
          description: The API key lacks evaluations:manage
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The failure, as a sentence
                  kind:
                    type: string
                    description: Stable failure code, on the failures that carry one
                  meta:
                    type: object
                    additionalProperties: {}
                    description: >-
                      What the code needs to be acted on, such as the missing
                      field
                required:
                  - error
        '404':
          description: No dataset with that slug
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: The failure, as a sentence
                  kind:
                    type: string
                    description: Stable failure code, on the failures that carry one
                  meta:
                    type: object
                    additionalProperties: {}
                    description: >-
                      What the code needs to be acted on, such as the missing
                      field
                required:
                  - error
components:
  securitySchemes:
    project_api_key:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        Project API key for sending traces and accessing project-scoped
        resources. Format: sk-lw-... (no underscore). Obtain one by creating a
        project via the Admin API or the LangWatch UI.

````