Get Scenario History
curl --request GET \
--url https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history"
headers = {"authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {authorization: '<authorization>'}};
fetch('https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history")
.header("authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "path must be a JSON array of at most 10 node IDs"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Versions
Get Scenario History
List how one scenario changed across saved versions.
GET
/
v2
/
agents
/
{agent_id}
/
scenarios
/
{node_id}
/
history
Get Scenario History
curl --request GET \
--url https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history \
--header 'authorization: <authorization>'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history"
headers = {"authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {authorization: '<authorization>'}};
fetch('https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history")
.header("authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/scenarios/{node_id}/history")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "path must be a JSON array of at most 10 node IDs"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
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 instaging 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.
Headers
string
required
Your API key for authentication.
Path Parameters
string
required
The agent’s unique identifier. Must be a UUID; otherwise the request returns
400 BAD_REQUEST.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.Query Parameters
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.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.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.Response
array
Up to 25 versions, newest first.
Show version entry
Show version entry
string
The version’s unique identifier.
string | null
The version’s display name, or
null if none was given.string
ISO 8601 timestamp of the save.
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.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.string | null
Pass as
before to fetch the next page. null when there are no older versions.array
Always two entries, one for
staging and one for production, independent of the requested page.null | array
null on success, or a list of error objects if the request failed.{
"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
}
{
"data": null,
"errors": [
{
"error": "BAD_REQUEST",
"message": "path must be a JSON array of at most 10 node IDs"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?