> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: "Create an experiment"
description: "Create an experiment against a dataset."
method: "POST"
endpoint: "/api/v1/projects/:projectId/experiments"
order: 2
group: "Manage experiments"
last_verified: 2026-07-27
---

<ApiEndpoint method="POST" endpoint="/api/v1/projects/:projectId/experiments" description="Create an experiment against a dataset.">
  <section>
    #### Body parameters
    <ApiAttribute name="dataset_id" type="string" description="The dataset to run against." required={true} />
    <ApiAttribute name="name" type="string" description="The experiment's name." required={true} />
    <ApiAttribute name="type" type="string" description="evaluation, comparison, or ablation." required={true} />
    <ApiAttribute name="target_type" type="string" description="What's under test: component, deployment, or prompt." required={false} />
    <ApiAttribute name="component_name" type="string" description="The function, workflow, or agent to invoke, when target_type is component." required={false} />
    <ApiAttribute name="deployment_id" type="string" description="The deployment to invoke, when target_type is deployment." required={false} />
    <ApiAttribute name="prompt_id" type="string" description="The prompt to evaluate, when target_type is prompt." required={false} />
    <ApiAttribute name="repetitions" type="integer" description="How many times to run each dataset item." required={false} />
    <ApiAttribute name="scorer_ids" type="array" description="Custom scorer UUIDs to apply to every result." required={false} />
    <ApiAttribute name="builtin_scorers" type="array" description="AGNT5-owned built-in scorers to apply — bare names like exact_match, or name/config objects for scorers that need config, e.g. json_schema, numeric_range, llm_judge. Both forms can be mixed in the same array." required={false} />
  </section>

  <Callout type="info">
Specify built-in scorers with `builtin_scorers` or with `config.builtin_scorers` — not both; sending both is a `400`. A builtin that needs config but is sent as a bare name (e.g. `json_schema` without a `schema`) is also a `400`, naming the missing config field.
  </Callout>
</ApiEndpoint>