MyUstadia API

GET /api/v1/billing

Returns a monthly usage summary for your account. Use this to track consumption, build invoices, and monitor quota.

curl "https://api.myustadia.com/api/v1/billing?month=2026-06" \
  -H "Authorization: Bearer sk_live_..."

The month query parameter is optional. It defaults to the current calendar month. Format: YYYY-MM.

# Current month (default)
GET /api/v1/billing

# Specific month
GET /api/v1/billing?month=2026-04

Response shape

{
  "month": "2026-06",
  "client_id": "acme_corp",
  "summary": {
    "courses_total": 12,
    "courses_ready": 11,
    "courses_partial": 0,
    "courses_error": 1,
    "distinct_external_refs": 5,
    "total_modules": 48
  },
  "quota_seconds": {
    "quota_seconds": 7200,
    "consumed_seconds": 3428,
    "remaining_seconds": 3772,
    "percent_consumed": 48,
    "over_quota": false
  },
  "breakdown_by_ref": [
    {
      "external_ref": "acme-emea",
      "courses": 3,
      "courses_ready": 3,
      "modules": 12
    }
  ],
  "note": "distinct_external_refs = number of unique external_ref values used this month. Use this to count billable units (e.g. companies served by ARESS). quota_seconds.percent_consumed is the authoritative usage figure."
}

Fields

Top level

Field	Type	Description
`month`	string	The billing month returned, in `YYYY-MM` format
`client_id`	string	Your account identifier
`summary`	object	Aggregate course counts for the month
`quota_seconds`	object	Authoritative seconds-bucket usage view
`breakdown_by_ref`	array	Per-`external_ref` course and module counts
`note`	string	Human-readable annotation; subject to change

summary

Field	Description
`courses_total`	All courses created this month (excludes sandbox)
`courses_ready`	Courses that reached `ready` status
`courses_partial`	Courses stopped mid-generation due to quota exhaustion (`partial_quota_exceeded`)
`courses_error`	Courses that ended in `error`
`distinct_external_refs`	Count of unique `external_ref` values used this month. Use this to count billable clients or projects.
`total_modules`	Sum of `module_count` across all courses this month

quota_seconds

This is the authoritative usage view. Show percent_consumed to clients as their usage gauge.

Field	Type	Description
`quota_seconds`	integer	Total seconds allocated to your account this billing period
`consumed_seconds`	integer	Seconds used so far this month
`remaining_seconds`	integer	`quota_seconds - consumed_seconds`, floored at 0
`percent_consumed`	integer	Usage as a percentage (0-100). This is the figure to surface to clients.
`over_quota`	boolean	`true` when your remaining seconds are at or below the start floor. While `true`, new course launches and preset creation are rejected with `429 quota_exceeded`.

There is no free tier and no unlimited plan: every account is metered, and generation always consumes from the seconds bucket. When the bucket is exhausted (over_quota: true), new launches and preset creation are rejected with 429 quota_exceeded until your quota is raised.

breakdown_by_ref

One entry per distinct external_ref value used this month. Useful for building per-client or per-project usage summaries.

Field	Description
`external_ref`	The caller-supplied reference string
`courses`	Total courses created under this ref this month
`courses_ready`	Courses that reached `ready`
`modules`	Total modules across all courses under this ref

Usage monitoring pattern

Poll /billing on a schedule to track quota burn and alert before exhaustion:

import httpx

resp = httpx.get(
    "https://api.myustadia.com/api/v1/billing",
    headers={"Authorization": "Bearer sk_live_..."},
)
data = resp.json()
pct = data["quota_seconds"]["percent_consumed"]

if pct >= 90:
    alert("Quota at {}% -- approaching limit".format(pct))

percent_consumed is clamped at 100 even if consumed_seconds slightly exceeds quota_seconds due to in-flight jobs completing after the soft cap.

Get Started

Concepts

API Reference

Endpoints

Billing

GET /api/v1/billing

Response shape

Fields

Top level

summary

quota_seconds

breakdown_by_ref

Usage monitoring pattern

​GET /api/v1/billing

​Response shape

​Fields

​Top level

​summary

​quota_seconds

​breakdown_by_ref

​Usage monitoring pattern

GET /api/v1/billing

Response shape

Fields

Top level

summary

quota_seconds

breakdown_by_ref

Usage monitoring pattern