Usage & Billing

Usage & Billing

The Usage API provides access to your tenant's resource consumption. Usage is tracked as a stream of events, each tagged with a free-form event_type (for example voice_minutes, api_calls, llm_tokens, storage) and a unit. The endpoints below return whatever event types your tenant has accumulated — there is no fixed set of categories. Use them to monitor usage and build internal dashboards.

The companion Billing API (/api/v1/billing) exposes your plan catalog, current subscription, and billing status.

Usage Summary

Get aggregated usage totals, grouped by event type:

curl "https://apps.aurionai.net/api/v1/usage/summary" \
  -H "X-API-Key: itsm_sk_live_xxxx"

import requests

response = requests.get(
    "https://apps.aurionai.net/api/v1/usage/summary",
    headers={"X-API-Key": "itsm_sk_live_xxxx"},
)
usage = response.json()

Query Parameters:

Response:

The response is a single summary object whose keys are the event types recorded for your tenant. Each value is a { "total", "unit" } pair. There is no fixed set of keys — the shape reflects whatever your tenant has used.

{
  "summary": {
    "voice_minutes": {
      "total": 320,
      "unit": "minutes"
    },
    "api_calls": {
      "total": 12450,
      "unit": "calls"
    }
  }
}

Detailed Usage

Get granular usage data with date-range filtering and optional grouping:

curl "https://apps.aurionai.net/api/v1/usage/details?start_date=2026-03-01&end_date=2026-03-08&group_by=day" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Query Parameters:

Response (grouped — when group_by is day or event_type):

Returns a groups array. Each row carries a bucket (the day timestamp, or the event-type name when grouping by event_type), the event_type, unit, and summed total.

{
  "groups": [
    {
      "bucket": "2026-03-01T00:00:00",
      "event_type": "voice_minutes",
      "unit": "minutes",
      "total": 45
    },
    {
      "bucket": "2026-03-02T00:00:00",
      "event_type": "voice_minutes",
      "unit": "minutes",
      "total": 38
    }
  ]
}

Response (ungrouped — when group_by is omitted):

Returns the raw events list with offset-based pagination metadata.

{
  "events": [
    {
      "id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "event_type": "voice_minutes",
      "quantity": 45,
      "unit": "minutes",
      "metadata": {},
      "occurred_at": "2026-03-01T14:22:00+00:00",
      "created_at": "2026-03-01T14:22:01+00:00"
    }
  ],
  "total": 128,
  "limit": 50,
  "offset": 0
}

Billing API

The Billing API exposes your plan catalog, current subscription, and billing status. These endpoints require the billing:read scope (distinct from the usage:read scope used by the Usage endpoints above).

List Plans

Return the plans available to your tenant, with per-plan transition metadata:

curl "https://apps.aurionai.net/api/v1/billing/plans" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

Returns a plans array. Plan limits come from your live catalog — do not hard-code them. Each plan object includes its pricing and included quotas, plus transition metadata describing how it relates to your current plan.

{
  "plans": [
    {
      "id": "f3a1...",
      "name": "voice_starter",
      "display_name": "Voice Starter",
      "product_line": "voice",
      "price_monthly_cents": 4900,
      "price_annual_cents": 49000,
      "included_minutes": 250,
      "included_seats": 3,
      "included_storage_gb": 1,
      "included_tickets": 0,
      "max_agent_pods": 1,
      "is_current": true,
      "transition_type": "current",
      "action_group": "current",
      "is_selectable": false,
      "requires_contact_sales": false,
      "requires_payment": false,
      "is_active": true,
      "note": null,
      "billing_cycle": "monthly"
    }
  ]
}

Current Subscription

Get the tenant's current subscription summary:

curl "https://apps.aurionai.net/api/v1/billing/subscription" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

Returns a subscription object describing the active subscription, including a nested plan summary. A pending_downgrade object is present only when a deferred downgrade is scheduled. (The Stripe customer ID is never exposed.)

{
  "subscription": {
    "status": "active",
    "billing_cycle": "monthly",
    "plan": {
      "id": "f3a1...",
      "name": "voice_starter",
      "display_name": "Voice Starter"
    }
  }
}

Billing Status

A lightweight status check (no Stripe calls), including any active alerts:

curl "https://apps.aurionai.net/api/v1/billing/status" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "subscription_status": "active",
  "is_suspended": false,
  "active_alerts": []
}

Tenant Tier

A lightweight tier lookup, used for feature gating:

curl "https://apps.aurionai.net/api/v1/billing/tier" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "tier": "starter",
  "plan_name": "voice_starter",
  "product_line": "voice",
  "integration_type": "freshservice"
}

Outstanding Charges

Check outstanding metered charges for the current billing cycle:

curl "https://apps.aurionai.net/api/v1/billing/outstanding-charges" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "has_charges": false,
  "total_cents": 0,
  "line_items": []
}

ℹ️ Alert management requires admin

GET /api/v1/billing/alerts and POST /api/v1/billing/alerts/{alert_id}/acknowledge require a tenant admin role and are not reachable with a billing:read API key. Use GET /api/v1/billing/status (above) to read active alerts programmatically.

Billing Alerts

The platform automatically generates alerts when usage approaches plan limits:

Configure alert thresholds and notification channels in the admin dashboard under Billing > Alerts.

Billing Status

Related Guides

• Analytics — Conversation and SLA analytics
• Environments — Rate limits per environment

Required Scopes

Read endpoints require the :read action; write operations would require :write. Alert management endpoints require a tenant admin role and are not reachable by an API key.