# Usage

> Workspace-level spend analytics and CEL pricing previews. Per-task charges are documented in Tasks: get task cost.

**URL:** https://inference.sh/docs/api/rest/usage
**Last updated:** 2026-10-11

---

Workspace-level spend analytics and CEL pricing previews. Per-task charges are documented in [Tasks: get task cost](/docs/api/rest/tasks#get-task-cost).

Requires API key scope **`billing:read`** unless noted otherwise.

→ [Billing API](/docs/api/rest/billing) — prepaid balance and top-ups  
→ [Extend pricing](/docs/extend/pricing) — CEL formulas for store apps

---

## Usage breakdown

`GET /usage/breakdown`

Returns spend over time grouped by app endpoint (`namespace/name`). Costs come from completed billing records (refunds excluded). Use this to build dashboards or export usage for a date range.

### Query parameters

| Parameter | Default | Values |
|-----------|---------|--------|
| `range` | `30d` | `1h`, `1d`, `7d`, `30d`, `90d` |
| `team_id` | — | Optional. On the **organization workspace** only, narrow the breakdown to one member team's spend. Omit to include every team the org pays for. Other teams cannot filter by another team's id. |

Granularity adjusts with the range: minute buckets for `1h`, hourly for `1d`, daily for `7d` / `30d` / `90d`.

### Response

| Field | Type | Description |
|-------|------|-------------|
| `timeseries` | array | Time buckets with `date` and `per_app` cost map |
| `per_model` | array | Top apps by spend (`app_endpoint`, `call_count`, `cost`) — field name is historical; values are app paths |
| `models` | string[] | App endpoints (`namespace/name`) present in the series |
| `total_cost` | int64 | Sum of costs in **microcents** |
| `period_start`, `period_end` | string | ISO timestamps for the queried window |
| `trend_percent` | number | Optional percent change vs the previous period of equal length |
| `per_team` | array | Spend by member team (`team_id`, `call_count`, `cost` in microcents), costliest first. Populated only on an **organization workspace** breakdown with no `team_id` filter; empty on a single-team breakdown (including a member team or an org workspace filtered to one team). |

Each `per_model[].cost`, each value in `timeseries[].per_app`, and each `per_team[].cost` is in **microcents** (1 USD = 100,000,000). See [Billing API — Money units](/docs/api/rest/billing#money-units).

**Example:**

```bash
curl "https://api.inference.sh/usage/breakdown?range=7d" \
  -H "Authorization: Bearer inf_your_key"
```

```json
{
  "timeseries": [
    {
      "date": "2026-05-28",
      "per_app": {
        "myteam/flux-dev": 250000000,
        "infsh/echo": 50000000
      }
    }
  ],
  "per_model": [
    {
      "app_endpoint": "myteam/flux-dev",
      "call_count": 42,
      "cost": 1200000000
    }
  ],
  "models": ["myteam/flux-dev", "infsh/echo"],
  "total_cost": 1500000000,
  "period_start": "2026-05-28T00:00:00Z",
  "period_end": "2026-06-04T12:00:00Z",
  "trend_percent": 12.5
}
```

---

## Usage summary

`GET /usage/summary`

Aggregates **usage events** for the workspace (resource-time and model usage), not dollar totals. For spend by app, use [Usage breakdown](#usage-breakdown) or [Get task cost](/docs/api/rest/tasks#get-task-cost).

### Response

| Field | Type | Description |
|-------|------|-------------|
| `tier_usage` | object | Seconds by infrastructure tier (`cloud`, `private`) |
| `type_usage` | object | Seconds by usage event type |
| `model_usage` | object | Seconds by model identifier |
| `total_usage` | int64 | Sum of all event quantities, normalized to **seconds** |

New usage events record run time in **milliseconds** (`unit: "milliseconds"`). Older events used whole **seconds**. The summary aggregates both into second totals (millisecond quantities are summed and divided by 1000).

**Example:**

```bash
curl https://api.inference.sh/usage/summary \
  -H "Authorization: Bearer inf_your_key"
```

```json
{
  "tier_usage": {
    "cloud": 3600,
    "private": 1200
  },
  "type_usage": {
    "gpu": 3000,
    "cpu": 1800
  },
  "model_usage": {
    "A100": 2400
  },
  "total_usage": 4800
}
```

---

## Evaluate CEL pricing

`POST /usage/cel/evaluate`

Preview [CEL pricing expressions](/docs/extend/pricing) before publishing a store app. Pass draft `AppPricing`, sample `output_meta`, optional `resources`, `usage_seconds`, and `task_inputs`. The API returns evaluated fee components and any expression errors.

Live task billing measures run time to the millisecond (see [Run time for resource fees](/docs/extend/pricing#run-time-for-resource-fees)). This preview endpoint still accepts **`usage_seconds`** as a whole number; the API multiplies it by 1000 before evaluating expressions.

Requires **`billing:read`**.

### Request body

| Field | Type | Description |
|-------|------|-------------|
| `pricing` | object | `AppPricing` with `prices` and fee expressions |
| `output_meta` | object | Sample inputs/outputs for usage-based formulas |
| `resources` | array | Resource rows with rates (for `resource_expression`) |
| `usage_seconds` | int64 | Elapsed seconds for resource pricing |
| `task_inputs` | object | Raw task input map for `get(task_inputs, ...)` |

### Response

| Field | Description |
|-------|-------------|
| `resource_fee`, `inference_fee`, `royalty_fee`, `partner_fee`, `total` | Each has `value` (microcents) and optional `error` |
| `description` | Evaluated listing description (`value` string, optional `error`) |

**Example:**

```bash
curl -X POST https://api.inference.sh/usage/cel/evaluate \
  -H "Authorization: Bearer inf_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing": {
      "prices": { "per_image": 200000 },
      "inference_expression": "image_count(output_meta.outputs) * prices.per_image"
    },
    "output_meta": {
      "inputs": [],
      "outputs": [{ "type": "image", "count": 2 }]
    },
    "usage_seconds": 45
  }'
```

---

## Per-task cost

`GET /usage/tasks/{taskID}/cost` — requires `apps:read` or `billing:read`. Documented in [Tasks API](/docs/api/rest/tasks#get-task-cost).

---

## Related

| Guide | Topic |
|-------|--------|
| [Billing API](/docs/api/rest/billing) | Balance, checkout, and payment methods |
| [Entitlements API](/docs/api/rest/entitlements) | Plan limits (not dollar usage) |
| [Extend pricing](/docs/extend/pricing) | Authoring CEL formulas |
| [Tasks API](/docs/api/rest/tasks) | Run apps and per-task cost |