List runs

Returns the caller org's live bot runs, read from the bot runtime and projected into the console contract with each run's live session URL derived here.

GET /v1/bot/runs

Bot → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/bot/runs`
Method	`GET`
Operation	`get_bot_runs`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Returns the caller org's live bot runs, read from the bot runtime and projected into the console contract with each run's live session URL derived here.

The org is ALWAYS the validated principal's org, NEVER a request field, and it is what scopes the runtime's answer — so one tenant can never enumerate another's runs. A runtime that cannot answer is an error, not an empty list: [] would tell the caller "your org has no runs", which is a different claim from "we could not ask", and the difference is the whole reason this endpoint exists.

Request

GET /v1/bot/runs takes no parameters and no body — the credential is the whole request.

Response

Status	Body	Meaning
`200`	bot.BotRuns	ok
`default`	problem-details	refused

200 body — 7 fields.

Field	In	Type	Always	Description
`bots`	body	bot.BotRun[]	—	Bots is the org's live runs.
`bots[].runId`	body	string	—	RunID is the run's id in the bot runtime, and the node id its live VNC session is registered under.
`bots[].sessionUrl`	body	string	—	SessionURL is the live session the hanzo.app /vnc panel embeds to watch or attach to this run.
`bots[].startedAt`	body	string	—	StartedAt is when the run began, RFC 3339, as the runtime stamped it.
`bots[].status`	body	string	—	Status is the run's state as the runtime reports it; "running" when the runtime names none of its own.
`bots[].surface`	body	string	—	Surface is what the bot drives: the desktop or terminal sandbox it runs in.
`bots[].task`	body	string	—	Task is the instruction the bot is executing.

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo bot runs list

.ts

.py

.go

.rs

.java

import { Configuration, BotApi } from 'hanzoai';

const api = new BotApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getBotRuns();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import BotApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = BotApi(client).get_bot_runs()

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.BotAPI.GetBotRuns(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, bot_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = bot_api::get_bot_runs(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.BotApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new BotApi(client).getBotRuns();

curl https://api.hanzo.ai/v1/bot/runs \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches bot through the bot tool, which names its 3 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_bot_members"
         }
       }
     }'

Bot API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList members NextSync members