> ## 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 offsets_ms. A tree whose compute was released and revived has several attachments; follow revived_from_sandbox_id 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 sampling_source=unsupported means the sandbox could not measure itself. ## OpenAPI ````yaml /managed-agents/openapi.yaml get /managed-agents/v1/sessions/{session_id}/resource-samples openapi: 3.1.0 info: title: Managed Agents API version: 0.13.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/v1/sessions/{session_id}/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 offsets_ms. A tree whose compute was released and revived has several attachments; follow revived_from_sandbox_id 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 sampling_source=unsupported means the sandbox could not measure itself. operationId: managedAgentsListSessionResourceSamples parameters: - description: >- Inclusive lower bound on bucket_start, RFC 3339. Omit for the start of the tree. in: query name: from schema: description: >- Inclusive lower bound on bucket_start, RFC 3339. Omit for the start of the tree. format: date-time type: string - description: Exclusive upper bound on bucket_start, RFC 3339. Omit for now. in: query name: to schema: description: Exclusive upper bound on bucket_start, RFC 3339. Omit for now. format: date-time type: string - 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 next_page_token. Bound to the organization, session, and filters it was issued for. in: query name: page_token schema: description: >- Signed continuation token from a previous page's next_page_token. 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: session_id 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 responses: '200': content: application/json: schema: $ref: >- #/components/schemas/ManagedAgentsSessionResourceSamplesResponse description: >- Sandbox CPU, memory, and accelerator usage for a session tree, as minute buckets per sandbox attachment. Samples are what the sandbox measured of itself, collected on tool calls and on read. '400': description: The request was rejected by schema or semantic validation. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '401': description: The caller is unauthenticated. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '403': description: The caller lacks a required permission or capability. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' '404': description: No such resource is reachable for this caller. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '429': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A rate limit is exhausted. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '500': description: An unexpected server-side failure. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '502': description: The service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorBadGateway' '503': headers: Retry-After: description: Seconds the caller should wait before retrying. schema: type: string style: simple description: A dependency is unavailable. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiError' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string description: The service did not respond before the timeout. Retryable. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout' components: schemas: ManagedAgentsSessionResourceSamplesResponse: description: >- Sandbox CPU, memory, and accelerator usage for a session tree, as minute buckets per sandbox attachment. Samples are what the sandbox measured of itself, collected on tool calls and on read. properties: as_of: description: RFC 3339 server time at which the page was read. format: date-time type: string buckets: 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/ManagedAgentsResourceSampleBucket' 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 next_page_token: description: >- Present when more buckets remain. Pass as page_token with the same query to continue. type: string resolution: description: Resolution the buckets were read at. enum: - minute - raw type: string root_session_id: 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/ManagedAgentsSessionSandbox' type: array session_id: description: Session id named in the request. type: string required: - session_id - root_session_id - resolution - live - sandboxes - buckets - as_of type: object example: as_of: '2026-02-18T09:30:00.000Z' buckets: - bucket_start: '2026-02-18T09:30:00.000Z' complete: true cpu_capacity_millicores: 1 cpu_limit_millicores: 1 cpu_millicores: - 1 cpu_millicores_avg: 1 cpu_millicores_peak: 1 disk_capacity_bytes: 1 disk_used_avg_bytes: 1 disk_used_bytes: - 1 disk_used_peak_bytes: 1 gpu_count: 1 gpu_devices: - index: 1 memory_total_bytes: 1 memory_used_peak_bytes: 1 utilization_avg: 1.5 utilization_peak: 1.5 gpu_memory_total_bytes: 1 gpu_memory_used_bytes: - 1 gpu_memory_used_peak_bytes: 1 gpu_utilization_avg: 1.5 gpu_utilization_peak: 1.5 gpu_utilization_percent: - 1.5 interval_ms: 1 memory_capacity_bytes: 1 memory_limit_bytes: 1 memory_working_set_avg_bytes: 1 memory_working_set_bytes: - 1 memory_working_set_peak_bytes: 1 offsets_ms: - 1 received_at: '2026-02-18T09:30:00.000Z' sample_count: 1 sandbox_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d shared_slots: 1 live: true next_page_token: example resolution: minute root_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandboxes: - attached_at: '2026-02-18T09:30:00.000Z' detach_reason: example detached_at: '2026-02-18T09:30:00.000Z' last_drained_at: '2026-02-18T09:30:00.000Z' owner_session_path: example revived_from_sandbox_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d role: user sample_interval_ms: 1 sample_rows: 1 sample_watermark_at: '2026-02-18T09:30:00.000Z' sampling_scope: example sampling_source: example sandbox_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_instance_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_provider: example session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d ManagedAgentsApiError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - analytics - analytics_not_ready - artifact_fetch_unavailable - artifact_generation_mismatch - artifact_hash_mismatch - artifact_invalid_events - artifact_invalid_json - artifact_not_allowlisted - artifact_size_mismatch - atlassian_rate_limited - atlassian_unavailable - atomic_ingest_timeout - auth_unavailable - automation_event_source_invalid - automation_memory_unavailable - automation_reference_invalid - automation_runs_unconfigured - automations_unconfigured - bad_gateway - built_in_catalog_unavailable - built_in_integrations_disabled - built_in_integrations_unconfigured - compute_offerings_unavailable - conflict - content_store_request_canceled - content_store_unavailable - content_store_upload_timeout - credential_encryption_unconfigured - delegate_preparation_failed - entity_family_not_permitted - environment_not_verified - evaluation_cancellation_pending - evaluation_deletion_pending - event_admission_unavailable - event_ingress_unavailable - event_source_verification_credential_invalid - event_sources_unconfigured - execution_unconfigured - file_quota_exceeded - file_storage_unconfigured - forbidden - gateway_timeout - gestalt_unconfigured - github_rate_limited - github_unavailable - handoff_access_invalid - handoff_access_unavailable - handoff_access_unsupported - handoff_capture_unavailable - handoff_requires_retest - handoff_revoke_unavailable - handoff_signal_unavailable - idempotency_conflict - idempotency_in_progress - idempotency_unavailable - ingest_policy_changed - ingest_policy_not_found - ingest_policy_revoked - integrations_unconfigured - internal_error - invalid_json - invalid_pull_request_review_result - invalid_request - invalid_scope - invariant_violation - launchdarkly_rate_limited - launchdarkly_unavailable - live_fleet_unconfigured - managed_agents_unavailable - merge_key_rejected - merge_link_unavailable - merge_rate_limited - merge_unavailable - missing_dependency - model_gateway_metadata_missing - model_gateway_unconfigured - model_gateway_unreachable - mutation_transaction_budget_exceeded - not_found - page_token_expired - payload_too_large - persistence_busy - precondition_failed - precondition_required - provider_registration_unsupported - provider_selection_unsupported - rate_limit_exceeded - rate_limited - repository_automation_unconfigured - request_too_large - reserved_source_type - revision_conflict - run_log_store_unavailable - runner_image_resolution_failed - sandbox_provider_disabled - service_unavailable - session_analyst_busy - session_analyst_model_unavailable - session_analyst_unconfigured - session_start_admission_unavailable - session_start_not_admitted - setup_fallback_environment_unsafe - setup_run_finished - setup_run_in_progress - setup_run_limit - setup_run_not_started - setup_runs_unavailable - skill_storage_unconfigured - slack_channels_rejected - slack_channels_unavailable - slack_channels_unconfigured - slack_connection_malformed - slack_event_intake_unavailable - slack_installation_mismatch - slack_missing_scope - slack_rate_limited - slack_reapproval_required - source_ownership_mismatch - source_revision_conflict - spanner_unavailable - streaming_unsupported - submission_transaction_budget_exceeded - task_version_number_conflict - team_board_unconfigured - too_many_streams - unauthorized - unsupported_media_type - vault_creation_retired - version_content_conflict - webhook_delivery_too_large - workspace_boundary_denied message: type: string minLength: 1 description: Human-readable error message. details: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorBadGateway: 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorGatewayTimeout: 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: description: Optional structured error details. type: object propertyNames: type: string additionalProperties: {} required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsResourceSampleBucket: description: >- One sandbox attachment's resource usage for one minute. Per-sample CPU, memory, and disk readings are parallel arrays indexed by offsets_ms; the average and peak columns summarize the minute and are all a summary-resolution read returns. Capacities and limits give each series its denominator. properties: bucket_start: 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 cpu_capacity_millicores: 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 cpu_limit_millicores: description: CPU quota of the container in millicores, when one is set. type: integer cpu_millicores: description: >- Per-sample CPU consumption in millicores; 1000 is one core fully busy. items: format: int64 type: integer type: array cpu_millicores_avg: description: Mean CPU millicores over the minute. format: int64 type: integer cpu_millicores_peak: description: Highest sampled CPU millicores in the minute. format: int64 type: integer disk_capacity_bytes: 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 disk_used_avg_bytes: description: >- Mean bytes in use on the workspace volume over the minute. Absent without a disk reading. type: integer disk_used_bytes: 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 type: array disk_used_peak_bytes: description: >- Highest sampled bytes in use on the workspace volume in the minute. Absent without a disk reading. type: integer gpu_count: description: >- Number of accelerators visible to the container. Absent without accelerators. type: integer gpu_devices: description: Per-device summary for the minute. Absent without accelerators. items: $ref: '#/components/schemas/ManagedAgentsGPUDeviceMinute' type: array gpu_memory_total_bytes: description: >- Total accelerator memory in bytes across devices. Absent without accelerators. type: integer gpu_memory_used_bytes: description: >- Per-sample GPU memory in use, summed across devices. Absent without accelerators. items: format: int64 type: integer type: array gpu_memory_used_peak_bytes: description: >- Highest sampled GPU memory in use during the minute, in bytes. Absent without accelerators. type: integer gpu_utilization_avg: description: >- Mean GPU utilization percent over the minute. Absent without accelerators. type: number gpu_utilization_peak: description: >- Highest sampled GPU utilization percent in the minute. Absent without accelerators. type: number gpu_utilization_percent: description: >- Per-sample GPU utilization percent, mean across devices. Absent without accelerators. items: format: double type: number type: array interval_ms: description: Producer sampling cadence in milliseconds. format: int64 type: integer memory_capacity_bytes: 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 memory_limit_bytes: description: Memory limit of the container in bytes, when one is set. type: integer memory_working_set_avg_bytes: description: Mean memory working set over the minute, in bytes. format: int64 type: integer memory_working_set_bytes: description: >- Per-sample memory working set in bytes (resident less reclaimable file cache). items: format: int64 type: integer type: array memory_working_set_peak_bytes: description: Highest sampled memory working set in the minute, in bytes. format: int64 type: integer offsets_ms: description: >- Sample times as milliseconds after bucket_start, ascending. Indexes the other per-sample arrays. items: format: int64 type: integer type: array received_at: description: >- RFC 3339 commit timestamp of the write that last touched this bucket. format: date-time type: string sample_count: description: >- Number of samples in the minute; twelve at the default five-second cadence. format: int64 type: integer sandbox_id: description: Attachment the bucket belongs to. type: string shared_slots: 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 required: - sandbox_id - bucket_start - complete - sample_count - interval_ms - cpu_millicores_avg - cpu_millicores_peak - memory_working_set_avg_bytes - memory_working_set_peak_bytes - received_at type: object example: bucket_start: '2026-02-18T09:30:00.000Z' complete: true cpu_capacity_millicores: 1 cpu_limit_millicores: 1 cpu_millicores: - 1 cpu_millicores_avg: 1 cpu_millicores_peak: 1 disk_capacity_bytes: 1 disk_used_avg_bytes: 1 disk_used_bytes: - 1 disk_used_peak_bytes: 1 gpu_count: 1 gpu_devices: - index: 1 memory_total_bytes: 1 memory_used_peak_bytes: 1 utilization_avg: 1.5 utilization_peak: 1.5 gpu_memory_total_bytes: 1 gpu_memory_used_bytes: - 1 gpu_memory_used_peak_bytes: 1 gpu_utilization_avg: 1.5 gpu_utilization_peak: 1.5 gpu_utilization_percent: - 1.5 interval_ms: 1 memory_capacity_bytes: 1 memory_limit_bytes: 1 memory_working_set_avg_bytes: 1 memory_working_set_bytes: - 1 memory_working_set_peak_bytes: 1 offsets_ms: - 1 received_at: '2026-02-18T09:30:00.000Z' sample_count: 1 sandbox_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d shared_slots: 1 ManagedAgentsSessionSandbox: description: >- One continuous residency of a sandbox container in a session tree: when it was bound, when and why it stopped serving, which attachment it continues if the compute was revived from a snapshot, and the state of resource sampling for it. properties: attached_at: description: RFC 3339 timestamp at which the container was bound to the tree. format: date-time type: string detach_reason: description: >- Why the attachment ended: released (compute given back, workspace kept), closed (session ended), replaced (a different container took over), or lost (the sandbox binding was found gone). type: string detached_at: description: >- RFC 3339 timestamp at which the container stopped serving the tree. Absent while attached. format: date-time type: string last_drained_at: description: RFC 3339 timestamp of the last successful drain from the producer. format: date-time type: string owner_session_path: description: >- Tree path of the session that attached the container. '/' for the root. type: string revived_from_sandbox_id: 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 sample_interval_ms: description: Producer sampling cadence in milliseconds. format: int64 type: integer sample_rows: description: Number of minute buckets stored for this attachment. format: int64 type: integer sample_watermark_at: description: >- Start of the newest minute bucket with samples. Absent until the first drain lands data. format: date-time type: string sampling_scope: description: >- What the samples describe: cgroup for one container or host for the whole machine. type: string sampling_source: 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 sandbox_id: 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 sandbox_instance_id: description: >- Provider-assigned identity of the container: a compute id or container id. Historical self_hosted rows may contain a daemon id. type: string sandbox_provider: description: >- Sandbox runtime that provided the container: runs or docker. Historical rows may report the retired self_hosted value. type: string required: - sandbox_id - sandbox_provider - sandbox_instance_id - role - owner_session_path - attached_at - sample_rows type: object example: attached_at: '2026-02-18T09:30:00.000Z' detach_reason: example detached_at: '2026-02-18T09:30:00.000Z' last_drained_at: '2026-02-18T09:30:00.000Z' owner_session_path: example revived_from_sandbox_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d role: user sample_interval_ms: 1 sample_rows: 1 sample_watermark_at: '2026-02-18T09:30:00.000Z' sampling_scope: example sampling_source: example sandbox_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_instance_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d sandbox_provider: example ManagedAgentsGPUDeviceMinute: description: >- One accelerator's summary for a minute bucket: its driver index, average and peak utilization, peak memory used, and total memory. The per-sample GPU arrays, and the -1 holes for samples the device did not report, live on the bucket itself. properties: index: description: Device index as the driver reports it. type: integer memory_total_bytes: description: Device memory capacity in bytes. format: int64 type: integer memory_used_peak_bytes: description: Highest sampled device memory in use during the minute, in bytes. format: int64 type: integer utilization_avg: description: Mean utilization percent across the minute's samples. format: double type: number utilization_peak: description: Highest sampled utilization percent in the minute. format: double type: number required: - index - utilization_avg - utilization_peak - memory_used_peak_bytes - memory_total_bytes type: object example: index: 1 memory_total_bytes: 1 memory_used_peak_bytes: 1 utilization_avg: 1.5 utilization_peak: 1.5 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````