# Get usage and cost

> Get what your resources have cost in a period and what they are costing right now.

> Nevia is in early access for selected teams. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/reference/api/usage/getUsage

`GET https://api.nevia.cloud/v1/usage`

## Authorization

- `bearerAuth`: HTTP bearer in the Authorization header

Send the token in the `Authorization: Bearer <token>` header. See [Authenticate](https://nevia.cloud/docs/reference/api.md#authenticate).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `workspace` | query | array<string> | no | Workspace ids or exact names. When one is absent the answer covers every workspace the caller can see. |
| `resource` | query | array<string> | no | Computer or database ids, or their exact names together with `workspace`. Sessions come only when exactly one is chosen. |
| `kind` | query | string | no | When present, every figure covers only resources of this kind, exactly as if the other kind did not exist. The other kind's `by_kind` figure reads zero. One of `computer` · `database`. |
| `from` | query | string (date-time) | no | Period start, RFC 3339, inclusive. Defaults to the start of the current month. |
| `to` | query | string (date-time) | no | Period end, RFC 3339, exclusive. Defaults to now. |
| `series_from` | query | string (date-time) | no | Where the chart's buckets start, RFC 3339, when they read farther back than the billed range. Must be at or before `from`, and defaults to it. The figures still count the range exactly, and only the series extends back. |
| `granularity` | query | string | no | Bucket size of the series. One of `minute` · `hour` · `day`. |

## Behavior

Without `workspace`, the answer covers every workspace you can see and lists each one's share. With one or more `workspace`s, it lists those workspaces' resources. With `resource`, it is about those resources. With `kind`, every figure covers only resources of that kind, exactly as if the other kind did not exist and its `by_kind` figure read zero. Amounts are decimal strings in USD, exact as metered and never rounded, so every total is the sum of its parts. Usage counts for the time it spent inside the period, wherever it began or ended. The period defaults to the current month so far and may span at most 92 days. The chart (the `series`) may read back from an earlier `series_from`, one request answering the bill and the chart in a single walk. Answers `503 not_supported` where metering is not deployed.

## Example request

### cURL

```bash
curl -X GET "https://api.nevia.cloud/v1/usage" \
  -H "Authorization: Bearer $TOKEN"
```

### JavaScript

```js
fetch("https://api.nevia.cloud/v1/usage", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.TOKEN}`
  }
})
```

### Python

```python
import os
import requests

url = "https://api.nevia.cloud/v1/usage"

response = requests.request("GET", url, headers = {
  "Authorization": f"Bearer {os.environ['TOKEN']}"
})

print(response.text)
```

## Responses

### 200

Your usage.

Content type: `application/json`

Schema: `MeteredUsageResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `usage` | MeteredUsage | yes |  |

Example:

```json
{
  "usage": {
    "currency": "USD",
    "period": {
      "starts_at": "2026-10-01T00:00:00.000Z",
      "ends_at": "2026-10-30T09:00:00.000Z"
    },
    "measured_at": "2026-10-30T09:00:00.000Z",
    "total_usd": "0.025871973333",
    "settled": {
      "compute_usd": "0.0209",
      "memory_usd": "0.003483333333",
      "storage_usd": "0.00007364",
      "total_usd": "0.024456973333",
      "vcpu_hours": 0.348,
      "memory_gib_hours": 0.348,
      "storage_gib_hours": 0.2688,
      "running_hours": 0.348
    },
    "usage": {
      "vcpu_hours": 0.348,
      "memory_gib_hours": 0.348,
      "storage_gib_hours": 0.2688,
      "running_hours": 0.348
    },
    "accruing": {
      "compute_usd": "0.0012",
      "memory_usd": "0.0002",
      "storage_usd": "0.000015",
      "total_usd": "0.001415",
      "running_resources": 1,
      "per_hour": {
        "compute_usd": "0.12",
        "memory_usd": "0.02",
        "storage_usd": "0.00",
        "total_usd": "0.14"
      },
      "per_hour_usage": {
        "vcpu_hours": 1,
        "memory_gib_hours": 1,
        "storage_gib_hours": 0.5,
        "running_hours": 1
      }
    },
    "rates": [
      {
        "kind": "computer",
        "vcpu_hour_usd": "0.06",
        "memory_gib_hour_usd": "0.01",
        "storage_gib_hour_usd": "0.000273972602",
        "effective_at": "2026-10-29T00:00:00.000Z"
      }
    ],
    "workspaces": [
      {
        "id": "01d4cnjjq40hnnh0nwmkg35nv2h",
        "name": "acme",
        "total_usd": "0.025871973333",
        "settled": {
          "compute_usd": "0.0209",
          "memory_usd": "0.003483333333",
          "storage_usd": "0.00007364",
          "total_usd": "0.024456973333"
        },
        "accruing": {
          "compute_usd": "0.0012",
          "memory_usd": "0.0002",
          "storage_usd": "0.000015",
          "total_usd": "0.001415"
        },
        "usage": {
          "vcpu_hours": 0.348,
          "memory_gib_hours": 0.348,
          "storage_gib_hours": 0.2688,
          "running_hours": 0.348
        }
      }
    ],
    "by_kind": {
      "computer": {
        "settled": {
          "compute_usd": "0.0209",
          "memory_usd": "0.003483333333",
          "storage_usd": "0.00007364",
          "total_usd": "0.024456973333"
        },
        "accruing": {
          "compute_usd": "0.0012",
          "memory_usd": "0.0002",
          "storage_usd": "0.000015",
          "total_usd": "0.001415"
        },
        "per_hour": {
          "compute_usd": "0.12",
          "memory_usd": "0.02",
          "storage_usd": "0.00",
          "total_usd": "0.14"
        },
        "usage": {
          "vcpu_hours": 0.348,
          "memory_gib_hours": 0.348,
          "storage_gib_hours": 0.2688,
          "running_hours": 0.348
        },
        "per_hour_usage": {
          "vcpu_hours": 1,
          "memory_gib_hours": 1,
          "storage_gib_hours": 0.5,
          "running_hours": 1
        }
      },
      "database": {
        "settled": {
          "compute_usd": "0.00",
          "memory_usd": "0.00",
          "storage_usd": "0.00",
          "total_usd": "0.00"
        },
        "accruing": {
          "compute_usd": "0.00",
          "memory_usd": "0.00",
          "storage_usd": "0.00",
          "total_usd": "0.00"
        },
        "per_hour": {
          "compute_usd": "0.00",
          "memory_usd": "0.00",
          "storage_usd": "0.00",
          "total_usd": "0.00"
        },
        "usage": {
          "vcpu_hours": 0,
          "memory_gib_hours": 0,
          "storage_gib_hours": 0,
          "running_hours": 0
        },
        "per_hour_usage": {
          "vcpu_hours": 0,
          "memory_gib_hours": 0,
          "storage_gib_hours": 0,
          "running_hours": 0
        }
      }
    },
    "series": {
      "granularity": "day",
      "buckets": [
        {
          "starts_at": "2026-10-30T00:00:00.000Z",
          "compute_usd": "0.0209",
          "memory_usd": "0.003483333333",
          "storage_usd": "0.00007364",
          "total_usd": "0.024456973333",
          "usage": {
            "vcpu_hours": 0.348,
            "memory_gib_hours": 0.348,
            "storage_gib_hours": 0.2688,
            "running_hours": 0.348
          },
          "peak": {
            "vcpu_hours": 1,
            "memory_gib_hours": 1,
            "storage_gib_hours": 10,
            "running_hours": 1
          },
          "by_kind": {
            "computer": {
              "compute_usd": "0.0209",
              "memory_usd": "0.003483333333",
              "storage_usd": "0.00007364",
              "total_usd": "0.024456973333",
              "usage": {
                "vcpu_hours": 0.348,
                "memory_gib_hours": 0.348,
                "storage_gib_hours": 0.2688,
                "running_hours": 0.348
              },
              "peak": {
                "vcpu_hours": 1,
                "memory_gib_hours": 1,
                "storage_gib_hours": 10,
                "running_hours": 1
              }
            },
            "database": {
              "compute_usd": "0.00",
              "memory_usd": "0.00",
              "storage_usd": "0.00",
              "total_usd": "0.00",
              "usage": {
                "vcpu_hours": 0,
                "memory_gib_hours": 0,
                "storage_gib_hours": 0,
                "running_hours": 0
              },
              "peak": {
                "vcpu_hours": 0,
                "memory_gib_hours": 0,
                "storage_gib_hours": 0,
                "running_hours": 0
              }
            }
          }
        }
      ]
    }
  }
}
```

### 400

`validation_failed`: malformed body, unknown field, or invalid id or name. Fix `details.field` and retry.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `validation_failed`:

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Unknown field `colour` in the request body. Remove it; request bodies are strict.",
    "details": {
      "field": "colour",
      "in": "body"
    }
  }
}
```

### 401

`unauthorized`: the credential is missing, malformed, expired, or revoked. Send a valid bearer token.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `unauthorized`:

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Missing credential. Send `Authorization: Bearer <token>` with an access token.",
    "details": {}
  }
}
```

### 404

`not_found`: absent, or outside the caller's access. Both cases return the same response. Check the id.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `not_found`:

```json
{
  "error": {
    "code": "not_found",
    "message": "Computer 01d4cnjk3xg90y576w8y6t4gdwm was not found. List the computers you can access with GET /v1/computers?workspace=<ws>.",
    "details": {
      "computer": "01d4cnjk3xg90y576w8y6t4gdwm"
    }
  }
}
```

### 429

`rate_limited`: slow down. Retry after `Retry-After`.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `rate_limited`:

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 2 seconds.",
    "details": {
      "retry_after_seconds": 2
    }
  }
}
```

### 500

`request_failed`, or the failed action's own code, such as `creation_failed`, `authorization_failed` or `command_execution_failed`. The diagnostic stays in server logs.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `request_failed`:

```json
{
  "error": {
    "code": "request_failed",
    "message": "request failed",
    "details": {}
  }
}
```

### 503

The action is temporarily unavailable, named by its code (`creation_failed`, `wake_failed`, ...). Wait at least `Retry-After` seconds (60 by default). `details.retryable` says whether repeating the request is safe. Keep the original `Idempotency-Key`. Signing in again does not help.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `creation_failed`:

```json
{
  "error": {
    "code": "creation_failed",
    "message": "The computer could not be created. Try again later.",
    "details": {
      "retryable": true
    }
  }
}
```
