Limits, budgets, and usage

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

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

ControlPurposeFailure and recovery
Request rateLimits 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 quotaLimits 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 allowanceStops 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.
Hard budgetStops 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 capStops 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.
Prepaid creditsRequires 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.

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). 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:

curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/usage" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" | jq .
{
  "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.