Skip to main content
POST
Create Experiment

Overview

Starts an A/B experiment that sends traffic_percentage percent of the agent’s eligible traffic to variant_version_id, with the rest running the version pinned to baseline_env. Eligible traffic is:
  • Send Call requests with agent_id and no agent_version. Any explicit agent_version, including production, keeps the call out of the experiment.
  • Inbound calls to numbers attached to the agent on production, when the number runs on Bland’s shared infrastructure. Numbers attached on staging never enter an experiment.
  • New text conversations on numbers attached on production. A conversation keeps the version it was assigned for its whole life.
Send Call requests that a migration split routes to the agent are eligible only while the split is at 100% and no rollout drives it. Inbound calls that a migration split routes to the agent never are. An agent has at most one active experiment: stop it with Stop Experiment before creating another, or adjust it in place with Update Experiment. 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. Experiments are available on enterprise plans. Every experiment endpoint returns 403 ENTERPRISE_REQUIRED for other organizations. This endpoint also requires an admin, owner, operator, or prompter role.

Headers

string
required
Your API key for authentication.

Path Parameters

string
required
The agent’s unique identifier.

Body Parameters

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.
integer
required
Share of eligible calls routed to the variant, 1 to 100. The remainder runs the baseline pin.
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.
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.
string
required
An IANA timezone name such as America/Chicago. Returns 400 BAD_REQUEST for an unknown name.
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.
string | null
default:"null"
ISO 8601 datetime. The variant receives no traffic before this time. null starts immediately.
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.
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. An outbound call answered by voicemail or an answering machine counts. Each new text conversation assigned to the variant also counts as one. null means no cap.

Response

object
The new experiment, in active status.
null | array
null on success, or a list of error objects if the request failed.
Docs for agents: llms.txt