---
title: "Launch an eval"
method: POST
path: "/v1/eval"
tags: ["Evals"]
---

# Launch an eval

`POST /v1/eval`

Launch an evaluation. This is the API-equivalent of the `Eval` function that is built into the Braintrust SDK. In the Eval API, you provide pointers to a dataset, task function, and scoring functions. The API will then run the evaluation, create an experiment, and return the results along with a link to the experiment. To learn more about evals, see the [Evals guide](https://www.braintrust.dev/docs/guides/evals).

## Request body

- object
  - `project_id` string, required — Unique identifier for the project to run the eval in
  - `data` union, required — The dataset to use
    - object — Dataset id
      - `dataset_id` string, required
    - object — Project and dataset name
      - `project_name` string, required
      - `dataset_name` string, required
  - `task` union, required — The function to evaluate
    - object — Function id
      - `function_id` string, required — The ID of the function
      - `version` string — The version of the function
    - object — Project name and slug
      - `project_name` string, required — The name of the project containing the function
      - `slug` string, required — The slug of the function
      - `version` string — The version of the function
    - object — Global function name
      - `global_function` string, required — The name of the global function. Currently, the global namespace includes the functions in autoevals
    - object — Prompt session id
      - `prompt_session_id` string, required — The ID of the prompt session
      - `prompt_session_function_id` string, required — The ID of the function in the prompt session
      - `version` string — The version of the function
    - object — Inline code function
      - `inline_context` object, required
        - `runtime` 'node' | 'python', required
        - `version` string, required
      - `code` string, required — The inline code to execute
  - `scores` union[], required — The functions to score the eval on
    - union — Options for identifying a function
      - object — Function id
        - `function_id` string, required — The ID of the function
        - `version` string — The version of the function
      - object — Project name and slug
        - `project_name` string, required — The name of the project containing the function
        - `slug` string, required — The slug of the function
        - `version` string — The version of the function
      - object — Global function name
        - `global_function` string, required — The name of the global function. Currently, the global namespace includes the functions in autoevals
      - object — Prompt session id
        - `prompt_session_id` string, required — The ID of the prompt session
        - `prompt_session_function_id` string, required — The ID of the function in the prompt session
        - `version` string — The version of the function
      - object — Inline code function
        - `inline_context` object, required
          - `runtime` 'node' | 'python', required
          - `version` string, required
        - `code` string, required — The inline code to execute
  - `experiment_name` string — An optional name for the experiment created by this eval. If it conflicts with an existing experiment, it will be suffixed with a unique identifier.
  - `metadata` object — Optional experiment-level metadata to store about the evaluation. You can later use this to slice & dice across experiments.
  - `stream` boolean — Whether to stream the results of the eval. If true, the request will return two events: one to indicate the experiment has started, and another upon completion. If false, the request will return the evaluation's summary upon completion.

## Response `200`

Eval launch response

- SummarizeExperimentResponse — Summary of an experiment
  - `project_name` string, required — Name of the project that the experiment belongs to
  - `experiment_name` string, required — Name of the experiment
  - `project_url` string, uri, required — URL to the project's page in the Braintrust app
  - `experiment_url` string, uri, required — URL to the experiment's page in the Braintrust app
  - `comparison_experiment_name` string, nullable — The experiment which scores are baselined against
  - `scores` object, nullable — Summary of the experiment's scores
  - `metrics` object, nullable — Summary of the experiment's metrics

## Changes

- **2024-09-21** `1e677afe2f7b` — 2 info
  - added `subschema #5` to the `scores/items/` request property `anyOf` list
  - added `subschema #5` to the `task` request property `anyOf` list
- **2024-07-30** `9635568dd298` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/v1/eval/post.md)

---

[API](https://skmtc.dev/braintrustdata/apis/braintrust-api.md) · [All operations](https://skmtc.dev/braintrustdata/apis/braintrust-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/braintrustdata/braintrust-api/revisions/35ca662bf690/schema)