> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get resource usage

> Query live sandbox CPU counters and memory 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](/api-reference/v2/sandboxes/get). Authenticate with your Tensorlake API key:

```bash theme={null}
curl "${SANDBOX_URL%/}/api/v1/resource-usage" \
  -H "Authorization: Bearer $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:

```text theme={null}
delta_total = second.cpu_total_ticks - first.cpu_total_ticks
delta_idle = second.cpu_idle_ticks - first.cpu_idle_ticks
cpu_percent = 100 * (1 - delta_idle / delta_total)
```

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`.


## OpenAPI

````yaml get /api/v1/resource-usage
openapi: 3.1.0
info:
  title: Tensorlake API
  description: Tensorlake Cloud APIs for Sandboxes and Serverless Workflows
  license:
    name: ''
  version: 0.1.0
servers:
  - url: https://api.tensorlake.ai/
security:
  - bearerAuth: []
tags:
  - name: Tensorlake Cloud API
    description: Tensorlake Cloud APIs for Sandboxes and Serverless Workflows
paths:
  /api/v1/resource-usage:
    servers:
      - url: https://{identifier}.sandbox.tensorlake.ai
        description: >-
          Example sandbox proxy host for a specific running sandbox. For
          programmatic access, use the sandbox's `ingress_endpoint`.
        variables:
          identifier:
            default: example-sandbox
            description: The sandbox ID or sandbox name.
    get:
      tags:
        - sandbox-runtime
      summary: Get resource usage
      description: >
        Read one current CPU and memory sample from inside the sandbox.

        Use the `sandbox_url` returned by the sandbox API and authenticate with

        your Tensorlake API key. No request parameters are required.


        CPU counters are cumulative across all guest CPUs. Calculate utilization

        between two samples as `100 * (1 - delta_idle_ticks /
        delta_total_ticks)`.

        The result is a percentage of total guest CPU capacity, from 0 to 100.

        This calculation treats I/O wait as idle and includes steal time in
        utilization.

        Start a new baseline if the timestamp or either counter moves backward,

        or if `cpu_limit_cores` changes. Skip intervals with no increase in
        total ticks.


        `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`.

        Each request reads a fresh sample;

        this endpoint does not retain or return historical data.
      operationId: sandbox_runtime_resource_usage
      responses:
        '200':
          description: Current guest CPU and memory counters
          headers:
            Cache-Control:
              description: Samples must not be cached.
              schema:
                type: string
                enum:
                  - no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxResourceUsage'
              example:
                observed_at_ms: 1792400000000
                cpu_total_ticks: 240000
                cpu_idle_ticks: 180000
                clock_ticks_per_second: 100
                cpu_limit_cores: 2
                memory_used_bytes: 536870912
                memory_available_bytes: 1610612736
                memory_limit_bytes: 2147483648
                source: guest_procfs
        '401':
          description: Unauthorized. Invalid or missing credentials
        '403':
          description: Forbidden. Your API key does not grant access to this sandbox
        '404':
          description: Sandbox not found
        '422':
          description: Guest resource sampling is unsupported on this operating system
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxProxyError'
              example:
                error: Guest resource usage is temporarily unavailable.
                code: RESOURCE_USAGE_UNSUPPORTED
        '503':
          description: Guest resource counters could not be read or parsed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxProxyError'
              example:
                error: Guest resource usage is temporarily unavailable.
                code: RESOURCE_USAGE_UNAVAILABLE
components:
  schemas:
    SandboxResourceUsage:
      type: object
      required:
        - observed_at_ms
        - cpu_total_ticks
        - cpu_idle_ticks
        - clock_ticks_per_second
        - cpu_limit_cores
        - memory_used_bytes
        - memory_available_bytes
        - memory_limit_bytes
        - source
      properties:
        observed_at_ms:
          type: integer
          format: int64
          description: >-
            Sample time in Unix milliseconds, recorded after reading both CPU
            and memory counters.
        cpu_total_ticks:
          type: integer
          format: int64
          minimum: 0
          description: >-
            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.
        cpu_idle_ticks:
          type: integer
          format: int64
          minimum: 0
          description: >-
            Cumulative idle and iowait ticks across all guest CPUs. This is a
            subset of cpu_total_ticks.
        clock_ticks_per_second:
          type: integer
          format: int64
          minimum: 1
          description: >-
            Linux USER_HZ, the number of clock ticks per second. Divide ticks by
            this value to convert them to CPU seconds.
        cpu_limit_cores:
          type: integer
          format: int64
          minimum: 1
          description: Number of guest CPU rows exposed by Linux procfs.
        memory_used_bytes:
          type: integer
          format: int64
          minimum: 0
          description: >-
            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.
        memory_available_bytes:
          type: integer
          format: int64
          minimum: 0
          description: >-
            Guest MemAvailable, in bytes. Estimates memory available for new
            workloads, accounting for reclaimable caches.
        memory_limit_bytes:
          type: integer
          format: int64
          minimum: 0
          description: Guest MemTotal, in bytes.
        source:
          type: string
          enum:
            - guest_procfs
          description: >-
            Counters read from Linux /proc/stat and /proc/meminfo inside the
            sandbox.
    SandboxProxyError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        code:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.