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

# Update Experiment

> Adjust an active experiment's split or conditions.

### Overview

Changes an active experiment's traffic split, schedule, dates, or quota. The variant and baseline are fixed for the experiment's life; to test a different version, [stop it](https://docs.bland.ai/api-v2/post/agents-id-experiments-experiment-id-stop.md) and [create a new one](https://docs.bland.ai/api-v2/post/agents-id-experiments.md). Only the fields below are accepted: any other key returns `400 BAD_REQUEST`, and so does an empty body. Completed experiments cannot be edited and return `409 CONFLICT`, as does a second update that arrives while one is still being applied (retry it).

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.

**experiment\_id** `string` *required*

The experiment's unique identifier. Must be a valid UUID; returns `400 BAD_REQUEST` otherwise.

### Body Parameters

Send at least one field. Fields you omit keep their current value.

**traffic\_percentage** `integer`

New share of eligible calls routed to the variant, `1` to `100`. Use this to ramp the variant up or down.

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

New weekly schedule, with the same shape and rules as on [Create Experiment](https://docs.bland.ai/api-v2/post/agents-id-experiments.md): an IANA `timezone` and a `days` object keyed `mon` through `sun` whose values are `{ "start": "HH:mm", "end": "HH:mm" }` windows. Pass `null` to remove the schedule and make the variant always eligible.

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

ISO 8601 datetime before which the variant receives no traffic. Pass `null` to clear it.

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

ISO 8601 datetime at which the experiment completes with `date_ended`. Must be in the future and after the effective `starts_at` (the one in this request, or the stored one if not sent). Pass `null` to remove the end date.

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

New cap on connected variant calls, `1` to `1000000`, or `null` for no cap. Lowering it to or below the current `variant_calls_routed` completes the experiment immediately with `quota_reached`, and the response reflects that.

### Response

**data.experiment** `object`

The experiment after the update.

**experiment object**

**id** `string`

Unique identifier for the experiment.

**agent\_id** `string`

The agent the experiment belongs to.

**status** `string`

`active`, or `completed` if the update lowered the quota below the routed count.

**completed\_reason** `string | null`

`null` while active; `quota_reached` if this update completed the experiment.

**baseline\_env** `string`

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

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

The version currently pinned to `baseline_env`, read at request time.

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

The version under test. Not editable.

**traffic\_percentage** `integer`

The current share of eligible calls routed to the variant.

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

The current weekly schedule, or `null` when 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`

The current cap on connected variant calls, or `null` for no cap.

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

Connected calls routed to the variant so far.

**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": "f4e3870b-7e35-4088-9855-917de3633c54",
      "agent_id": "ff4b135e-2a7e-48e3-9e75-1303718b2f9d",
      "status": "active",
      "completed_reason": null,
      "baseline_env": "production",
      "baseline_current_version_id": "41cf1621-96cc-4f7c-8f9c-a8456b65b9fe",
      "variant_version_id": "82a83fe3-719f-45f8-9207-4424aac1a26d",
      "traffic_percentage": 50,
      "run_hours": null,
      "starts_at": null,
      "ends_at": "2026-10-01T00:00:00.000Z",
      "variant_call_quota": 2000,
      "variant_calls_routed": 318,
      "created_by": "499bd008-10c1-4fb9-841e-87e1961b5904",
      "created_at": "2026-09-08T12:40:19.221Z",
      "completed_at": null
    }
  },
  "errors": null
}
```

```json Invalid Body theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "BAD_REQUEST",
      "message": "\"variant_version_id\" is not an updatable field (allowed: traffic_percentage, run_hours, starts_at, ends_at, variant_call_quota)"
    }
  ]
}
```

```json Completed theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "CONFLICT",
      "message": "Completed experiments cannot be edited"
    }
  ]
}
```

```json Not Found theme={null}
{
  "data": null,
  "errors": [
    {
      "error": "NOT_FOUND",
      "message": "Experiment 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.