---
title: Usage · API reference
url: https://docs.schemalabs.ai/api-reference/usage
description: Read your organization's usage meter: cells drawn per surface and per operation, percent of the weekly allowance used, and add-usage settings.
---

# Usage

> Read your organization's usage meter: cells drawn per surface and per operation, percent of the weekly allowance used, and add-usage settings.

One organization, one meter. Usage from the platform and from the API draws the same weekly allowance and the same bill; the platform Usage page renders this exact route. The unit is the cell (one row x one column); every operation draws the allowance in proportion to its rate (see [Usage and billing](https://docs.schemalabs.ai/billing)).

Consumption is reported in absolute cells and the allowance as percent used with its reset time. Usage alerts fire at 80% and 100% of the weekly allowance as platform notifications and email.

## Operations

### Retrieve usage

`GET /v2/usage` (scope: `read`)

Returns the organization’s usage for the current allowance period, broken down by surface and by operation.

**Returns**

The usage object.

**Response fields**

- `org` (string): Organization name.
- `plan` (string): Current plan; `api` for pure pay-as-you-go with no subscription. One of: `free`, `plus`, `pro`, `enterprise`, `api`.
- `window` (string): The current allowance period, `start -> end`. Weekly, no rollover.
- `resets_in` (string): Time until the weekly reset, for example `3d` or `4h`.
- `days` (integer): Days in the window.
- `used_pct` (number): Percent of the period’s allowance drawn, in fresh-cell equivalents. Your allowance is set by your plan.
- `total_cells` (integer): Absolute fresh-cell equivalents drawn this period.
- `by_surface` (object): Draw per surface (`api`, `ui`), in fresh-cell equivalents.
- `by_op` (object): Draw per operation (`run`, `cached`, `create`, `refresh`, `serve`, `batch`, `generate`), in fresh-cell equivalents.
- `by_op_multiplier` (object): The ratio each operation draws at, relative to the fresh rate, following the published rate card. See Usage and billing.
- `by_op_raw` (object): Cells per operation as counted, before the rate ratio is applied.
- `top_endpoints` (array of objects): Endpoints by draw: `endpoint`, `id`, `cells`.
- `add_usage` (object): `enabled`, `spend_cap_set`, `spend_cap_usd`, `spend_cap_managed_in` (the spend cap is set on the platform under Billing).
- `events` (array of objects): Per-request usage events: `day`, `op`, `cells`, `tables`, `model`, `key`, `endpoint_id`, `requests`, `surface`.
- `lifetime` (boolean): `true` on Free, where the allotment is lifetime and does not reset.

**Example request (cURL)**

```bash
curl 'https://api.schemalabs.ai/v2/usage' \
  -H "Authorization: Bearer $SCHEMA_API_KEY"
```

**Example response (200)**

```json
{
  "org": "org_4f2a9c",
  "plan": "pro",
  "window": "2026-08-12 -> 2026-08-19",
  "resets_in": "3d",
  "days": 7,
  "used_pct": 39,
  "total_cells": 54400000,
  "by_surface": {
    "api": 49400000,
    "ui": 5000000
  },
  "by_op": {
    "run": 21200000,
    "cached": 13200000,
    "create": 15000000,
    "generate": 5000000
  },
  "by_op_multiplier": {
    "run": 1,
    "cached": 0.1,
    "create": 1,
    "generate": 0.5
  },
  "by_op_raw": {
    "run": 21200000,
    "cached": 132000000,
    "create": 15000000,
    "generate": 10000000
  },
  "top_endpoints": [
    {
      "endpoint": "churn",
      "id": "{endpoint_id}",
      "cells": 16400000
    }
  ],
  "add_usage": {
    "enabled": true,
    "spend_cap_set": false,
    "spend_cap_usd": 0
  },
  "events": [
    {
      "day": "2026-08-15",
      "op": "run",
      "cells": 45000,
      "tables": 2,
      "model": "schema-2",
      "key": "key_77ab",
      "endpoint_id": "",
      "requests": 1,
      "surface": "api"
    }
  ],
  "lifetime": false
}
```