---
title: "List VM usage records"
url: https://hexelstudio.com/docs/api/compute/usage/list
---

# List VM usage records

**GET** `/compute/v1/usage`

Returns VM usage records for the caller's org, optionally filtered by date range and tier

## Query parameters

- `from: optional string`

  Start date (YYYY-MM-DD), default 30 days ago

- `to: optional string`

  End date (YYYY-MM-DD), default today

- `tier: optional string`

  Filter by tier

- `limit: optional integer`

  Max records (default 100)

- `offset: optional integer`

  Offset for pagination

## Headers

- `Authorization: string`

  `Bearer <token>`. STS access token. Obtain via POST https://sts.hexelstudio.com/token with X-API-Key header.

- `X-Workspace-Id: string`

  Workspace ID

- `X-Environment-Id: string`

  Environment ID

## Returns

`200` OK (`array of UsageRecord`)

- `duration_seconds: optional integer`

- `ended_at: optional string`

- `reason: optional string`

- `started_at: optional string`

- `tier: optional string`

- `vm_id: optional string`

## Errors

- `500` Internal Server Error

## Example

```bash
curl --request GET \
  --url 'https://compute.hexelstudio.com/compute/v1/usage' \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'X-Workspace-Id: X_WORKSPACE_ID' \
  --header 'X-Environment-Id: X_ENVIRONMENT_ID'
```

### Response (200)

```json
[
  {
    "duration_seconds": 0,
    "ended_at": "2026-01-01T00:00:00Z",
    "reason": "string",
    "started_at": "2026-01-01T00:00:00Z",
    "tier": "string",
    "vm_id": "string"
  }
]
```

### Response (500)

```json
{
  "code": 0,
  "error_code": "string",
  "message": "string"
}
```