---
title: "GPU, RAM, and ANE utilization"
method: GET
path: "/v1/system/resources"
tags: ["System"]
---

# GPU, RAM, and ANE utilization

`GET /v1/system/resources`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/system/resources`
- Auth: HTTP bearer

Returns the latest cached snapshot and probes nothing. Pass
`detail=models` to also receive per-model memory footprint with its
confidence, the host budget, pressure and running engine processes,
collected once for this request. No detail is collected for callers
that do not ask for it.

## Query parameters

- `detail` 'models'

## Response `200`

System resource snapshot

- SystemResources: GPU, RAM, and ANE utilization snapshot
  - `gpu` GpuResources, required
    - `thermalState` 'nominal' | 'fair' | 'serious' | 'critical', required
    - `metalAllocatedBytes` number, required
    - `metalMaxBytes` number, required
    - `allocatedSystemBytes` number: IOKit "Alloc system memory" (system-wide GPU)
    - `inUseSystemBytes` number: IOKit "In use system memory" (system-wide GPU)
    - `deviceUtilization` number: IOKit "Device Utilization %" (0-100)
  - `memory` MemoryResources, required
    - `totalBytes` number, required
    - `availableBytes` number, required
    - `usedBytes` number, required
  - `ane` AneResources, required
    - `active` boolean, required
    - `backendIds` string[], required
  - `timestamp` string, date-time, required
  - `detail` ResourceDetail: Present only when requested with `detail=models`
    - `models` object[], required
      - `modelId` string, required
      - `estimated` integer, required: Estimated bytes
      - `measured` integer: Bytes from the persisted memory profile, when present
      - `gpu` integer
      - `confidence` 'estimated' | 'measured' | 'refined', required
    - `children` object[], required
      - `backendId` string, required
      - `pid` integer, required
      - `physFootprint` number, required
      - `neuralFootprint` number, required
    - `budget` object, required
      - `used` integer, required
      - `available` integer, required: Effective total allowance, not remaining bytes
      - `total` integer, required: Physical memory
    - `pressure` 'none' | 'warning' | 'critical', required: Last polled memory pressure level

## Other responses

- `400`: Unsupported `detail` value
- `503`: Resource monitoring or model management is not ready

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)