--- 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 - RunEval - `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 - `name` string, nullable — The name of the inline code function - object — Inline prompt definition - `inline_prompt` PromptData, nullable, required — The prompt, model, and its parameters - `prompt` union - object - `type` 'completion', required - `content` string, required - object - `type` 'chat', required - `messages` ChatCompletionMessageParam[], required - … - `tools` string - object, nullable - `options` object, nullable - `model` string - `params` union - object - … - object - … - object - … - object - … - object - … - `position` string - `parser` object, nullable - `type` 'llm_classifier', required - `use_cot` boolean, required - `choice_scores` object, required - `tool_functions` SavedFunctionId[], nullable - union - object - … - object - … - `origin` object, nullable - `prompt_id` string - `project_id` string - `prompt_version` string - `name` string, nullable — The name of the inline prompt - `scores` union[], required — The functions to score the eval on - union - object — Options for identifying a function - `function_id` string, required — The ID of the function - `version` string — The version of the function - object — Options for identifying a function - `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 — Options for identifying a function - `global_function` string, required — The name of the global function. Currently, the global namespace includes the functions in autoevals - object — Options for identifying a function - `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 — Options for identifying a function - `inline_context` object, required - `runtime` 'node' | 'python', required - `version` string, required - `code` string, required — The inline code to execute - `name` string, nullable — The name of the inline code function - object — Options for identifying a function - `inline_prompt` PromptData, nullable, required — The prompt, model, and its parameters - `prompt` union - object - … - object - … - object, nullable - `options` object, nullable - `model` string - `params` union - … - `position` string - `parser` object, nullable - `type` 'llm_classifier', required - `use_cot` boolean, required - `choice_scores` object, required - `tool_functions` SavedFunctionId[], nullable - union - … - `origin` object, nullable - `prompt_id` string - `project_id` string - `prompt_version` string - `name` string, nullable — The name of the inline prompt - `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 --- [API](https://skmtc.net/braintrustdata/apis/braintrust-api.md) · [All operations](https://skmtc.net/braintrustdata/apis/braintrust-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/braintrustdata/braintrust-api/revisions/9d216c8243fe/schema)