Usage

Returns credit balance, recent usage events, and billing state for the authenticated account.

Use this endpoint to show account balance, recent credit events, and billing state in external dashboards.

Endpoint

GET /v1/usage

Authentication

Header	Required	Value
`Authorization`	Yes	`Bearer sw_api_live_...`

Required scope:

runs:read

Query Parameters

Parameter	Type	Required	Description
`recent_limit`	integer	No	Number of recent ledger/usage rows to return. Clamped between 1 and 100. Defaults to 20.

Example Request

curl -s "https://api.sleepwalker.ai/v1/usage?recent_limit=20" \
  -H "Authorization: Bearer sw_api_live_..."

The same request in Python and JavaScript:

import requests

resp = requests.get(
    "https://api.sleepwalker.ai/v1/usage",
    headers={"Authorization": "Bearer sw_api_live_..."},
    params={"recent_limit": 20},
)
resp.raise_for_status()
print(resp.json())

const resp = await fetch("https://api.sleepwalker.ai/v1/usage?recent_limit=20", {
  headers: { Authorization: "Bearer sw_api_live_..." },
});
const data = await resp.json();
console.log(data);

Response

{
  "profile": {
    "user_id": "af408459-...",
    "plan": "starter",
    "subscription_status": "active",
    "trial_ends_at": null,
    "current_period_start": "2026-06-01T00:00:00Z",
    "current_period_end": "2026-07-01T00:00:00Z",
    "cancel_at_period_end": false,
    "cancel_at": null
  },
  "legacy_usage": {
    "plan": "starter",
    "limit": 100,
    "run_count": 7,
    "month": "2026-06-01",
    "remaining_runs": 93,
    "basis": "stripe_period"
  },
  "credits": {
    "available_credit_units": "1240.00",
    "used_credit_units": "83.00",
    "active_grant_count": 1,
    "active_grants": [
      {
        "id": "grant_...",
        "source": "stripe_topup",
        "credit_units": "250.00",
        "remaining_credit_units": "167.00",
        "expires_at": null,
        "created_at": "2026-06-10T12:00:00Z"
      }
    ]
  },
  "recent_credit_ledger": [
    {
      "id": "ledger_...",
      "status": "settled",
      "entry_type": "grant",
      "credit_units": "250.00",
      "action_name": "billing.credits.topup",
      "created_at": "2026-06-10T12:00:00Z"
    }
  ],
  "recent_usage_events": [
    {
      "id": "usage_...",
      "created_at": "2026-06-10T12:30:00Z",
      "source": "api",
      "actor_type": "api_key",
      "action_name": "visibility.runs.create",
      "resource_type": "visibility_run",
      "resource_id": "6a75b22b-...",
      "event_type": "reservation",
      "raw_units": 1,
      "status": "settled",
      "credit_units": "1.00",
      "provider": "perplexity",
      "platform": "perplexity",
      "model": "sonar",
      "prompt_count": 1,
      "probe_count": 1
    }
  ],
  "billing_state": {
    "credit_metering": "partial_beta",
    "read_endpoint_metered": false,
    "notes": [
      "Legacy run limits and credit ledger telemetry are exposed together during the billing migration.",
      "Read-only usage calls are not charged."
    ]
  }
}

Response Sections

Section	Description
`profile`	Plan and subscription-period summary. It does not expose the account email.
`legacy_usage`	Legacy plan run count and remaining run allowance during the billing migration.
`credits`	Current credit balance, settled usage total, and active credit grants.
`recent_credit_ledger`	Recent credit balance changes.
`recent_usage_events`	Recent API/MCP/Console metering events, including reserved, settled, released, and estimated work.
`billing_state`	Metering migration state and read-endpoint notes. Pricing is documented separately and is not returned here.

Billing Notes

Read endpoints do not consume credits.
Top-ups add credits after payment is processed.
Usage events may be estimated, reserved, settled, released, or failed.

See Credit Lifecycle for definitions.

Errors

Status	Meaning
`401`	Missing or invalid API key.
`403`	API key is missing `runs:read`.
`422`	`recent_limit` has the wrong type.
`503`	Usage or credit storage is temporarily unavailable.

API-key rate limits are documented in Errors.