> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get usage handlers

> Returns the tenant's current usage metrics from the tenancy system. **Required scope:** read

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

**Required scope:** `read`

### Response

`UsageResponse`

<ResponseField name="account" type="UsageAccount" required>
  <Expandable title="UsageAccount">
    <ResponseField name="can_produce_outcome" type="boolean" required>
      Whether the tenant can currently produce another billable outcome.
    </ResponseField>

    <ResponseField name="included_outcomes_remaining" type="integer (int64)" required>
      Included outcomes remaining before billable overage starts.
    </ResponseField>

    <ResponseField name="prepaid_credits_remaining_cents" type="integer (int64)">
      Prepaid (purchased) credits remaining in cents. Never expire.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Tenant status from the tenancy system.
    </ResponseField>

    <ResponseField name="trial_credits_remaining_cents" type="integer (int64)" required>
      Trial credits remaining in cents.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="api_requests_month" type="integer (int64)" required />

<ResponseField name="entities" type="integer" required />

<ResponseField name="inference_requests_month" type="integer (int64)" required />

<ResponseField name="limits" type="UsageLimits" required>
  <Expandable title="UsageLimits">
    <ResponseField name="max_entities" type="integer" required />

    <ResponseField name="max_requests_per_minute" type="integer (int32)" required />

    <ResponseField name="max_rules" type="integer" required />

    <ResponseField name="max_triples" type="integer" required />
  </Expandable>
</ResponseField>

<ResponseField name="outcomes" type="OutcomeUsage" required>
  <Expandable title="OutcomeUsage">
    <ResponseField name="base_fee" type="number (double)" required>
      Base platform fee in dollars.
    </ResponseField>

    <ResponseField name="estimated_total" type="number (double)" required>
      Total estimated bill (base + outcome charges).
    </ResponseField>

    <ResponseField name="outcome_charges" type="number (double)" required>
      Total outcome charges this month in dollars.
    </ResponseField>

    <ResponseField name="outcomes_billable" type="integer (int64)" required>
      Billable outcomes (beyond included quota).
    </ResponseField>

    <ResponseField name="outcomes_included" type="integer (int64)" required>
      Outcomes included in the tier (no extra charge).
    </ResponseField>

    <ResponseField name="outcomes_month" type="integer (int64)" required>
      Total resolved outcomes this month.
    </ResponseField>

    <ResponseField name="price_per_outcome" type="number (double)" required>
      Price per billable outcome in dollars.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="recursive" type="RecursiveUsage" required>
  <Expandable title="RecursiveUsage">
    <ResponseField name="grounded_outcome_rate" type="number (double)" required>
      Grounded outcome rate across recursive requests.
    </ResponseField>

    <ResponseField name="ready_action_responses_month" type="integer (int64)" required>
      Number of recursive responses that returned one or more ready actions.
    </ResponseField>

    <ResponseField name="requests_month" type="integer (int64)" required>
      Number of recursive chat requests this month.
    </ResponseField>

    <ResponseField name="review_required_rate" type="number (double)" required>
      Review-required rate across recursive requests.
    </ResponseField>

    <ResponseField name="review_required_responses_month" type="integer (int64)" required>
      Number of recursive responses that required human review.
    </ResponseField>

    <ResponseField name="tool_call_responses_month" type="integer (int64)" required>
      Number of recursive responses that returned one or more tool calls.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rules" type="integer" required />

<ResponseField name="storage_bytes" type="integer (int64)" required />

<ResponseField name="tier" type="string" required />

<ResponseField name="triples" type="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 |

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.nsr.stateset.com/api/v1/billing/usage' \
    --header 'X-API-Key: YOUR_API_KEY'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "account": {
      "can_produce_outcome": true,
      "included_outcomes_remaining": 1,
      "prepaid_credits_remaining_cents": 1,
      "status": "string",
      "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": 1,
      "estimated_total": 1,
      "outcome_charges": 1,
      "outcomes_billable": 1,
      "outcomes_included": 1,
      "outcomes_month": 1,
      "price_per_outcome": 1
    },
    "recursive": {
      "grounded_outcome_rate": 1,
      "ready_action_responses_month": 1,
      "requests_month": 1,
      "review_required_rate": 1,
      "review_required_responses_month": 1,
      "tool_call_responses_month": 1
    },
    "rules": 1,
    "storage_bytes": 1,
    "tier": "string",
    "triples": 1
  }
  ```
</ResponseExample>