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

# List Experiments

> List an agent's experiments, newest first.

### Overview

Returns every experiment on the agent, active and completed, newest first. At most one is `active`. An active experiment whose `ends_at` has passed is completed with `date_ended` before it is returned, so the list never reports a stale active experiment. For a single experiment with its live progress, use [Get Experiment](/api-v2/get/agents-id-experiments-experiment-id).

### Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

### Path Parameters

<ParamField path="agent_id" type="string" required>
  The agent's unique identifier.
</ParamField>

### Response

<ResponseField name="data.experiments" type="array">
  Array of experiment objects, newest first.

  <Expandable title="experiment object">
    <ResponseField name="id" type="string">
      Unique identifier for the experiment.
    </ResponseField>

    <ResponseField name="agent_id" type="string">
      The agent the experiment belongs to.
    </ResponseField>

    <ResponseField name="status" type="string">
      `active` or `completed`. Completion is terminal.
    </ResponseField>

    <ResponseField name="completed_reason" type="string | null">
      `null` while active. On completion, one of `manual` (stopped through the API), `date_ended`, `quota_reached`, or `baseline_changed` (the baseline environment was repointed).
    </ResponseField>

    <ResponseField name="baseline_env" type="string">
      The control environment: `production` or `staging`.
    </ResponseField>

    <ResponseField name="baseline_current_version_id" type="string | null">
      The version currently pinned to `baseline_env`, read at request time. For a completed experiment this may no longer be the version it ran against.
    </ResponseField>

    <ResponseField name="variant_version_id" type="string">
      The version under test.
    </ResponseField>

    <ResponseField name="traffic_percentage" type="integer">
      Share of eligible calls routed to the variant, `1` to `100`.
    </ResponseField>

    <ResponseField name="run_hours" type="object | null">
      Weekly schedule (`timezone` plus per-day `{ start, end }` windows) during which the variant receives traffic, or `null` when always eligible.
    </ResponseField>

    <ResponseField name="starts_at" type="string | null">
      When variant traffic begins, or `null` for immediately.
    </ResponseField>

    <ResponseField name="ends_at" type="string | null">
      When the experiment completes on its own, or `null` for no end date.
    </ResponseField>

    <ResponseField name="variant_call_quota" type="integer | null">
      Maximum connected variant calls, or `null` for no cap.
    </ResponseField>

    <ResponseField name="variant_calls_routed" type="integer">
      Connected calls routed to the variant. Live while active, frozen at completion.
    </ResponseField>

    <ResponseField name="created_by" type="string | null">
      ID of the user who created the experiment, or `null` when created with an org-level key.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation.
    </ResponseField>

    <ResponseField name="completed_at" type="string | null">
      ISO 8601 timestamp of completion, or `null` while active.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="errors" type="null | array">
  `null` on success, or a list of error objects if the request failed.
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": {
      "experiments": [
        {
          "id": "90384992-15ea-43bb-9656-fa76b5f15bc8",
          "agent_id": "ee8fcf53-b284-4356-8942-63445fd42b7e",
          "status": "active",
          "completed_reason": null,
          "baseline_env": "production",
          "baseline_current_version_id": "b062d11d-7da4-4560-aad8-9f494e945fbb",
          "variant_version_id": "7350f8e0-8b2e-40d5-9365-34318282afdc",
          "traffic_percentage": 10,
          "run_hours": null,
          "starts_at": null,
          "ends_at": null,
          "variant_call_quota": null,
          "variant_calls_routed": 137,
          "created_by": "4cabf114-62e5-4cc4-a676-8890d0c19173",
          "created_at": "2026-09-09T08:30:12.640Z",
          "completed_at": null
        },
        {
          "id": "de11a8bf-3222-4dca-bbfb-e0ad5e8927fa",
          "agent_id": "ee8fcf53-b284-4356-8942-63445fd42b7e",
          "status": "completed",
          "completed_reason": "baseline_changed",
          "baseline_env": "production",
          "baseline_current_version_id": "b062d11d-7da4-4560-aad8-9f494e945fbb",
          "variant_version_id": "9a838897-bb5c-4131-9db3-3e24fca4603e",
          "traffic_percentage": 25,
          "run_hours": null,
          "starts_at": null,
          "ends_at": "2026-09-15T00:00:00.000Z",
          "variant_call_quota": 1000,
          "variant_calls_routed": 412,
          "created_by": "4cabf114-62e5-4cc4-a676-8890d0c19173",
          "created_at": "2026-08-28T13:02:51.115Z",
          "completed_at": "2026-09-08T17:45:09.882Z"
        }
      ]
    },
    "errors": null
  }
  ```

  ```json Not Found theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "NOT_FOUND",
        "message": "Agent not found"
      }
    ]
  }
  ```
</ResponseExample>

***

Docs for agents: [llms.txt](/llms.txt)