Agents

List sandbox events

Return Sandbox work, lifecycle, and progress events so product UIs can show what the sandbox is doing. A Sandbox runs many conversations in parallel; this streams all of them by default and every event carries a conversationId. Filter to one or more with conversation. Event payloads are extensible. Clients can long-poll this endpoint with sort=asc and a cursor to stream responses. Response events expose agent text, streaming partials via data.is_streaming, and tool calls/results via data.tools. When you poll, send the last ETag back in If-None-Match. An unchanged page answers 304 Not Modified with no body.

GET

sandboxes

{sandboxId}

events

List boat events

curl --request GET \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/events \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://boat.dev/api/v1/sandboxes/{sandboxId}/events', 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://boat.dev/api/v1/sandboxes/{sandboxId}/events",
  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: Bearer <token>"
  ],
]);

$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://boat.dev/api/v1/sandboxes/{sandboxId}/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://boat.dev/api/v1/sandboxes/{sandboxId}/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "type": "events.list",
  "id": "bx_23456789",
  "events": [
    {
      "id": "prompt_123",
      "type": "prompt",
      "timestamp": 1780347055370,
      "taskId": "prompt_123",
      "data": {
        "prompt": "Run tests and summarize failures.",
        "status": "running",
        "is_reverted": false
      }
    },
    {
      "id": "response_123-tools",
      "type": "response",
      "timestamp": 1780347063427,
      "taskId": "prompt_123",
      "data": {
        "content": "",
        "model": "gpt-5.4",
        "tools": [
          {
            "use": {
              "id": "call_123",
              "type": "tool_use",
              "name": "Bash",
              "input": {
                "command": "npm test"
              }
            },
            "result": {
              "type": "tool_result",
              "tool_use_id": "call_123",
              "is_error": false,
              "content": "{\"exitCode\":0}"
            }
          }
        ],
        "is_reverted": false
      }
    },
    {
      "id": "response_123",
      "type": "response",
      "timestamp": 1780347065650,
      "taskId": "prompt_123",
      "data": {
        "content": "Tests passed.",
        "model": "gpt-5.4",
        "is_reverted": false
      }
    }
  ],
  "pageInfo": {
    "nextCursor": null,
    "hasMore": false,
    "limit": 100
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Boat bearer token in the form boat_.... Service API keys authenticate sandbox operations.

Headers

If-None-Match

string

The ETag of the last page you read. If the page is unchanged, the answer is 304 with no body.

Path Parameters

sandboxId

string

required

Public Sandbox id returned by create/list/get sandbox calls.

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Query Parameters

limit

integer

default:100

Maximum items to return.

Required range: 1 <= x <= 200

cursor

string | null

Opaque pagination cursor returned as pageInfo.nextCursor.

sort

enum<string>

default:desc

Sort direction for cursor pagination.

Available options:

asc,

desc

type

string

Comma-separated event type filter, for example prompt,response,steer.

conversation

string

Only return events for this conversation id. Repeat the parameter (or comma-separate) for several. Omit to stream every conversation on the sandbox. See Integrated agents.

Response

The agent's work on the sandbox (prompts, responses), not sandbox lifecycle. A sandbox that was never prompted returns an empty list even though it started, stopped and resumed.

boolean

required

Example:

true

type

string

required

Stable success envelope discriminator added by v1.

Allowed value: "events.list"

string

required

events

object[]

required

Sandbox work and lifecycle event objects. Event shapes are intentionally extensible; branch on each event type when present.

Show child attributes

pageInfo

object

Show child attributes

List boat events

curl --request GET \
  --url https://boat.dev/api/v1/sandboxes/{sandboxId}/events \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://boat.dev/api/v1/sandboxes/{sandboxId}/events', 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://boat.dev/api/v1/sandboxes/{sandboxId}/events",
  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: Bearer <token>"
  ],
]);

$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://boat.dev/api/v1/sandboxes/{sandboxId}/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://boat.dev/api/v1/sandboxes/{sandboxId}/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "ok": true,
  "type": "events.list",
  "id": "bx_23456789",
  "events": [
    {
      "id": "prompt_123",
      "type": "prompt",
      "timestamp": 1780347055370,
      "taskId": "prompt_123",
      "data": {
        "prompt": "Run tests and summarize failures.",
        "status": "running",
        "is_reverted": false
      }
    },
    {
      "id": "response_123-tools",
      "type": "response",
      "timestamp": 1780347063427,
      "taskId": "prompt_123",
      "data": {
        "content": "",
        "model": "gpt-5.4",
        "tools": [
          {
            "use": {
              "id": "call_123",
              "type": "tool_use",
              "name": "Bash",
              "input": {
                "command": "npm test"
              }
            },
            "result": {
              "type": "tool_result",
              "tool_use_id": "call_123",
              "is_error": false,
              "content": "{\"exitCode\":0}"
            }
          }
        ],
        "is_reverted": false
      }
    },
    {
      "id": "response_123",
      "type": "response",
      "timestamp": 1780347065650,
      "taskId": "prompt_123",
      "data": {
        "content": "Tests passed.",
        "model": "gpt-5.4",
        "is_reverted": false
      }
    }
  ],
  "pageInfo": {
    "nextCursor": null,
    "hasMore": false,
    "limit": 100
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

{
  "ok": false,
  "type": "sandbox.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

Tools

API

Sandboxes

Commands

Files

Agents

Access

Snapshots

Saved snapshots

Environments

AI credentials

Account and organizations

API keys

Webhooks and OpenTelemetry

CI on Boat VMs

Data retention

List sandbox events

Authorizations

Headers

Path Parameters

Query Parameters

Response