API reference · Usage

Usage

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).

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.

Routes

GET/v2/usage

Retrieve usage

GET/v2/usage

scope read

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

GET/v2/usage

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

import os
import requests

SCHEMA_API_KEY = os.environ["SCHEMA_API_KEY"]

r = requests.get(
    "https://api.schemalabs.ai/v2/usage",
    headers={"Authorization": f"Bearer {SCHEMA_API_KEY}"},
)
r.raise_for_status()
result = r.json()

const res = await fetch('https://api.schemalabs.ai/v2/usage', {
  headers: {
    Authorization: `Bearer ${process.env.SCHEMA_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Schema API error ${res.status}`);
const result = await res.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
}

Returns

The usage object.

Response fields 15

orgstring
Organization name.
planstring
Current plan; api for pure pay-as-you-go with no subscription.
freeplusproenterpriseapi
windowstring
The current allowance period, start -> end. Weekly, no rollover.
resets_instring
Time until the weekly reset, for example 3d or 4h.
daysinteger
Days in the window.
used_pctnumber
Percent of the period’s allowance drawn, in fresh-cell equivalents. Your allowance is set by your plan.
total_cellsinteger
Absolute fresh-cell equivalents drawn this period.
by_surfaceobject
Draw per surface (api, ui), in fresh-cell equivalents.
by_opobject
Draw per operation (run, cached, create, refresh, serve, batch, generate), in fresh-cell equivalents.
by_op_multiplierobject
The ratio each operation draws at, relative to the fresh rate, following the published rate card. See Usage and billing.
by_op_rawobject
Cells per operation as counted, before the rate ratio is applied.
top_endpointsarray of objects
Endpoints by draw: endpoint, id, cells.
add_usageobject
enabled, spend_cap_set, spend_cap_usd, spend_cap_managed_in (the spend cap is set on the platform under Billing).
eventsarray of objects
Per-request usage events: day, op, cells, tables, model, key, endpoint_id, requests, surface.
lifetimeboolean
true on Free, where the allotment is lifetime and does not reset.