> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Read sandbox CPU, memory, and GPU usage for a session tree > Returns the tree's sandbox attachments and one page of per-minute resource usage buckets for them, ordered by attachment then time. Each bucket carries the minute's average and peak; resolution=raw adds the individual samples as parallel arrays indexed by offsetsMs. A tree whose compute was released and revived has several attachments; follow revivedFromSandboxId to connect them. live reports whether a sandbox is still attached, which is the cue to keep polling. An empty sandboxes list means the tree never ran in a sandbox or sampling is disabled; an attachment with samplingSource=unsupported means the sandbox could not measure itself. ## OpenAPI ````yaml /recursion/openapi.yaml get /managed-agents/v2/sessions/{sessionId}/resource-samples openapi: 3.1.0 info: title: Managed Agents API version: 0.15.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v2/sessions/{sessionId}/resource-samples: get: tags: - Sessions summary: Read sandbox CPU, memory, and GPU usage for a session tree description: >- Returns the tree's sandbox attachments and one page of per-minute resource usage buckets for them, ordered by attachment then time. Each bucket carries the minute's average and peak; resolution=raw adds the individual samples as parallel arrays indexed by offsetsMs. A tree whose compute was released and revived has several attachments; follow revivedFromSandboxId to connect them. live reports whether a sandbox is still attached, which is the cue to keep polling. An empty sandboxes list means the tree never ran in a sandbox or sampling is disabled; an attachment with samplingSource=unsupported means the sandbox could not measure itself. operationId: managedAgentsListSessionResourceSamplesV2 parameters: - description: >- Inclusive lower bound on bucketStartedAt, RFC 3339. Omit for the start of the tree. in: query name: bucketStartedAtGte schema: description: >- Inclusive lower bound on bucketStartedAt, RFC 3339. Omit for the start of the tree. format: date-time type: string x-recursion-omission: strategy: absent - description: Exclusive upper bound on bucketStartedAt, RFC 3339. Omit for now. in: query name: bucketStartedAtLt schema: description: Exclusive upper bound on bucketStartedAt, RFC 3339. Omit for now. format: date-time type: string x-recursion-omission: strategy: absent - description: >- 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. in: query name: resolution schema: default: minute description: >- 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. enum: - minute - raw type: string - description: >- Maximum buckets per page, across all of the tree's sandbox attachments. in: query name: limit schema: default: 120 description: >- Maximum buckets per page, across all of the tree's sandbox attachments. maximum: 720 minimum: 1 type: integer - description: >- Signed continuation token from a previous page's nextCursor. Bound to the organization, session, and filters it was issued for. in: query name: cursor schema: description: >- Signed continuation token from a previous page's nextCursor. Bound to the organization, session, and filters it was issued for. type: string - description: >- Any session id (UUID) in the tree. The sandbox is shared by the whole tree, so every id in it returns the same usage. in: path name: sessionId required: true schema: description: >- Any session id (UUID) in the tree. The sandbox is shared by the whole tree, so every id in it returns the same usage. format: uuid type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' responses: '200': content: application/json: schema: $ref: >- #/components/schemas/StandaloneV2SessionResourceSamplesResponse description: OK headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '404': description: Not Found. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' x-recursion-error-codes: - not_found headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - managed_agents_unavailable - service_unavailable '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: A dependent service timed out. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout' x-recursion-error-codes: - gateway_timeout components: parameters: RecursionTenantId: name: x-tenant-id in: header required: false description: >- Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is `default`. schema: minLength: 1 type: string RecursionOrganizationId: name: x-organization-id in: header required: false description: >- 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`. schema: minLength: 1 type: string schemas: StandaloneV2SessionResourceSamplesResponse: properties: asOf: description: RFC 3339 server time at which the page was read. format: date-time type: string items: description: >- 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. items: $ref: '#/components/schemas/StandaloneV2ResourceSampleBucket' type: array live: description: >- 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. type: boolean nextCursor: description: Cursor for the next page, or null on the last page. type: - 'null' - string resolution: description: Resolution the buckets were read at. enum: - minute - raw type: string rootSessionId: description: Root of the tree the usage belongs to. type: string sandboxes: description: >- 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. items: $ref: '#/components/schemas/StandaloneV2SessionSandbox' type: array sessionId: description: Session id named in the request. type: string total: description: >- Total matching buckets when known; null when the snapshot cannot count them cheaply. minimum: 0 type: - 'null' - integer maximum: 9007199254740991 required: - sessionId - rootSessionId - resolution - live - sandboxes - items - nextCursor - total - asOf type: object additionalProperties: false ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyFailure: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. StandaloneV2ResourceSampleBucket: properties: bucketStart: description: RFC 3339 timestamp of the minute's start, on the producer's clock. format: date-time type: string complete: description: >- True once the producer has moved past this minute. An incomplete bucket is the one being filled and is rewritten by the next drain. type: boolean cpuCapacityMillicores: description: >- CPU the container could use in millicores: its quota when set, otherwise the CPUs its cpuset allows. Divide cpu_millicores by this for utilization percent. type: integer minimum: -9007199254740991 maximum: 9007199254740991 cpuLimitMillicores: description: CPU quota of the container in millicores, when one is set. type: integer minimum: -9007199254740991 maximum: 9007199254740991 cpuMillicores: description: >- Per-sample CPU consumption in millicores; 1000 is one core fully busy. items: format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: array cpuMillicoresAvg: description: Mean CPU millicores over the minute. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 cpuMillicoresPeak: description: Highest sampled CPU millicores in the minute. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 diskCapacityBytes: description: >- Bytes the workspace volume can hold for an unprivileged writer (size less the root reserve). Divide disk_used by this for utilization percent. type: integer minimum: -9007199254740991 maximum: 9007199254740991 diskUsedAvgBytes: description: >- Mean bytes in use on the workspace volume over the minute. Absent without a disk reading. type: integer minimum: -9007199254740991 maximum: 9007199254740991 diskUsedBytes: description: >- Per-sample bytes in use on the volume holding the workspace. -1 marks a sample without a disk reading. Absent when the producer never saw the volume. items: format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: array diskUsedPeakBytes: description: >- Highest sampled bytes in use on the workspace volume in the minute. Absent without a disk reading. type: integer minimum: -9007199254740991 maximum: 9007199254740991 gpuCount: description: >- Number of accelerators visible to the container. Absent without accelerators. type: integer minimum: -9007199254740991 maximum: 9007199254740991 gpuDevices: description: Per-device summary for the minute. Absent without accelerators. items: $ref: '#/components/schemas/StandaloneV2GPUDeviceMinute' type: array gpuMemoryTotalBytes: description: >- Total accelerator memory in bytes across devices. Absent without accelerators. type: integer minimum: -9007199254740991 maximum: 9007199254740991 gpuMemoryUsedBytes: description: >- Per-sample GPU memory in use, summed across devices. Absent without accelerators. items: format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: array gpuMemoryUsedPeakBytes: description: >- Highest sampled GPU memory in use during the minute, in bytes. Absent without accelerators. type: integer minimum: -9007199254740991 maximum: 9007199254740991 gpuUtilizationAvg: description: >- Mean GPU utilization percent over the minute. Absent without accelerators. type: number gpuUtilizationPeak: description: >- Highest sampled GPU utilization percent in the minute. Absent without accelerators. type: number gpuUtilizationPercent: description: >- Per-sample GPU utilization percent, mean across devices. Absent without accelerators. items: format: double type: number type: array intervalMs: description: Producer sampling cadence in milliseconds. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 memoryCapacityBytes: description: >- Memory the container could use in bytes: its limit when set, otherwise the machine's total. Divide the working set by this for utilization percent. type: integer minimum: -9007199254740991 maximum: 9007199254740991 memoryLimitBytes: description: Memory limit of the container in bytes, when one is set. type: integer minimum: -9007199254740991 maximum: 9007199254740991 memoryWorkingSetAvgBytes: description: Mean memory working set over the minute, in bytes. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 memoryWorkingSetBytes: description: >- Per-sample memory working set in bytes (resident less reclaimable file cache). items: format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: array memoryWorkingSetPeakBytes: description: Highest sampled memory working set in the minute, in bytes. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 offsetsMs: description: >- Sample times as milliseconds after bucket_start, ascending. Indexes the other per-sample arrays. items: format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 type: array receivedAt: description: >- RFC 3339 commit timestamp of the write that last touched this bucket. format: date-time type: string sampleCount: description: >- Number of samples in the minute; twelve at the default five-second cadence. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 sandboxId: description: Attachment the bucket belongs to. type: string sharedSlots: description: >- Historical count of sessions that shared the retired environment worker's process boundary, including this one. Absent on samples from active providers. type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - sandboxId - bucketStart - complete - sampleCount - intervalMs - cpuMillicoresAvg - cpuMillicoresPeak - memoryWorkingSetAvgBytes - memoryWorkingSetPeakBytes - receivedAt type: object additionalProperties: false StandaloneV2SessionSandbox: properties: attachedAt: description: RFC 3339 timestamp at which the container was bound to the tree. format: date-time type: string detachReason: description: >- Why the attachment ended: released (compute given back, workspace kept), closed (session ended), replaced (a different container took over), idle_stopped (the provider stopped an idle compute, workspace kept), or lost (the sandbox binding was found gone). type: string detachedAt: description: >- RFC 3339 timestamp at which the container stopped serving the tree. Absent while attached. format: date-time type: string lastDrainedAt: description: RFC 3339 timestamp of the last successful drain from the producer. format: date-time type: string ownerSessionPath: description: >- Tree path of the session that attached the container. '/' for the root. type: string revivedFromSandboxId: description: >- Attachment this one continues, when the container was restored from the previous attachment's snapshot. type: string role: description: What the container is to the session. Always primary today. type: string sampleIntervalMs: description: Producer sampling cadence in milliseconds. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 sampleRows: description: Number of minute buckets stored for this attachment. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 sampleWatermarkAt: description: >- Start of the newest minute bucket with samples. Absent until the first drain lands data. format: date-time type: string samplingScope: description: >- What the samples describe: cgroup for one container or host for the whole machine. type: string samplingSource: description: >- Producer of this attachment's resource samples: rma_worker or agent_service_daemon. Absent until the first drain, and 'unsupported' when the sandbox cannot measure itself. type: string sandboxId: description: >- Tree-local identifier of this attachment (UUIDv7). A released-and-revived compute is a new attachment; follow revived_from_sandbox_id for its predecessor. type: string sandboxInstanceId: description: >- Provider-assigned identity of the container: a compute id or container id. Historical self_hosted rows may contain a daemon id. type: string sandboxProvider: description: >- Sandbox runtime that provided the container: runs or docker. Historical rows may report the retired self_hosted value. type: string required: - sandboxId - sandboxProvider - sandboxInstanceId - role - ownerSessionPath - attachedAt - sampleRows type: object additionalProperties: false ManagedAgentsApiErrorDetails: type: object properties: field: description: >- Request field or header responsible for the error, when one can be identified. type: string issues: description: >- Boundary-validation failures as path-prefixed human-readable messages. type: array items: type: string requestId: description: Request correlation identifier for support and log lookup. type: string retryable: description: >- Server advice about failure transience. `true` means transient, `false` means non-transient, and absence gives no advice. Automatic replay is allowed only when this field is not `false` and the operation-specific retry and idempotency contract permits replay. type: boolean additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. StandaloneV2GPUDeviceMinute: properties: index: description: Device index as the driver reports it. type: integer minimum: -9007199254740991 maximum: 9007199254740991 memoryTotalBytes: description: Device memory capacity in bytes. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 memoryUsedPeakBytes: description: Highest sampled device memory in use during the minute, in bytes. format: int64 type: integer minimum: -9007199254740991 maximum: 9007199254740991 utilizationAvg: description: Mean utilization percent across the minute's samples. format: double type: number utilizationPeak: description: Highest sampled utilization percent in the minute. format: double type: number required: - index - utilizationAvg - utilizationPeak - memoryUsedPeakBytes - memoryTotalBytes type: object additionalProperties: false PlatformSafeJsonValue: description: >- A JSON value whose integer members stay within the exact ECMAScript safe-integer range at every nesting level. oneOf: - type: 'null' - type: boolean - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: number not: type: integer - type: array items: $ref: '#/components/schemas/PlatformSafeJsonValue' - additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: minLength: 1 type: string RecursionTenantId: description: Tenant id resolved for this request. schema: minLength: 1 type: string securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````