Meet the new Scripe, live on October 7.Register

OpenAPI reference · Workspace

Usage and limits

GET/usage

What the workspace has used of its limits, and whether the next AI job would be accepted.

Two 402s guard every AI verb — usage_limit_exceeded (the weekly AI budget, the primary limit) and spend_cap_exceeded (the daily API spend cap) — and this endpoint is the pre-flight for both. Read canGenerate first: false means the next post generation, image generation or knowledge ingest will be refused, and blockedBy names which limit. canGenerate is measured against the cost of a post generation, the most common AI job.

AI budgets are reported as a percentage of the allowance, never as money: the budget is denominated in provider cost, so the meaningful figure for a customer is how much of the allowance is gone. Storage is reported in bytes, and the daily API cap in cents — both are already public (the cap appears in the spend_cap_exceeded body).

With projectId the answer covers that project's weekly budget; without one it covers the workspace pool and ai.project is null. A company page has no budget of its own and spends from the pool, which ai.scope names.

Required scope: workspace:read.

Authorization

  • Authorizationstringrequired

    Bearer token in the Authorization header.

    Pass Authorization: Bearer scripe_sk_live_<...> (or scripe_sk_test_<...> for test keys) on every request. Keys are scoped to a single workspace and can be revoked from the Scripe dashboard.

    The same header also accepts an OAuth 2.1 access token (scripe_oat_*); both credentials share one scope vocabulary and every operation below documents the scope it requires. An API key can hold every scope named on this surface except webhooks:manage, which is grantable to OAuth tokens only today — the webhook-endpoint operations answer 403 scope_missing to every API key. Operations that name no scope accept any valid token of the workspace.

Query parameters

  • projectIdstring

    Report the weekly AI budget of this project. Omit for the workspace pool alone.

Header parameters

  • Scripe-Api-Versionstring

    Pin the API version. Format YYYY-MM-DD. Omit to receive the currently rolling default. Unknown versions return 400 version_unsupported.

Responses

  • 200

    Current usage and limits.

  • 401

    Missing, malformed, expired, or revoked API key.

  • 403

    Plan not eligible, scope missing, or workspace mismatch.

  • 404

    Resource not found in this workspace.

  • 429

    Sliding-window rate limit exceeded.

Example request

bash
curl --request GET \
  --url 'https://api.scripe.io/v1/usage' \
  --header 'Authorization: Bearer <token>'

Example response (200)

json
{
  "data": {
    "plan": "BUSINESS",
    "canGenerate": true,
    "blockedBy": "weekly_ai_budget",
    "ai": {
      "scope": "ai_project",
      "percentUsed": 0,
      "unlimited": true,
      "enforcement": "off",
      "weekStart": "2026-08-10",
      "resetsAt": "2026-08-10T09:00:00Z",
      "project": {
        "id": "string",
        "name": "string",
        "percentUsed": 0,
        "unlimited": true
      },
      "workspacePool": {
        "percentUsed": 0,
        "unlimited": true
      }
    },
    "storage": {
      "usedBytes": 0,
      "limitBytes": 0,
      "percentUsed": 0,
      "usedAssets": 0,
      "assetLimit": 0
    },
    "apiSpend": {
      "bucketDate": "2026-08-14",
      "capCents": 0,
      "spentCents": 0,
      "remainingCents": 0
    }
  }
}