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

# List Agent Deployments

> List an environment's deployment history, newest first.

### Overview

Every publish, promote, and rollback appends a deployment to the target environment's history. This endpoint returns that history for one environment, newest first, with the latest check run recorded for each deployed version. Use `is_rollback_eligible` to find valid targets for [Roll Back Agent](/api-v2/post/agents-id-rollback).

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

### Query Parameters

<ParamField query="env" type="string" default="production">
  Environment to list: `dev`, `staging`, or `production`. Any other value falls back to `production`.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Maximum number of deployments to return. Minimum `1`, maximum `200`. Values outside that range are clamped; a non-numeric value falls back to `50`.
</ParamField>

### Response

<ResponseField name="data" type="array">
  Deployments for the requested environment, newest first.

  <Expandable title="deployment object">
    <ResponseField name="id" type="string">
      Unique identifier for the deployment.
    </ResponseField>

    <ResponseField name="env_type" type="string">
      The environment this deployment was made to. Matches the `env` query parameter.
    </ResponseField>

    <ResponseField name="agent_version_id" type="string">
      ID of the version that was deployed.
    </ResponseField>

    <ResponseField name="version_name" type="string | null">
      The version's saved name, or `null` if it was never named.
    </ResponseField>

    <ResponseField name="semver" type="string">
      The version number recorded on this deployment. Promotes and rollbacks re-record the version's original number rather than minting a new one.
    </ResponseField>

    <ResponseField name="deployed_by" type="string | null">
      ID of the user who made the deployment, or `null` when made with an org-level key.
    </ResponseField>

    <ResponseField name="deployed_at" type="string">
      ISO 8601 timestamp of the deployment.
    </ResponseField>

    <ResponseField name="check_run" type="object | null">
      The newest check run that scored this deployment's version, regardless of the environment the run targeted. `null` if the version has never been checked. See `data[].check_run` below.
    </ResponseField>

    <ResponseField name="is_rollback_eligible" type="boolean">
      `true` for `production` deployments whose version is not the current production pin. Always `false` for `dev` and `staging`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data[].check_run" type="object | null">
  The check run attached to a deployment.

  <Expandable title="check run object">
    <ResponseField name="id" type="string">
      Unique identifier for the check run.
    </ResponseField>

    <ResponseField name="agent_id" type="string">
      The agent the run belongs to.
    </ResponseField>

    <ResponseField name="env_type" type="string">
      The environment the run was started for: `staging` or `production`.
    </ResponseField>

    <ResponseField name="agent_version_id" type="string">
      The version the run scored.
    </ResponseField>

    <ResponseField name="semver" type="string | null">
      The scored version's number, or `null` if it had not been published when the run was read.
    </ResponseField>

    <ResponseField name="version_name" type="string | null">
      The scored version's saved name, or `null`.
    </ResponseField>

    <ResponseField name="status" type="string">
      One of `PENDING`, `RUNNING`, `PASSED`, `FAILED`, `ERROR`, `CANCELLED`.
    </ResponseField>

    <ResponseField name="judge_names" type="string[]">
      Display names of the judges configured when the run started.
    </ResponseField>

    <ResponseField name="scenario_count" type="integer">
      Number of test scenarios in the run.
    </ResponseField>

    <ResponseField name="simulations_count" type="integer">
      Conversations generated per scenario.
    </ResponseField>

    <ResponseField name="overall_passed" type="boolean | null">
      `true` when every required judge passed, `false` when one failed, `null` while the run has no verdict.
    </ResponseField>

    <ResponseField name="verdicts" type="array | null">
      One entry per judge once the run finishes, otherwise `null`. Each has `eval_agent_id`, `eval_agent_version_id`, `name`, `required`, `target_level_keys` (string array, empty for pass/fail judges), `match_rate` (number or `null`), `score` (0 to 100, or `null`), and `passed` (boolean or `null`).
    </ResponseField>

    <ResponseField name="simulation_set_id" type="string | null">
      ID of the simulated conversation set, once created.
    </ResponseField>

    <ResponseField name="eval_run_id" type="string | null">
      ID of the evaluation run that scored the simulations, once started.
    </ResponseField>

    <ResponseField name="error_message" type="string | null">
      Failure detail when `status` is `ERROR`.
    </ResponseField>

    <ResponseField name="triggered_by" type="string | null">
      ID of the user who started the run, or `null`.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp the run was created.
    </ResponseField>

    <ResponseField name="started_at" type="string | null">
      ISO 8601 timestamp the run began executing, or `null`.
    </ResponseField>

    <ResponseField name="completed_at" type="string | null">
      ISO 8601 timestamp the run reached a terminal status, or `null`.
    </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": [
      {
        "id": "e787c15f-abe6-409d-a685-1b007aad977d",
        "env_type": "production",
        "agent_version_id": "6cd4ce35-a4d2-4d13-a708-2a05f86ed3d8",
        "version_name": "Holiday hours",
        "semver": "1.3.2",
        "deployed_by": "f4cfacd2-d5b9-4498-ace1-8868e5b05b49",
        "deployed_at": "2026-09-10T18:42:11.904Z",
        "check_run": {
          "id": "16a5fe15-9458-4237-b884-69ce44413aae",
          "agent_id": "449bbc38-188a-4533-b73a-ebf1debdf535",
          "env_type": "staging",
          "agent_version_id": "6cd4ce35-a4d2-4d13-a708-2a05f86ed3d8",
          "semver": "1.3.2",
          "version_name": "Holiday hours",
          "status": "PASSED",
          "judge_names": [
            "Greeting quality"
          ],
          "scenario_count": 3,
          "simulations_count": 2,
          "overall_passed": true,
          "verdicts": [
            {
              "eval_agent_id": "de2d68ac-cfc6-4c40-8b1a-d6e541133f3c",
              "eval_agent_version_id": "e112f640-71be-46ca-8269-746abec3bcde",
              "name": "Greeting quality",
              "required": true,
              "target_level_keys": [],
              "match_rate": 1,
              "score": 88,
              "passed": true
            }
          ],
          "simulation_set_id": "0cb85a21-bd7d-4a73-ace4-738507fb36a0",
          "eval_run_id": "968c3972-ecca-4878-acd5-273a21853d5b",
          "error_message": null,
          "triggered_by": "f4cfacd2-d5b9-4498-ace1-8868e5b05b49",
          "created_at": "2026-09-10T18:30:02.117Z",
          "started_at": "2026-09-10T18:30:03.540Z",
          "completed_at": "2026-09-10T18:36:48.221Z"
        },
        "is_rollback_eligible": false
      },
      {
        "id": "579eca61-40fa-433b-8066-809927758313",
        "env_type": "production",
        "agent_version_id": "0f5adeb8-94a2-4cc3-8e6e-015178f994b7",
        "version_name": null,
        "semver": "1.3.1",
        "deployed_by": "f4cfacd2-d5b9-4498-ace1-8868e5b05b49",
        "deployed_at": "2026-09-03T15:07:39.318Z",
        "check_run": null,
        "is_rollback_eligible": true
      }
    ],
    "errors": null
  }
  ```

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

***

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