Skip to main content
GET
Read sandbox CPU, memory, and GPU usage for a session tree

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Headers

x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Path Parameters

sessionId
string<uuid>
required

Any session id (UUID) in the tree. The sandbox is shared by the whole tree, so every id in it returns the same usage.

Query Parameters

bucketStartedAtGte
string<date-time>

Inclusive lower bound on bucketStartedAt, RFC 3339. Omit for the start of the tree.

bucketStartedAtLt
string<date-time>

Exclusive upper bound on bucketStartedAt, RFC 3339. Omit for now.

resolution
enum<string>
default:minute

minute returns per-minute summaries only; raw also includes each bucket's per-sample arrays at the producer's cadence (five seconds by default). Use raw for the window on screen and minute for the overview.

Available options:
minute,
raw
limit
integer
default:120

Maximum buckets per page, across all of the tree's sandbox attachments.

Required range: 1 <= x <= 720
cursor
string

Signed continuation token from a previous page's nextCursor. Bound to the organization, session, and filters it was issued for.

Response

OK

asOf
string<date-time>
required

RFC 3339 server time at which the page was read.

items
object[]
required

One page of minute buckets ordered by (sandbox_id, bucket_start). Each bucket names its attachment; join on sandboxes to place it on a lane.

live
boolean
required

True while a sandbox that can be sampled is still attached to the tree. A client keeps polling while this is true and stops once it turns false; an attached sandbox that cannot measure itself does not keep it true.

nextCursor
null | string
required

Cursor for the next page, or null on the last page.

resolution
enum<string>
required

Resolution the buckets were read at.

Available options:
minute,
raw
rootSessionId
string
required

Root of the tree the usage belongs to.

sandboxes
object[]
required

Every sandbox attachment the tree has had, oldest first, including ones that have since been released or closed. Empty when the tree never had a sandbox or sampling is disabled. Complete on every page.

sessionId
string
required

Session id named in the request.

total
null | integer
required

Total matching buckets when known; null when the snapshot cannot count them cheaply.

Required range: 0 <= x <= 9007199254740991