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

# Create Experiment

> Start an A/B experiment on a variant version.

### Overview

Starts an A/B experiment that sends `traffic_percentage` percent of the agent's eligible calls to `variant_version_id`, with the rest running the version pinned to `baseline_env`. Only calls that do not explicitly select a version or environment are eligible. An agent has at most one active experiment: stop it with [Stop Experiment](https://docs.bland.ai/api-v2/post/agents-id-experiments-experiment-id-stop.md) before creating another, or adjust it in place with [Update Experiment](https://docs.bland.ai/api-v2/patch/agents-id-experiments-experiment-id.md). Returns `409 CONFLICT` while one is active.

An experiment completes on its own when `ends_at` passes, when `variant_call_quota` connected variant calls have been routed, or when the baseline environment is repointed to another version (for example by a publish or promote). Completion is permanent, and all eligible traffic returns to the baseline pin.

Requires an admin, owner, operator, or prompter role.

### Headers

**authorization** `string` *required*

Your API key for authentication.

### Path Parameters

**agent\_id** `string` *required*

The agent's unique identifier.

### Body Parameters

**variant\_version\_id** `string` *required*

The version to test. Must be a UUID, a version of this agent, and different from the baseline environment's current pin. The variant is prepared for live calls before the experiment is created, so a version that cannot run returns `400 BAD_REQUEST` here rather than failing on calls.

**traffic\_percentage** `integer` *required*

Share of eligible calls routed to the variant, `1` to `100`. The remainder runs the baseline pin.

**baseline\_env** `string` (default: production)

`production` or `staging`. The environment whose pinned version is the control arm. Returns `400 BAD_REQUEST` if that environment has no pinned version.

**run\_hours** `object | null` (default: null)

Weekly schedule during which the variant receives traffic, evaluated in `timezone` at each call so daylight-saving changes are handled automatically. Outside the schedule every eligible call runs the baseline. `null` means the variant is always eligible.

```json theme={null}
{
  "timezone": "America/New_York",
  "days": {
    "mon": { "start": "09:00", "end": "17:00" },
    "tue": { "start": "09:00", "end": "17:00" },
    "fri": { "start": "22:00", "end": "02:00" }
  }
}
```

**run\_hours.timezone** `string` *required*

An IANA timezone name such as `America/Chicago`. Returns `400 BAD_REQUEST` for an unknown name.

**run\_hours.days** `object` *required*

Keyed by `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`, with at least one day. Each value is `{ "start": "HH:mm", "end": "HH:mm" }` in 24-hour time, and `start` and `end` must differ. A day that is absent never routes to the variant. When `end` is earlier than `start`, the window wraps past midnight into the following day.

**starts\_at** `string | null` (default: null)

ISO 8601 datetime. The variant receives no traffic before this time. `null` starts immediately.

**ends\_at** `string | null` (default: null)

ISO 8601 datetime. The experiment completes with `completed_reason: "date_ended"` once this time passes. Must be in the future and, when `starts_at` is set, after it. `null` means no end date.

**variant\_call\_quota** `integer | null` (default: null)

Maximum connected variant calls, `1` to `1000000`. The experiment completes with `completed_reason: "quota_reached"` when the count is reached. Only calls that connect count, so unanswered outbound calls never consume quota. `null` means no cap.

### Response

**data.experiment** `object`

The new experiment, in `active` status.

**experiment object**

**id** `string`

Unique identifier for the experiment. Pass it as `{experiment_id}` on the other experiment endpoints.

**agent\_id** `string`

The agent the experiment belongs to.

**status** `string`

`active` on creation. Becomes `completed` when the experiment ends; completion is terminal.

**completed\_reason** `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).

**baseline\_env** `string`

The control environment: `production` or `staging`.

**baseline\_current\_version\_id** `string | null`

The version currently pinned to `baseline_env`, read at request time. While the experiment is active this is the control arm.

**variant\_version\_id** `string`

The version under test.

**traffic\_percentage** `integer`

Share of eligible calls routed to the variant.

**run\_hours** `object | null`

The weekly schedule as submitted, or `null` when the variant is always eligible.

**starts\_at** `string | null`

When variant traffic begins, or `null` for immediately.

**ends\_at** `string | null`

When the experiment completes on its own, or `null` for no end date.

**variant\_call\_quota** `integer | null`

Maximum connected variant calls, or `null` for no cap.

**variant\_calls\_routed** `integer`

Connected calls routed to the variant so far. Always `0` on creation; live while active, frozen at completion.

**created\_by** `string | null`

ID of the user who created the experiment, or `null` when created with an org-level key.

**created\_at** `string`

ISO 8601 timestamp of creation.

**completed\_at** `string | null`

`null` while active.

**errors** `null | array`

`null` on success, or a list of error objects if the request failed.

```json Response theme={null}
{
  "data": {
    "experiment": {
      "id": "5c590769-b12c-4f5e-8608-85dd2ac29bb1",
      "agent_id": "4fdd0f5b-4416-42f6-bb85-fb42d3ceec29",
      "status": "active",
      "completed_reason": null,
      "baseline_env": "production",
      "baseline_current_version_id": "d717a103-f912-42f4-ae07-6a2a8b5395b0",
      "variant_version_id": "dc7c8387-c78e-4942-8190-b8899f31237d",
      "traffic_percentage": 20,
      "run_hours": {
        "timezone": "America/Chicago",
        "days": {
          "mon": { "start": "09:00", "end": "17:00" },
          "tue": { "start": "09:00", "end": "17:00" },
          "wed": { "start": "09:00", "end": "17:00" },
          "thu": { "start": "09:00", "end": "17:00" },
          "fri": { "start": "09:00", "end": "17:00" }
        }
      },
      "starts_at": null,
      "ends_at": "2026-09-24T00:00:00.000Z",
      "variant_call_quota": 500,
      "variant_calls_routed": 0,
      "created_by": "3ba21c4b-2b23-413d-8a09-1ce549a29391",
      "created_at": "2026-09-10T20:14:33.508Z",
      "completed_at": null
    }
  },
  "errors": null
}
```

```json Invalid Body theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "traffic_percentage must be an integer between 1 and 100"
    }
  ]
}
```

```json Variant Not Found theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "variant_version_id is not a version of this agent"
    }
  ]
}
```

```json Already Active theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "CONFLICT",
      "message": "This agent already has an active experiment — stop it first"
    }
  ]
}
```

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

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.