Get a trace

GET /v1/traces/{trace_id}

The requests of one W3C trace in your project, in start order, with the usage each one was charged and the sandbox tags of the sandboxes that made them (b3os.app, b3os.deploy, b3os.item). A trace is every request whose traceparent named this trace id: the calls of one traces.turn in the SDKs, or of a harness that sends its own traceparent. In this beta the edge assembles it from the request log and the usage records, so spans are the requests themselves, listed flat (nested: false); calls made inside B3OS on a request's behalf (a routine step's scrape, a hosted tool) are inside their request's time and have no span of their own. harness_ms is the time inside the trace when no B3OS request was in flight. origin is call for one call and its retries, or for a trace made only by an SDK version that sends no trace mark (by its User-Agent); otherwise traceparent. At most 300 requests are read (truncated).

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token)

Path Parameters

trace_id string required path

Pattern ^[0-9a-f]{32}$

Example: "4bf92f3577b34da6a3ce929d0e0e4736"

Responses

200 The trace.

application/json

id string REQUIRED

object string REQUIRED

Values trace

origin string REQUIRED

How the trace came to be (NOTES/deploy-platform/observability.md 2.2). This beta gives traceparent (a caller's own trace: a turn of the SDKs' turn helper, or a harness's) or call (one call and its retries, or a trace made only by SDK versions that send no mark); the others come with the node's own spans.

Values turn traceparent inferred run call ingested

nested boolean REQUIRED

false in this beta: spans are the trace's requests, listed flat in start order.

project_id string REQUIRED

app string | null REQUIRED

The b3os.app tag of the first sandbox that made a request in the trace; null outside a deploy.

deploy string | null REQUIRED

service string | null REQUIRED

The service name from that sandbox's b3os.item tag (service/<name>).

started_at string (date-time) REQUIRED

ended_at string (date-time) REQUIRED

duration_ms number REQUIRED

harness_ms number REQUIRED

Time between the trace's first start and last end when no B3OS request was in flight.

status string REQUIRED

Values ok error

counts object REQUIRED

spans integer REQUIRED

model_calls integer REQUIRED

tool_calls integer REQUIRED

errors integer REQUIRED

dropped integer REQUIRED

Spans the node dropped past its cap; always 0 in this beta (truncated says the 300-request read stopped early).

usage object[] REQUIRED

Array of:

unit string REQUIRED

The usage unit (infer.input_tokens, vision.page, sandboxes.vcpu_ms).

qty number REQUIRED

sandboxes object[] REQUIRED

Array of:

id string REQUIRED

app string | null REQUIRED

The sandbox's b3os.app tag; null outside a deploy, or when the sandbox could not be read.

deploy string | null REQUIRED

Its b3os.deploy tag.

item string | null REQUIRED

Its b3os.item tag (service/harness, eval/answers).

spans object[] REQUIRED

Array of:

request_id string REQUIRED

kind string REQUIRED

What the span is, from the request's product and operation.

Values model sandbox.exec vision render action routine request

name string REQUIRED

<product>.<operation> (vision.scrape), or the path when the operation is not known.

product string | null REQUIRED

operation_id string | null REQUIRED

method string REQUIRED

path string REQUIRED

status string REQUIRED

error for a 4xx or 5xx answer.

Values ok error

status_code integer REQUIRED

error_code string | null REQUIRED

error_detail string | null

The request record's error_detail, when it has one (why a 4xx or 5xx failed).

source string REQUIRED

connection string REQUIRED

sandbox_id string | null REQUIRED

user_agent string | null REQUIRED

started_at string (date-time) REQUIRED

offset_ms number REQUIRED

Milliseconds from the trace's first request to this one's start.

duration_ms number REQUIRED

phases object[] REQUIRED

Array of:

name string REQUIRED

source string REQUIRED

Values edge node

duration_ms number REQUIRED

usage object[] REQUIRED

The usage records charged to this request, summed by unit.

Array of:

unit string REQUIRED

The usage unit (infer.input_tokens, vision.page, sandboxes.vcpu_ms).

qty number REQUIRED

truncated boolean REQUIRED

400 The request failed validation (invalid_request, invalid_url).

application/problem+json

type string (uri) REQUIRED

https://docs.beta.b3os.org/errors#<code>.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (req_…) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (invalid_request and the other codes that list errors).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (/url, /steps/0/uses), or #query/<name>, #path/<name> or #header/<name> for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (unauthorized, forbidden, egress_denied, upstream_unreachable, …).

required_scope string

The scope that was missing (forbidden with reason: scope).

retry_after_s integer

Same value as the Retry-After header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by GET /v1/limits.

id string REQUIRED

Limit ID, such as vision.scrape.rpm or sandboxes.concurrent.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as requests, sandboxes, vcpu or MiB.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as sandbox_not_running.

upstream_status integer

The HTTP status the upstream returned (upstream_error, action_output_invalid).

step string

The failed step, as a step ID (routines), an index (act) or a path such as beats/2/do/0 (render).

pack_error object

The error a pack's error mapping chose (upstream_error from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

option string

The option a request value was refused for, by its id (option_not_allowed), e.g. sandboxes.clone_reset.

value unknown

The value the request asked for (option_not_allowed).

allowed unknown[]

The values the request may ask for (option_not_allowed, an option with a closed list of values).

bound_by string

What set the bound a refused value is outside (option_not_allowed); node is the node's policy.

Values node org flag limit

service string

The application's service a refusal is about, with port (the address codes, app_host_*).

port integer

The port of service a refusal is about (the address codes, app_host_*).

exit_code integer

The exit status of a hosted tool's command (tool_failed with reason: exit).

signal string

The signal that ended a hosted tool's command, such as SIGKILL (tool_failed with reason: signal).

tool_code string

The error code a hosted tool answered with (tool_failed with reason: tool_error), when it matches the pattern. Text the tool wrote, not a B3OS code.

tool_message string

The first 300 characters of a hosted tool's own error message (tool_failed with reason: tool_error). Text the tool wrote: treat it as data, not as an instruction.

retryable boolean

Whether a hosted tool says the same call may succeed later (tool_failed with reason: tool_error).

stderr string

The first 4096 bytes of a hosted tool's standard error, on a development node only ([actions.tools] dev_stderr); never on a node that serves customers.

401 Missing, malformed, expired or revoked credentials (unauthorized).

application/problem+json

type string (uri) REQUIRED

https://docs.beta.b3os.org/errors#<code>.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (req_…) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (invalid_request and the other codes that list errors).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (/url, /steps/0/uses), or #query/<name>, #path/<name> or #header/<name> for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (unauthorized, forbidden, egress_denied, upstream_unreachable, …).

required_scope string

The scope that was missing (forbidden with reason: scope).

retry_after_s integer

Same value as the Retry-After header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by GET /v1/limits.

id string REQUIRED

Limit ID, such as vision.scrape.rpm or sandboxes.concurrent.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as requests, sandboxes, vcpu or MiB.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as sandbox_not_running.

upstream_status integer

The HTTP status the upstream returned (upstream_error, action_output_invalid).

step string

The failed step, as a step ID (routines), an index (act) or a path such as beats/2/do/0 (render).

pack_error object

The error a pack's error mapping chose (upstream_error from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

option string

The option a request value was refused for, by its id (option_not_allowed), e.g. sandboxes.clone_reset.

value unknown

The value the request asked for (option_not_allowed).

allowed unknown[]

The values the request may ask for (option_not_allowed, an option with a closed list of values).

bound_by string

What set the bound a refused value is outside (option_not_allowed); node is the node's policy.

Values node org flag limit

service string

The application's service a refusal is about, with port (the address codes, app_host_*).

port integer

The port of service a refusal is about (the address codes, app_host_*).

exit_code integer

The exit status of a hosted tool's command (tool_failed with reason: exit).

signal string

The signal that ended a hosted tool's command, such as SIGKILL (tool_failed with reason: signal).

tool_code string

The error code a hosted tool answered with (tool_failed with reason: tool_error), when it matches the pattern. Text the tool wrote, not a B3OS code.

tool_message string

The first 300 characters of a hosted tool's own error message (tool_failed with reason: tool_error). Text the tool wrote: treat it as data, not as an instruction.

retryable boolean

Whether a hosted tool says the same call may succeed later (tool_failed with reason: tool_error).

stderr string

The first 4096 bytes of a hosted tool's standard error, on a development node only ([actions.tools] dev_stderr); never on a node that serves customers.

403 Authenticated but not allowed (forbidden, egress_denied).

application/problem+json

type string (uri) REQUIRED

https://docs.beta.b3os.org/errors#<code>.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (req_…) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (invalid_request and the other codes that list errors).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (/url, /steps/0/uses), or #query/<name>, #path/<name> or #header/<name> for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (unauthorized, forbidden, egress_denied, upstream_unreachable, …).

required_scope string

The scope that was missing (forbidden with reason: scope).

retry_after_s integer

Same value as the Retry-After header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by GET /v1/limits.

id string REQUIRED

Limit ID, such as vision.scrape.rpm or sandboxes.concurrent.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as requests, sandboxes, vcpu or MiB.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as sandbox_not_running.

upstream_status integer

The HTTP status the upstream returned (upstream_error, action_output_invalid).

step string

The failed step, as a step ID (routines), an index (act) or a path such as beats/2/do/0 (render).

pack_error object

The error a pack's error mapping chose (upstream_error from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

option string

The option a request value was refused for, by its id (option_not_allowed), e.g. sandboxes.clone_reset.

value unknown

The value the request asked for (option_not_allowed).

allowed unknown[]

The values the request may ask for (option_not_allowed, an option with a closed list of values).

bound_by string

What set the bound a refused value is outside (option_not_allowed); node is the node's policy.

Values node org flag limit

service string

The application's service a refusal is about, with port (the address codes, app_host_*).

port integer

The port of service a refusal is about (the address codes, app_host_*).

exit_code integer

The exit status of a hosted tool's command (tool_failed with reason: exit).

signal string

The signal that ended a hosted tool's command, such as SIGKILL (tool_failed with reason: signal).

tool_code string

The error code a hosted tool answered with (tool_failed with reason: tool_error), when it matches the pattern. Text the tool wrote, not a B3OS code.

tool_message string

The first 300 characters of a hosted tool's own error message (tool_failed with reason: tool_error). Text the tool wrote: treat it as data, not as an instruction.

retryable boolean

Whether a hosted tool says the same call may succeed later (tool_failed with reason: tool_error).

stderr string

The first 4096 bytes of a hosted tool's standard error, on a development node only ([actions.tools] dev_stderr); never on a node that serves customers.

404 No request of this trace in your project in the last 7 days (trace_not_found).

application/problem+json

type string (uri) REQUIRED

https://docs.beta.b3os.org/errors#<code>.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (req_…) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (invalid_request and the other codes that list errors).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (/url, /steps/0/uses), or #query/<name>, #path/<name> or #header/<name> for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (unauthorized, forbidden, egress_denied, upstream_unreachable, …).

required_scope string

The scope that was missing (forbidden with reason: scope).

retry_after_s integer

Same value as the Retry-After header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by GET /v1/limits.

id string REQUIRED

Limit ID, such as vision.scrape.rpm or sandboxes.concurrent.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as requests, sandboxes, vcpu or MiB.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as sandbox_not_running.

upstream_status integer

The HTTP status the upstream returned (upstream_error, action_output_invalid).

step string

The failed step, as a step ID (routines), an index (act) or a path such as beats/2/do/0 (render).

pack_error object

The error a pack's error mapping chose (upstream_error from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

option string

The option a request value was refused for, by its id (option_not_allowed), e.g. sandboxes.clone_reset.

value unknown

The value the request asked for (option_not_allowed).

allowed unknown[]

The values the request may ask for (option_not_allowed, an option with a closed list of values).

bound_by string

What set the bound a refused value is outside (option_not_allowed); node is the node's policy.

Values node org flag limit

service string

The application's service a refusal is about, with port (the address codes, app_host_*).

port integer

The port of service a refusal is about (the address codes, app_host_*).

exit_code integer

The exit status of a hosted tool's command (tool_failed with reason: exit).

signal string

The signal that ended a hosted tool's command, such as SIGKILL (tool_failed with reason: signal).

tool_code string

The error code a hosted tool answered with (tool_failed with reason: tool_error), when it matches the pattern. Text the tool wrote, not a B3OS code.

tool_message string

The first 300 characters of a hosted tool's own error message (tool_failed with reason: tool_error). Text the tool wrote: treat it as data, not as an instruction.

retryable boolean

Whether a hosted tool says the same call may succeed later (tool_failed with reason: tool_error).

stderr string

The first 4096 bytes of a hosted tool's standard error, on a development node only ([actions.tools] dev_stderr); never on a node that serves customers.

429 A rate, concurrency or quota limit applies (rate_limited, concurrency_limited, quota_exceeded).

application/problem+json

type string (uri) REQUIRED

https://docs.beta.b3os.org/errors#<code>.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (req_…) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (invalid_request and the other codes that list errors).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (/url, /steps/0/uses), or #query/<name>, #path/<name> or #header/<name> for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (unauthorized, forbidden, egress_denied, upstream_unreachable, …).

required_scope string

The scope that was missing (forbidden with reason: scope).

retry_after_s integer

Same value as the Retry-After header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by GET /v1/limits.

id string REQUIRED

Limit ID, such as vision.scrape.rpm or sandboxes.concurrent.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as requests, sandboxes, vcpu or MiB.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as sandbox_not_running.

upstream_status integer

The HTTP status the upstream returned (upstream_error, action_output_invalid).

step string

The failed step, as a step ID (routines), an index (act) or a path such as beats/2/do/0 (render).

pack_error object

The error a pack's error mapping chose (upstream_error from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

option string

The option a request value was refused for, by its id (option_not_allowed), e.g. sandboxes.clone_reset.

value unknown

The value the request asked for (option_not_allowed).

allowed unknown[]

The values the request may ask for (option_not_allowed, an option with a closed list of values).

bound_by string

What set the bound a refused value is outside (option_not_allowed); node is the node's policy.

Values node org flag limit

service string

The application's service a refusal is about, with port (the address codes, app_host_*).

port integer

The port of service a refusal is about (the address codes, app_host_*).

exit_code integer

The exit status of a hosted tool's command (tool_failed with reason: exit).

signal string

The signal that ended a hosted tool's command, such as SIGKILL (tool_failed with reason: signal).

tool_code string

The error code a hosted tool answered with (tool_failed with reason: tool_error), when it matches the pattern. Text the tool wrote, not a B3OS code.

tool_message string

The first 300 characters of a hosted tool's own error message (tool_failed with reason: tool_error). Text the tool wrote: treat it as data, not as an instruction.

retryable boolean

Whether a hosted tool says the same call may succeed later (tool_failed with reason: tool_error).

stderr string

The first 4096 bytes of a hosted tool's standard error, on a development node only ([actions.tools] dev_stderr); never on a node that serves customers.

500 Something failed inside B3OS (internal). Retry with backoff.

application/problem+json

type string (uri) REQUIRED

https://docs.beta.b3os.org/errors#<code>.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (req_…) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (invalid_request and the other codes that list errors).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (/url, /steps/0/uses), or #query/<name>, #path/<name> or #header/<name> for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (unauthorized, forbidden, egress_denied, upstream_unreachable, …).

required_scope string

The scope that was missing (forbidden with reason: scope).

retry_after_s integer

Same value as the Retry-After header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by GET /v1/limits.

id string REQUIRED

Limit ID, such as vision.scrape.rpm or sandboxes.concurrent.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as requests, sandboxes, vcpu or MiB.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as sandbox_not_running.

upstream_status integer

The HTTP status the upstream returned (upstream_error, action_output_invalid).

step string

The failed step, as a step ID (routines), an index (act) or a path such as beats/2/do/0 (render).

pack_error object

The error a pack's error mapping chose (upstream_error from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

option string

The option a request value was refused for, by its id (option_not_allowed), e.g. sandboxes.clone_reset.

value unknown

The value the request asked for (option_not_allowed).

allowed unknown[]

The values the request may ask for (option_not_allowed, an option with a closed list of values).

bound_by string

What set the bound a refused value is outside (option_not_allowed); node is the node's policy.

Values node org flag limit

service string

The application's service a refusal is about, with port (the address codes, app_host_*).

port integer

The port of service a refusal is about (the address codes, app_host_*).

exit_code integer

The exit status of a hosted tool's command (tool_failed with reason: exit).

signal string

The signal that ended a hosted tool's command, such as SIGKILL (tool_failed with reason: signal).

tool_code string

The error code a hosted tool answered with (tool_failed with reason: tool_error), when it matches the pattern. Text the tool wrote, not a B3OS code.

tool_message string

The first 300 characters of a hosted tool's own error message (tool_failed with reason: tool_error). Text the tool wrote: treat it as data, not as an instruction.

retryable boolean

Whether a hosted tool says the same call may succeed later (tool_failed with reason: tool_error).

stderr string

The first 4096 bytes of a hosted tool's standard error, on a development node only ([actions.tools] dev_stderr); never on a node that serves customers.

503 The node or the product is not available right now (node_unavailable, product_unavailable, capacity_unavailable).

application/problem+json

type string (uri) REQUIRED

https://docs.beta.b3os.org/errors#<code>.

title string REQUIRED

Short summary of the problem type.

status integer REQUIRED

The HTTP status code, repeated for convenience.

code string REQUIRED

Stable machine-readable error code from the errors catalog.

detail string REQUIRED

Explanation of this occurrence. Never contains secrets.

instance string

The request ID (req_…) of the request that failed. Include it when you contact support.

errors object[]

Validation problems, one per field (invalid_request and the other codes that list errors).

Array of:

pointer string REQUIRED

Where the problem is: a JSON pointer into the request body (/url, /steps/0/uses), or #query/<name>, #path/<name> or #header/<name> for parameters.

detail string REQUIRED

What is wrong there.

reason string

Finer-grained cause for codes that document one (unauthorized, forbidden, egress_denied, upstream_unreachable, …).

required_scope string

The scope that was missing (forbidden with reason: scope).

retry_after_s integer

Same value as the Retry-After header, for clients that only read the body.

limit object

The limit an error refers to. IDs and current values are listed by GET /v1/limits.

id string REQUIRED

Limit ID, such as vision.scrape.rpm or sandboxes.concurrent.

limit number REQUIRED

The limit's value.

unit string REQUIRED

What the limit counts, such as requests, sandboxes, vcpu or MiB.

window_s integer

Window length in seconds for rate limits and quotas.

current number

Current usage against the limit, when known.

current_status string

The object's current status, for state conflicts such as sandbox_not_running.

upstream_status integer

The HTTP status the upstream returned (upstream_error, action_output_invalid).

step string

The failed step, as a step ID (routines), an index (act) or a path such as beats/2/do/0 (render).

pack_error object

The error a pack's error mapping chose (upstream_error from pack actions).

code string REQUIRED

message string REQUIRED

retryable boolean REQUIRED

option string

The option a request value was refused for, by its id (option_not_allowed), e.g. sandboxes.clone_reset.

value unknown

The value the request asked for (option_not_allowed).

allowed unknown[]

The values the request may ask for (option_not_allowed, an option with a closed list of values).

bound_by string

What set the bound a refused value is outside (option_not_allowed); node is the node's policy.

Values node org flag limit

service string

The application's service a refusal is about, with port (the address codes, app_host_*).

port integer

The port of service a refusal is about (the address codes, app_host_*).

exit_code integer

The exit status of a hosted tool's command (tool_failed with reason: exit).

signal string

The signal that ended a hosted tool's command, such as SIGKILL (tool_failed with reason: signal).

tool_code string

The error code a hosted tool answered with (tool_failed with reason: tool_error), when it matches the pattern. Text the tool wrote, not a B3OS code.

tool_message string

The first 300 characters of a hosted tool's own error message (tool_failed with reason: tool_error). Text the tool wrote: treat it as data, not as an instruction.

retryable boolean

Whether a hosted tool says the same call may succeed later (tool_failed with reason: tool_error).

stderr string

The first 4096 bytes of a hosted tool's standard error, on a development node only ([actions.tools] dev_stderr); never on a node that serves customers.

curl -X GET 'https://beta-api.b3os.org/v1/traces/4bf92f3577b34da6a3ce929d0e0e4736' \  -H 'Authorization: Bearer YOUR_API_TOKEN'

const response = await fetch('https://beta-api.b3os.org/v1/traces/4bf92f3577b34da6a3ce929d0e0e4736', {  method: 'GET',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN"  }});const data = await response.json();console.log(data);

import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.get('https://beta-api.b3os.org/v1/traces/4bf92f3577b34da6a3ce929d0e0e4736', headers=headers)print(response.json())

200 Response

{  "id": "4bf92f3577b34da6a3ce929d0e0e4736",  "object": "trace",  "origin": "traceparent",  "nested": false,  "project_id": "prj_01m5t3pf8heewxt65ej3dm577y",  "app": "research-agent",  "deploy": "dep_01m6a2zq8x9hkqd3n7c5b4v2tw",  "service": "harness",  "started_at": "2026-11-07T10:00:00.010Z",  "ended_at": "2026-11-07T10:00:01.122Z",  "duration_ms": 1112,  "harness_ms": 160.3,  "status": "ok",  "counts": {    "spans": 2,    "model_calls": 1,    "tool_calls": 1,    "errors": 0,    "dropped": 0  },  "usage": [    {      "unit": "infer.input_tokens",      "qty": 1830    },    {      "unit": "infer.output_tokens",      "qty": 212    },    {      "unit": "vision.page",      "qty": 1    }  ],  "sandboxes": [    {      "id": "sbx_01m5t68q1b590rj801nbzsqzkk",      "app": "research-agent",      "deploy": "dep_01m6a2zq8x9hkqd3n7c5b4v2tw",      "item": "service/harness"    }  ],  "spans": [    {      "request_id": "req_01m5t4yg394wegr3j4y01qb363",      "kind": "vision",      "name": "vision.scrape",      "product": "vision",      "operation_id": "visionScrape",      "method": "POST",      "path": "/v1/vision/scrape",      "status": "ok",      "status_code": 200,      "error_code": null,      "source": "sandbox",      "connection": "sandbox",      "sandbox_id": "sbx_01m5t68q1b590rj801nbzsqzkk",      "user_agent": "b3os-sdk-ts/0.1.1 node/24.11.0",      "started_at": "2026-11-07T10:00:00.010Z",      "offset_ms": 0,      "duration_ms": 139.4,      "phases": [        {          "name": "fetch",          "source": "node",          "duration_ms": 121.2        },        {          "name": "total",          "source": "node",          "duration_ms": 138.8        }      ],      "usage": [        {          "unit": "vision.page",          "qty": 1        }      ]    },    {      "request_id": "req_01m5t6d8ksbzrfxhqhzge06mqn",      "kind": "model",      "name": "infer.createChatCompletion",      "product": "infer",      "operation_id": "inferCreateChatCompletion",      "method": "POST",      "path": "/v1/infer/chat/completions",      "status": "ok",      "status_code": 200,      "error_code": null,      "source": "sandbox",      "connection": "sandbox",      "sandbox_id": "sbx_01m5t68q1b590rj801nbzsqzkk",      "user_agent": "openai-node/5.23.0",      "started_at": "2026-11-07T10:00:00.310Z",      "offset_ms": 300,      "duration_ms": 812,      "phases": [        {          "name": "ttft",          "source": "node",          "duration_ms": 127.9        },        {          "name": "total",          "source": "node",          "duration_ms": 811.6        }      ],      "usage": [        {          "unit": "infer.input_tokens",          "qty": 1830        },        {          "unit": "infer.output_tokens",          "qty": 212        }      ]    }  ],  "truncated": false}

400 Response

{  "type": "https://docs.beta.b3os.org/errors#invalid_request",  "title": "Invalid request",  "status": 400,  "code": "invalid_request",  "detail": "1 field failed validation",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "errors": [    {      "pointer": "/url",      "detail": "must be an absolute http or https URL"    }  ]}

401 Response

{  "type": "https://docs.beta.b3os.org/errors#unauthorized",  "title": "Unauthorized",  "status": 401,  "code": "unauthorized",  "detail": "API key checksum does not match; check that the whole key was copied",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "reason": "malformed"}

403 Response

{  "type": "https://docs.beta.b3os.org/errors#forbidden",  "title": "Forbidden",  "status": 403,  "code": "forbidden",  "detail": "This key lacks the scope sandboxes:write",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "reason": "scope",  "required_scope": "sandboxes:write"}

404 Response

{  "type": "https://docs.beta.b3os.org/errors#trace_not_found",  "title": "Trace not found",  "status": 404,  "code": "trace_not_found",  "detail": "No request of trace 4bf92f3577b34da6a3ce929d0e0e4736 in this project in the last 7 days",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

429 Response

{  "type": "https://docs.beta.b3os.org/errors#rate_limited",  "title": "Rate limited",  "status": 429,  "code": "rate_limited",  "detail": "60 scrapes per minute allowed; retry in 12 seconds",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "retry_after_s": 12,  "limit": {    "id": "vision.scrape.rpm",    "limit": 60,    "unit": "requests",    "window_s": 60,    "current": 60  }}

500 Response

{  "type": "https://docs.beta.b3os.org/errors#internal",  "title": "Internal error",  "status": 500,  "code": "internal",  "detail": "internal error",  "instance": "req_01m5t4yg394wegr3j4y01qb363"}

503 Response

{  "type": "https://docs.beta.b3os.org/errors#node_unavailable",  "title": "Node unavailable",  "status": 503,  "code": "node_unavailable",  "detail": "Node n1 is not reachable; retry in 5 seconds",  "instance": "req_01m5t4yg394wegr3j4y01qb363",  "retry_after_s": 5}

GET /v1/traces/{trace_id}

Base URL

Bearer Token

Path Parameters

trace_id string required

Response

Was this page helpful?

Previous Block an address

Next List eval runs