Usage API

GET /v1/usage returns where an Aevral organization stands: PR review plan, usage and cap, scan status, and, for PR review, a link an owner or admin opens to subscribe or upgrade. Read-only. An agent cannot buy or change a plan.

Read-only. The response can carry a billing link, but only an owner or admin of the organization can act on it, in the console. An aevr_ key cannot subscribe, upgrade, change a plan, or raise a spend cap.

Request

GET https://aevral-worker-prod.fly.dev/v1/usage
Authorization: Bearer aevr_...

The organization comes from the key alone. Query, body and header org values are ignored for keys. A key never reads another organization.
Use a key that is already in your environment. Coding agents must never ask the human to paste a key into chat, and never put a key in a URL.
Responses carry Cache-Control: private, max-age=30. Reads are limited to about 60 a minute per organization and never count against scan quota.

Response

{
  "org_id": "<org uuid>",
  "pr": {
    "state": "free",
    "plan": null,
    "used": 25,
    "limit": 25,
    "at_cap": true,
    "resets_at": "2026-10-01T00:00:00.000Z",
    "trial_ends_at": null,
    "action": {
      "kind": "subscribe",
      "human_action_required": true,
      "who": "an owner or admin of this organization",
      "url": "https://app.aevral.com/billing?org=<org uuid>&plan=starter&ref=agent#plans",
      "suggested_plan": "starter",
      "plans_url": "https://aevral-worker-prod.fly.dev/v1/pr/billing/plans",
      "message": "Private pull requests get a neutral Check and no review until 2026-10-01. An owner or admin can upgrade at the link."
    }
  },
  "scans": {
    "state": "trial",
    "plan": null,
    "used": 1,
    "limit": 2,
    "at_cap": false,
    "resets_at": null,
    "action": null
  }
}

`pr` (PR security review)

Field	Type	Meaning
`state`	`trial` \| `trial_used_up` \| `free` \| `paid` \| `attention`	`attention` means the subscription is past due or unpaid.
`plan`	`starter` \| `pro` \| `business` \| null	Set only when `state` is `paid`.
`used`	integer \| null	Private reviews counted against `limit` this period (trial: reviews counted toward the trial). Null when there is no meter.
`limit`	integer \| null	The allowance for this period: the trial ceiling, the free monthly allowance, or the plan's included reviews.
`at_cap`	boolean	True when `used` has reached a non-zero `limit`. On a private pull request past the cap, the GitHub Check is neutral and no review runs. A neutral Check can also mean payment attention, paused paid extras, or an hourly or daily cap: read its title.
`resets_at`	ISO timestamp \| null	Free: the first day of next month (UTC). Paid: the end of the current billing period. Trial: null.
`trial_ends_at`	ISO timestamp \| null	Set only when `state` is `trial`.
`action`	object \| null	What a human can do next. See below.

`pr.action`

Field	Type	Meaning
`kind`	`subscribe` \| `upgrade`	`subscribe` for an organization with no paid plan; `upgrade` for a paid plan at its cap with a higher plan available.
`human_action_required`	`true`	Always true. Nothing is bought until a human confirms in the console.
`who`	string	Who must open the link: `an owner or admin of this organization`.
`url`	string	Console Billing page for this organization, with the suggested plan when there is one. The console rechecks live state on arrival and says so if the link no longer applies.
`suggested_plan`	`starter` \| `pro` \| `business` \| null	The lowest available plan whose included reviews cover twice the current usage, or the highest available plan when none does. Null when no plan is suggested.
`plans_url`	string	`GET /v1/pr/billing/plans`: the live PR plan ladder.
`message`	string	One sentence you can show the human.

action is null when plans are not on sale, the subscription is past due or unpaid, a checkout is still pending, the paid plan is under its cap, cancelling, already upgrading, or on the highest plan.

`scans` (whole-repo scans)

Status only: state, plan, used, limit, at_cap, resets_at, and action, which is always null. Scan plan changes happen in the console Billing page.

`state`	Meaning
`paid`	A scan plan is active. `plan` is `team`, `business` or `scale`; `resets_at` is the end of the billing period.
`attention`	The scan subscription is past due or unpaid. `plan`, `used`, `limit` and `resets_at` are null.
`included`	An included monthly allowance with no scan plan. `resets_at` is the first day of next month (UTC).
`trial`	The 14-day private trial: `limit` is 2, `resets_at` is null.
`free`	No plan and no trial left: one public-repository scan a month.

Prices

Quote numbers only from the public plans endpoints, never from memory:

PR review, USD: GET https://aevral-worker-prod.fly.dev/v1/pr/billing/plans
Whole-repo scans, EUR: GET https://aevral-worker-prod.fly.dev/v1/billing/plans

Both return {"plans":[{"id","included","monthly_cents","overage_cents"}]} and need no key. Amounts are in cents, excluding VAT. The human-readable ladders are on Pricing and plans.

Scan refusals point here

When POST /v1/scans is refused with 402 (quota_exhausted, overage_confirmation_required or spend_cap_reached), the body adds usage_url pointing to GET /v1/usage. A spend-cap refusal is not a plan problem: an owner may need to raise the cap in the console.

Errors

Status	Body	Meaning
401	`{"error": ...}`	Missing, malformed or invalid key.
404	`{"error":"unknown_org"}`	The key's organization no longer exists.
405	`{"error":"method_not_allowed"}`	Only GET.
429	`{"error":"rate_limited","retry_after":N}`	Too many reads. Wait `retry_after` seconds (also in the `Retry-After` header).
502	`{"error":"usage_unavailable"}`	Usage could not be read. Retry later.
503	`{"error":"usage_unconfigured"}`	The endpoint is not available on this host.

For coding agents

Call this endpoint only with an aevr_ key already in the environment. Never ask the human to paste one into chat.
Show the human pr.action.url and say who must open it: an owner or admin of the organization.
Never say you upgraded or subscribed. Never open the link in an automated browser.
Quote prices only from plans_url.

See also Console and API keys and For AI agents.

Usage API

On this page