Get usage handlers

Returns the tenant’s current usage metrics from the tenancy system. Required scope: read

GET /api/v1/billing/usage

cURL

curl --request GET \
  --url 'https://api.nsr.stateset.com/api/v1/billing/usage' \
  --header "X-API-Key: $STATESET_NSR_API_KEY"

200

{
  "account": {
    "can_produce_outcome": true,
    "included_outcomes_remaining": 1,
    "prepaid_credits_remaining_cents": 1,
    "status": "pending",
    "trial_credits_remaining_cents": 1
  },
  "api_requests_month": 1,
  "entities": 1,
  "inference_requests_month": 1,
  "limits": {
    "max_entities": 1,
    "max_requests_per_minute": 1,
    "max_rules": 1,
    "max_triples": 1
  },
  "outcomes": {
    "base_fee": 49,
    "estimated_total": 49,
    "outcome_charges": 1.5,
    "outcomes_billable": 1,
    "outcomes_included": 1,
    "outcomes_month": 1,
    "price_per_outcome": 1.5
  },
  "recursive": {
    "grounded_outcome_rate": 7.5,
    "ready_action_responses_month": 1,
    "requests_month": 1,
    "review_required_rate": 7.5,
    "review_required_responses_month": 1,
    "tool_call_responses_month": 1
  },
  "rules": 1,
  "storage_bytes": 1,
  "tier": "string",
  "triples": 1
}

Returns the tenant’s current usage metrics from the tenancy system.

Required scope: read

Response

UsageResponse

account · UsageAccount · required

Show UsageAccount

can_produce_outcome · boolean · required

Whether the tenant can currently produce another billable outcome.

included_outcomes_remaining · integer (int64) · required

Included outcomes remaining before billable overage starts.

prepaid_credits_remaining_cents · integer (int64)

Prepaid (purchased) credits remaining in cents. Never expire.

status · string · required

Tenant status from the tenancy system.

trial_credits_remaining_cents · integer (int64) · required

Trial credits remaining in cents.

api_requests_month · integer (int64) · required

entities · integer · required

inference_requests_month · integer (int64) · required

limits · UsageLimits · required

Show UsageLimits

max_entities · integer · required

max_requests_per_minute · integer (int32) · required

max_rules · integer · required

max_triples · integer · required

outcomes · OutcomeUsage · required

Show OutcomeUsage

base_fee · number (double) · required

Base platform fee in dollars.

estimated_total · number (double) · required

Total estimated bill (base + outcome charges).

outcome_charges · number (double) · required

Total outcome charges this month in dollars.

outcomes_billable · integer (int64) · required

Billable outcomes (beyond included quota).

outcomes_included · integer (int64) · required

Outcomes included in the tier (no extra charge).

outcomes_month · integer (int64) · required

Total resolved outcomes this month.

price_per_outcome · number (double) · required

Price per billable outcome in dollars.

recursive · RecursiveUsage · required

Show RecursiveUsage

grounded_outcome_rate · number (double) · required

Grounded outcome rate across recursive requests.

ready_action_responses_month · integer (int64) · required

Number of recursive responses that returned one or more ready actions.

requests_month · integer (int64) · required

Number of recursive chat requests this month.

review_required_rate · number (double) · required

Review-required rate across recursive requests.

review_required_responses_month · integer (int64) · required

Number of recursive responses that required human review.

tool_call_responses_month · integer (int64) · required

Number of recursive responses that returned one or more tool calls.

rules · integer · required

storage_bytes · integer (int64) · required

tier · string · required

triples · integer · required

Status codes

Code	Meaning
200	Usage metrics
401	Unauthorized — missing or invalid credentials
403	Forbidden — the key/token lacks the required scope
429	Rate limited — see Retry-After / X-RateLimit-Reset

cURL

curl --request GET \
  --url 'https://api.nsr.stateset.com/api/v1/billing/usage' \
  --header "X-API-Key: $STATESET_NSR_API_KEY"

200

{
  "account": {
    "can_produce_outcome": true,
    "included_outcomes_remaining": 1,
    "prepaid_credits_remaining_cents": 1,
    "status": "pending",
    "trial_credits_remaining_cents": 1
  },
  "api_requests_month": 1,
  "entities": 1,
  "inference_requests_month": 1,
  "limits": {
    "max_entities": 1,
    "max_requests_per_minute": 1,
    "max_rules": 1,
    "max_triples": 1
  },
  "outcomes": {
    "base_fee": 49,
    "estimated_total": 49,
    "outcome_charges": 1.5,
    "outcomes_billable": 1,
    "outcomes_included": 1,
    "outcomes_month": 1,
    "price_per_outcome": 1.5
  },
  "recursive": {
    "grounded_outcome_rate": 7.5,
    "ready_action_responses_month": 1,
    "requests_month": 1,
    "review_required_rate": 7.5,
    "review_required_responses_month": 1,
    "tool_call_responses_month": 1
  },
  "rules": 1,
  "storage_bytes": 1,
  "tier": "string",
  "triples": 1
}