Usage & Limits

Plans and metering

API calls run in the context of your API key user's organization. Creating interviews, running sessions, and AI-backed features all consume the same limits as the web app. When a limit is hit, the API returns 403 with code PLAN_LIMIT_EXCEEDED and extra fields describing the cap.

What counts against your plan

• Interview templates — Each new interview template counts toward your template quota. When exceeded, POST /api/v1/interviews responds with PLAN_LIMIT_EXCEEDED and limit: "templates".
• Session hours — Monthly session time is aggregated for the organization. Adding candidates or running long interviews can hit this ceiling; related endpoints return limit: "session_hours" with used/max hours.
• AI tokens — AI features draw from your organization's AI token pool. Heavy use of summaries, analysis, or generation reduces the remaining balance shown in usage.

GET /api/v1/usage

Successful response shape:

{
  "data": {
    "plan": "…",
    "templates": { "used": 0, "limit": null },
    "session_hours": { "used": 0.0, "limit": 0 },
    "ai_tokens": { "used": 0, "limit": 0 },
    "seats": { "used": 0, "limit": 0 }
  }
}

limit may be null where a metric is unlimited on your plan. session_hours.used is derived from monthly session seconds.

Handling PLAN_LIMIT_EXCEEDED

Example error body:

{
  "error": {
    "code": "PLAN_LIMIT_EXCEEDED",
    "message": "Template limit reached.",
    "limit": "templates",
    "current": 10,
    "max": 10,
    "upgrade_url": "https://aural-ai.com/billing"
  }
}

• Read error.limit to branch in your integration (templates, session_hours, etc.).
• Point operators to upgrade_url or your billing page to upgrade or top up.
• Back off or queue work when limits are near thresholds; poll GET /usage before bulk operations.