Skip to main content
GET
Get resource usage
Get one current CPU and memory sample from inside your sandbox. Use this endpoint to poll live resource usage; it does not return historical samples.

Example request

Set SANDBOX_URL to the sandbox_url returned by Get Sandbox. Authenticate with your Tensorlake API key:

CPU utilization

CPU counters accumulate across all guest CPUs. Take two samples and calculate utilization as a percentage of total guest CPU capacity:
This calculation treats I/O wait as idle and includes steal time in utilization. For example, an increase of 200 total ticks and 50 idle ticks means 75% utilization across the guest CPUs. Start a new baseline if the timestamp or either counter moves backward, or if cpu_limit_cores changes. Skip intervals where delta_total is zero.

Memory usage

memory_used_bytes is calculated as (MemTotal − MemAvailable) × 1024 using the sandbox’s /proc/meminfo. MemAvailable is the kernel’s estimate of memory available for new workloads, accounting for reclaimable caches. This follows the used-memory calculation documented by Linux free.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Response

Current guest CPU and memory counters

observed_at_ms
integer<int64>
required

Sample time in Unix milliseconds, recorded after reading both CPU and memory counters.

cpu_total_ticks
integer<int64>
required

Cumulative CPU ticks across all guest CPUs, including user, nice, system, idle, iowait, irq, softirq, and steal. Guest and guest_nice are already included in user and nice and are not counted again.

Required range: x >= 0
cpu_idle_ticks
integer<int64>
required

Cumulative idle and iowait ticks across all guest CPUs. This is a subset of cpu_total_ticks.

Required range: x >= 0
clock_ticks_per_second
integer<int64>
required

Linux USER_HZ, the number of clock ticks per second. Divide ticks by this value to convert them to CPU seconds.

Required range: x >= 1
cpu_limit_cores
integer<int64>
required

Number of guest CPU rows exposed by Linux procfs.

Required range: x >= 1
memory_used_bytes
integer<int64>
required

Calculated as (MemTotal − MemAvailable) × 1024 using the sandbox’s /proc/meminfo. MemAvailable is the kernel’s estimate of memory available for new workloads, accounting for reclaimable caches. This follows the used-memory calculation documented by Linux free.

Required range: x >= 0
memory_available_bytes
integer<int64>
required

Guest MemAvailable, in bytes. Estimates memory available for new workloads, accounting for reclaimable caches.

Required range: x >= 0
memory_limit_bytes
integer<int64>
required

Guest MemTotal, in bytes.

Required range: x >= 0
source
enum<string>
required

Counters read from Linux /proc/stat and /proc/meminfo inside the sandbox.

Available options:
guest_procfs