---
title: "Create an LLM Observability experiment"
method: POST
path: "/api/v2/llm-obs/v1/experiments"
tags: ["LLM Observability"]
---

# Create an LLM Observability experiment

`POST /api/v2/llm-obs/v1/experiments`

Create a new LLM Observability experiment.

## Request body

- LLMObsExperimentRequest — Request to create an LLM Observability experiment.
  - `data` LLMObsExperimentDataRequest, required — Data object for creating an LLM Observability experiment.
    - `attributes` LLMObsExperimentDataAttributesRequest, required — Attributes for creating an LLM Observability experiment.
      - `config` object — Configuration parameters for the experiment.
      - `dataset_id` string — Identifier of the dataset used in this experiment.
      - `dataset_version` integer — Version of the dataset to use. Defaults to the current version if not specified.
      - `description` string — Description of the experiment.
      - `ensure_unique` boolean — Whether to ensure the experiment name is unique. Defaults to `true`.
      - `metadata` object — Arbitrary metadata associated with the experiment.
      - `name` string, required — Name of the experiment.
      - `parent_experiment_id` string — Identifier of the parent (baseline) experiment this experiment is run against.
      - `project_id` string, required — Identifier of the project this experiment belongs to.
      - `run_count` integer — Number of runs configured for this experiment.
    - `type` 'experiments', required — Resource type of an LLM Observability experiment.

## Response `200`

OK

- LLMObsExperimentResponse — Response containing a single LLM Observability experiment.
  - `data` LLMObsExperimentDataResponse, required — Data object for an LLM Observability experiment.
    - `attributes` LLMObsExperimentDataAttributesResponse, required — Attributes of an LLM Observability experiment.
      - `aggregate_data` object, nullable — Pre-computed aggregate metrics for this experiment run, including eval score distributions, token costs, and error rates.
      - `author` LLMObsExperimentUser — User data for the author of an experiment. Only present when `include[user_data]` is `true`.
        - `email` string — Email address of the user.
        - `handle` string — Username or handle associated with the user's Datadog account.
        - `icon` string — URL of the user's icon.
        - `id` string — Unique identifier of the user.
        - `name` string — Display name of the user.
      - `config` object, nullable, required — Configuration parameters for the experiment.
      - `created_at` string, date-time, required — Timestamp when the experiment was created.
      - `dataset_id` string, required — Identifier of the dataset used in this experiment.
      - `dataset_name` string, nullable — Name of the dataset used in this experiment. Only present when `include[dataset_names]` is `true`.
      - `dataset_version` integer — Version of the dataset used in this experiment.
      - `deleted_at` string, date-time, nullable — Timestamp when the experiment was soft-deleted, if applicable.
      - `description` string, nullable, required — Description of the experiment.
      - `error` string, nullable — Error message describing why the experiment failed, if applicable.
      - `experiment` string — Logical name of the experiment, shared across all runs of the same pipeline.
      - `metadata` object, nullable, required — Arbitrary metadata associated with the experiment.
      - `name` string, required — Name of the experiment.
      - `parent_experiment_id` string, nullable — Identifier of the parent (baseline) experiment this experiment was run against, if any.
      - `project_id` string, required — Identifier of the project this experiment belongs to.
      - `run_count` integer — Expected number of runs for this experiment.
      - `status` 'running' | 'completed' | 'failed' | 'interrupted' — Execution status of an LLM Observability experiment.
      - `updated_at` string, date-time, required — Timestamp when the experiment was last updated.
    - `id` string, required — Unique identifier of the experiment.
    - `type` 'experiments', required — Resource type of an LLM Observability experiment.

## Other responses

- `201` — Created
- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too many requests

---

[API](https://skmtc.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)