Admin

Read a user's usage this billing cycle

The same answer GET /v1/users/me/usage gives the account itself: runs, indexed storage and the plan-capped counts, per project and against the rung. Needs the admin role.

get/v1/admin/users/{user_id}/usage

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/admin/users/{user_id}/usage
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

user_idstring required

Response

The account's usage for the cycle.

cycle_fromstring date-time required

Start of the billing cycle the runs were counted over — the first instant of the current UTC calendar month.

pending_spend_usdnumber nullable required

Model and embedding spend metered since the balance was last reconciled, across every project the account pays for. null when at least one project's meter could not be read.

spendable_balance_usdnumber nullable required

The credit balance less pending_spend_usd. A managed generation can be refused with 402 insufficient_credit while the credit balance still reads positive; while this is zero or above, none is. Check it before starting work that runs several generations. null when pending_spend_usd is.

Example response

{
  "cycle_from": "2026-07-01T00:00:00.000Z",
  "pending_spend_usd": 1.43,
  "spendable_balance_usd": 23.35,
  "projects": [
    {
      "project_id": "proj_V1StGXR8Z5jdHi6B",
      "name": "Support",
      "status": "active",
      "runs": 1284,
      "triggers": 2,
      "channels": 1,
      "storage": {
        "used": 0.42,
        "sampled_at": "2026-07-14T12:00:00.000Z"
      },
      "pending_spend_usd": 1.43
    }
  ],
  "limits": {
    "projects": {
      "used": 2,
      "limit": 3
    },
    "channels": {
      "used": 2,
      "limit": 3
    },
    "triggers": {
      "used": 2,
      "limit": 3
    },
    "storage": {
      "used": 2,
      "limit": 3
    },
    "runs": {
      "used": 2,
      "limit": 3
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.