space.ai.usage()

Reads the project’s AI units, requests, and tokens over a time range, next to the same length of time before it, and split by model and by caller.

function usage(
  options?: CallOptions & { range?: "24h" | "7d" | "30d" }
): Promise<UsageReport>

Parameters

options.rangestring

24h, by hour; or 7d or 30d, by day. 24h when you leave it out.

options.signalAbortSignal

Cancels the call.

options.timeoutMsnumber

How long the call may take, in milliseconds. The timeoutMs set in createSpace when you leave it out, 30,000 by default.

Returns

A promise of a usage report:

{
  "range": "7d",
  "step": "day",
  "current": {
    "since": "2026-09-23T00:00:00Z",
    "until": "2026-09-30T00:00:00Z",
    "totals": { "units": 4200, "requests": 70, "inputTokens": 91000, "outputTokens": 30000 },
    "points": [
      { "start": "2026-09-23T00:00:00Z", "units": 600, "requests": 10, "inputTokens": 13000, "outputTokens": 4300 }
    ]
  },
  "previous": {
    "since": "2026-09-16T00:00:00Z",
    "until": "2026-09-23T00:00:00Z",
    "totals": { "units": 3100, "requests": 52, "inputTokens": 70000, "outputTokens": 21000 },
    "points": []
  },
  "models": [{ "name": "openai/gpt-oss-120b", "units": 4200, "requests": 70 }],
  "callers": [{ "name": "apiKey:01m3c081d2wj4g63qcr53pa1yh", "units": 4200, "requests": 70 }]
}

rangestring

The range asked for: 24h, 7d, or 30d.

stepstring

hour or day: how long each point is. Hours and days are in UTC.

currentobject

The range asked for, up to the end of this hour or today: since and until, as ISO 8601 strings; totals; and points, one for each step in order, with zeros where nothing ran.

previousobject

The same length of time before it, in the same shape, to compare with.

current.totals.unitsnumber

The AI units calls used. See AI units.

current.totals.requestsnumber

Calls that used AI units.

current.totals.inputTokensnumber

Tokens sent to models.

current.totals.outputTokensnumber

Tokens models wrote.

modelsobject[]

The range’s units and requests by model name, most first, up to 20.

callersobject[]

The same by who called: apiKey: and the key’s ID, or user: and the person’s ID for calls from the console. Up to 20.

A call counts in the hour it started.

Errors

Every call can also fail with the codes shared by all of space, such as missing_project or network_error. See SpaceError.

Example

import { space } from "digitospace"

const report = await space.ai.usage({ range: "7d" })

const now = report.current.totals.units
const before = report.previous.totals.units
console.log(`${now} AI units this week, against ${before} the week before`)

for (const model of report.models) {
  console.log(model.name, model.units)
}