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

# Get Scenario History

> List how one scenario changed across saved versions.

### Overview

Walks the agent's saved versions, newest first, and returns the scenario node's saved content at each one, 25 versions per page, alongside the node as currently pinned in `staging` and `production`. Works for `scenario`, `complex-scenario`, `auth`, `auth-zone`, and `complex-auth` nodes, and for the agent's hub prompt by passing `agent` as the `node_id`. Node content is returned as stored, so older versions may carry fields the editor no longer writes. To read a whole version instead, use [Get Latest Agent Version](/api-v2/get/agents-id-versions-latest).

### 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. Must be a UUID; otherwise the request returns `400 BAD_REQUEST`.
</ParamField>

<ParamField path="node_id" type="string" required>
  The scenario node's `id` within its flow. 1 to 200 characters and not blank. Pass the literal value `agent` to read the agent's hub prompt instead of a scenario; the hub lives in the root flow, so `path` must be omitted or empty for that value.
</ParamField>

### Query Parameters

<ParamField query="branch" type="string">
  An open branch's ID (UUID). Lists that branch's own saves followed by the dev version it was cut from. Returns `404 NOT_FOUND` if the branch is not open or does not belong to this agent. Omit to read the dev timeline.
</ParamField>

<ParamField query="path" type="string" default="[]">
  JSON-encoded array of container node IDs leading from the root flow to the flow that holds `node_id`, outermost first, for example `["76c53696-04da-4dfa-be12-ebd286070549"]`. At most 10 IDs of 1 to 200 characters each, and the raw string may not exceed 12,500 characters. Omit for a node in the root flow. Malformed values return `400 BAD_REQUEST`.
</ParamField>

<ParamField query="before" type="string">
  Pagination cursor: the `next_cursor` from the previous page (a version ID). Returns the versions saved before it. A cursor that is not in the requested timeline returns `400 BAD_REQUEST`.
</ParamField>

### Response

<ResponseField name="data.versions" type="array">
  Up to 25 versions, newest first.

  <Expandable title="version entry">
    <ResponseField name="id" type="string">
      The version's unique identifier.
    </ResponseField>

    <ResponseField name="name" type="string | null">
      The version's display name, or `null` if none was given.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of the save.
    </ResponseField>

    <ResponseField name="author" type="string | null">
      Display name of the user who saved the version, or `null` when saved with an org-level key or the name is unavailable.
    </ResponseField>

    <ResponseField name="node" type="object | null">
      The scenario as saved in that version: its `type` and full `data` object (for example `name`, `rule`, `target`, `loopWhile`, `variables`, `entry`, and for container types `flow`). For `node_id` `agent` the `type` is `agent` and `data` carries the hub's `prompt`, `variables`, and `tools`, with no `name` field, since the agent's name lives on the agent record. `null` when the node did not exist at that path in that version.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.next_cursor" type="string | null">
  Pass as `before` to fetch the next page. `null` when there are no older versions.
</ResponseField>

<ResponseField name="data.environments" type="array">
  Always two entries, one for `staging` and one for `production`, independent of the requested page.

  <Expandable title="environment entry">
    <ResponseField name="env" type="string">
      `staging` or `production`.
    </ResponseField>

    <ResponseField name="node" type="object | null">
      The scenario as it exists in the version that environment is pinned to, in the same shape as `versions[].node`. `null` when the environment is unpinned or the node is absent from the pinned version.
    </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": {
      "versions": [
        {
          "id": "279d679d-20e6-4dac-976b-c7d23dc7449e",
          "name": null,
          "created_at": "2026-09-10T23:41:07.902Z",
          "author": "Dana Whitfield",
          "node": {
            "type": "scenario",
            "data": {
              "name": "Book appointment",
              "rule": "Collect the caller's preferred date and time, offer the nearest open slot, then confirm the booking.",
              "target": { "kind": "dialogue", "label": "Book appointment" },
              "loopWhile": "",
              "variables": [
                {
                  "id": "4313aace-ade6-4f67-832e-d7646b5c62c1",
                  "key": "preferred_date",
                  "value": "The date the caller asked for, in YYYY-MM-DD format.",
                  "type": "string",
                  "accurateSpelling": false
                }
              ],
              "entry": {
                "mode": "llm",
                "label": "Caller wants to book",
                "description": "",
                "alwaysPick": false,
                "conditions": []
              }
            }
          }
        },
        {
          "id": "a2a07641-cf05-46fd-ac9b-4e974f2f058c",
          "name": "Adds booking flow",
          "created_at": "2026-09-10T23:02:11.418Z",
          "author": "Dana Whitfield",
          "node": {
            "type": "scenario",
            "data": {
              "name": "Book appointment",
              "rule": "Collect the caller's preferred date and time, then confirm the booking.",
              "target": { "kind": "dialogue", "label": "Book appointment" },
              "loopWhile": "",
              "variables": [],
              "entry": {
                "mode": "llm",
                "label": "Caller wants to book",
                "description": "",
                "alwaysPick": false,
                "conditions": []
              }
            }
          }
        }
      ],
      "next_cursor": null,
      "environments": [
        {
          "env": "staging",
          "node": {
            "type": "scenario",
            "data": {
              "name": "Book appointment",
              "rule": "Collect the caller's preferred date and time, then confirm the booking.",
              "target": { "kind": "dialogue", "label": "Book appointment" },
              "loopWhile": "",
              "variables": [],
              "entry": {
                "mode": "llm",
                "label": "Caller wants to book",
                "description": "",
                "alwaysPick": false,
                "conditions": []
              }
            }
          }
        },
        {
          "env": "production",
          "node": null
        }
      ]
    },
    "errors": null
  }
  ```

  ```json Bad Request theme={null}
  {
    "data": null,
    "errors": [
      {
        "error": "BAD_REQUEST",
        "message": "path must be a JSON array of at most 10 node IDs"
      }
    ]
  }
  ```

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

***

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