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

# Stop Experiment

> End an active experiment and return traffic to baseline.

### Overview

Completes an active experiment with `completed_reason: "manual"`. Eligible calls immediately return to the baseline pin, and the final `variant_calls_routed` count is frozen on the record. Completion is permanent: a stopped experiment cannot be resumed, so use [Create Experiment](/api-v2/post/agents-id-experiments) to test again. Returns `409 CONFLICT` if the experiment is already completed for any reason.

Requires an admin, owner, operator, or prompter role. This endpoint takes no body.

### 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 stopped 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 belonged to.
    </ResponseField>

    <ResponseField name="status" type="string">
      Always `completed` on success.
    </ResponseField>

    <ResponseField name="completed_reason" type="string">
      Always `manual` on success.
    </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`, which all eligible traffic now runs.
    </ResponseField>

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

    <ResponseField name="traffic_percentage" type="integer">
      The share of eligible calls the variant was receiving when stopped.
    </ResponseField>

    <ResponseField name="run_hours" type="object | null">
      The weekly schedule that was in effect, or `null`.
    </ResponseField>

    <ResponseField name="starts_at" type="string | null">
      The configured start, or `null`.
    </ResponseField>

    <ResponseField name="ends_at" type="string | null">
      The configured end date, or `null`.
    </ResponseField>

    <ResponseField name="variant_call_quota" type="integer | null">
      The configured cap, or `null`.
    </ResponseField>

    <ResponseField name="variant_calls_routed" type="integer">
      Final count of connected calls routed to the variant.
    </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">
      ISO 8601 timestamp of this stop.
    </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": "339da41c-429f-4a5b-81c5-5f33fe01a266",
        "agent_id": "b8c322a1-9498-4a20-abd0-78ab3957b7d8",
        "status": "completed",
        "completed_reason": "manual",
        "baseline_env": "staging",
        "baseline_current_version_id": "4f8eb28b-8d56-44bb-9297-afe154f5acea",
        "variant_version_id": "2adb110d-e30d-49db-9e68-1d0904e462e3",
        "traffic_percentage": 40,
        "run_hours": null,
        "starts_at": null,
        "ends_at": null,
        "variant_call_quota": null,
        "variant_calls_routed": 96,
        "created_by": "c52e0087-b404-46af-aa5f-073edb5a3913",
        "created_at": "2026-09-09T09:05:44.310Z",
        "completed_at": "2026-09-10T21:37:12.654Z"
      }
    },
    "errors": null
  }
  ```

  ```json Already Completed theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "CONFLICT",
        "message": "The experiment is already completed"
      }
    ]
  }
  ```

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

***

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