> ## 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.

# Get Experiment

> Retrieve one experiment and its live progress.

### Overview

Returns one experiment. For an active experiment, `variant_calls_routed` is the live count of connected variant calls, so poll this endpoint to track progress toward `variant_call_quota`. An active experiment whose `ends_at` has passed is completed with `date_ended` before it is returned. Use [List Experiments](/api-v2/get/agents-id-experiments) to find experiment IDs.

### 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>

<ParamField path="experiment_id" type="string" required>
  The experiment's unique identifier. Must be a valid UUID; returns `400 BAD_REQUEST` otherwise.
</ParamField>

### Response

<ResponseField name="data.experiment" type="object">
  The experiment.

  <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. While the experiment is active this is the control arm; for a completed experiment it 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 during which the variant receives traffic, or `null` when always eligible. `timezone` is an IANA name; `days` maps `mon` through `sun` to `{ "start": "HH:mm", "end": "HH:mm" }` windows in that timezone. A window whose `end` is earlier than its `start` wraps past midnight.
    </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": {
      "experiment": {
        "id": "49ed2bc3-e876-4ac2-8893-fa56eeed1982",
        "agent_id": "abb3f6e7-663d-4afd-8006-2e46480af324",
        "status": "active",
        "completed_reason": null,
        "baseline_env": "production",
        "baseline_current_version_id": "99ab6abb-fbf4-4cf8-b837-23534442ae13",
        "variant_version_id": "5dcfc5e9-f339-437f-b7d5-7316c27fa223",
        "traffic_percentage": 30,
        "run_hours": {
          "timezone": "Europe/London",
          "days": {
            "mon": { "start": "08:30", "end": "18:00" },
            "tue": { "start": "08:30", "end": "18:00" },
            "wed": { "start": "08:30", "end": "18:00" },
            "thu": { "start": "08:30", "end": "18:00" },
            "fri": { "start": "08:30", "end": "18:00" }
          }
        },
        "starts_at": "2026-09-07T07:30:00.000Z",
        "ends_at": "2026-09-30T17:00:00.000Z",
        "variant_call_quota": 750,
        "variant_calls_routed": 262,
        "created_by": "9acd611b-dd69-4675-864d-a26e19e7e468",
        "created_at": "2026-09-05T16:11:27.043Z",
        "completed_at": null
      }
    },
    "errors": null
  }
  ```

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

***

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