# Limits, budgets, and usage

> Distinguish request rate, monthly quota, hard budget, credits, and Usage API counters.

Canonical guide: <https://engine.neraperla.com/docs/usage-quotas>

Raw Markdown: <https://engine.neraperla.com/docs/raw/usage-quotas.md>

OpenAPI: <https://engine.neraperla.com/v1/openapi.json>

Six controls can affect whether work starts. They are checked in the order below, and the first that refuses is the error you get:

| Control | Purpose | Failure and recovery |
|---|---|---|
| Request rate | Limits request pace per API key. A company-level key has one budget for every project it serves. | `rate_limit_exceeded`; retry after `Retry-After`. |
| Usage quota | Limits accepted job requests, or the amount charged, at organization, project, API-key, and optional capability scope for a UTC calendar month. | `quota_exceeded`; use `error.details.resets_at`, wait for reset, or ask an administrator to change the quota. |
| Project allowance | Stops new work in one project once its allowance, a never-resetting spending limit you top up, can't cover a run or its minimum to start. Other projects keep running. | `budget_exceeded` with `error.details.kind` of `allowance` or `min_to_start`; top up the project's allowance. See [Managing your clients with projects](https://engine.neraperla.com/docs/projects). |
| Hard budget | Stops new capability work once the charges for runs in an organization or project scope, optionally for one capability, reach a daily or monthly ceiling. The daily and monthly limits you set for a project or for the whole company with the projects and limits API are hard budgets. | `budget_exceeded`; use `error.details`, wait for reset, or ask an owner, administrator or billing member to change the budget. |
| Usage-tier spend cap | Stops new capability work once the organization's charges this month reach its tier-based monthly spend ceiling. The cap rises with the tier ladder (earned by credit purchases and account age) and never sits below the organization's total granted promotional credit. On a capped tier, the organization runs one job at a time: a job in progress holds the rest of the month's cap until it finishes. | `budget_exceeded` with `error.details.scope: usage_tier`. When `error.details.reserved_usd` is above zero and `spend_usd` is below `limit_usd`, another job holds the cap: start this one when that job finishes. Otherwise wait for reset, purchase credits to advance the tier, or ask support for a tier change. See [Rate limits](https://engine.neraperla.com/docs/rate-limits#usage-tiers). |
| Prepaid credits | Requires a positive spendable balance when billing is enabled; no future job price is estimated or reserved. | `insufficient_credits`; add credits or let auto-recharge complete. |

Only the rate-limit case is a transient automatic retry. See [Errors](https://engine.neraperla.com/docs/errors).

Quota periods and monthly budgets begin at `00:00:00 UTC` on the first day of a calendar month and reset at the next month's boundary. Daily budgets begin at `00:00:00 UTC` and reset at the next UTC midnight. An error's structured `details` reports the applicable scope, limit, current value, remaining value, and `resets_at`. Do not automatically retry either code merely because its HTTP status is `429`: an administrator may change a control before reset, but only `rate_limit_exceeded` is transient by itself.

## What each counter records

One newly accepted Playbooks job or Audience cycle adds exactly `1` to Usage `requests`. Idempotent replay returns the original job without adding another request. Rejected job creation, campaign setup, reads, polling, candidate retrieval, and Usage calls add `0` to this monthly counter. They can still consume the API-key request-rate window.

When a job finishes, the amount it was charged is added to `cost_usd`; it does not add a second request. A run that fails is not charged and adds `0`. A request quota checks whether the next new job would exceed its limit. A cost quota stops new jobs once the amount charged in its scope has reached the limit. Work already accepted continues even if a later completion crosses a cost or budget threshold. `tokens` is retained in usage objects for compatibility and is always `0`. Token quotas can no longer be created, and an existing token quota reports `used: 0`.

Budgets count what runs are charged (the debits on the prepaid balance), independently of Usage quotas. A soft budget records alerts but does not reject work. A hard budget rejects new work once the period's charges reach its ceiling; runs already accepted are never cut off, so the runs in progress when the ceiling is reached can take the total past it. `budgets` in `GET /v1/usage` lists monthly budgets only; read daily limits with `get_project_limits` and `get_company_limits` (see [Managing your clients with projects](https://engine.neraperla.com/docs/projects#daily-and-monthly-limits)). Prepaid billing is separate: any positive spendable balance permits work to start, with no admission estimate or price reserve. At completion, the run's price is charged in full, and that charge is the `cost_usd` reported for the job. If that price exceeds the remaining balance, the job still succeeds with its result and the balance goes negative; auto-recharge is then triggered, and new work is rejected with `insufficient_credits` until a top-up restores a positive balance. `credits.balance_usd` is the current ledger balance, which can be negative, not a monthly counter.

Usage records are append-only. The public Usage API returns the authenticated project's current monthly rollup and capability breakdown:

```bash
curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/usage" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" | jq .
```

```json
{
  "project_id": "proj_example",
  "period": "2026-07",
  "period_start": "2026-07-01T00:00:00Z",
  "period_end": "2026-08-01T00:00:00Z",
  "rollup": {
    "requests": 12,
    "tokens": 0,
    "cost_usd": 1.243
  },
  "by_capability": [
    {
      "capability_key": "playbooks",
      "requests": 12,
      "tokens": 0,
      "cost_usd": 1.243
    }
  ],
  "usage_tier": {
    "key": "tier_2",
    "name": "Tier 2",
    "rank": 2,
    "rate_limit_per_minute": 300,
    "monthly_cost_cap_usd": 2500.0
  },
  "rate_limit": {
    "limit": 300,
    "window_seconds": 60
  },
  "quotas": [
    {
      "metric": "requests",
      "period": "month",
      "scope": "project",
      "capability_key": "playbooks",
      "limit_value": 1000,
      "used": 12,
      "remaining": 988,
      "resets_at": "2026-08-01T00:00:00Z"
    }
  ],
  "budgets": [
    {
      "period": "month",
      "scope": "project",
      "capability_key": null,
      "limit_usd": 50,
      "spend_usd": 1.243,
      "remaining_usd": 48.757,
      "hard_limit": true,
      "resets_at": "2026-08-01T00:00:00Z"
    }
  ],
  "credits": {
    "billing_enabled": true,
    "balance_usd": 98.757,
    "topup_increment_usd": 100.0
  }
}
```

`period_start` is inclusive and `period_end` is exclusive. `rollup` totals the project, while `by_capability` reconciles those counters by capability key. Every `cost_usd`, `spend_usd`, and `limit_usd` is an amount charged to the prepaid balance, so these figures reconcile with your transactions and statements. `usage_tier` is nullable and reports the organization's resolved rate and monthly spend cap when tiering applies. `quotas` includes every organization, project, or API-key quota that can affect this key; `budgets` includes every organization or project budget that can affect this project. Empty arrays mean no matching control is configured. Compare a completed job's `usage` with these rollups while allowing for other jobs in the same period.

Usage retrieval is OpenAPI operation `usage_v1_usage_get` with schema `PublicUsageResponse`.
