Billing & Usage

Plan entitlements

Credit weights and a worked example

The generated OpenAPI contract publishes each operation's x-hebbrix-default-credit-weight. Defaults: read operations 0; raw memory 1; smart ingestion 5; hybrid search 2; reasoning search 10; documents 10 per MB. These are operation weights, not a universal one-credit-per-request promise.

Example using those defaults: 100 raw writes × 1 + 50 hybrid searches × 2 + 10 smart-ingestion requests × 5 = 250 operation credits. Managed-model usage, size-based operations, and account-specific billing configuration can add or change charges. Check the served-model usage receipt, current credit balance and billing ledger for actual amounts; the example is not a price guarantee.

Pricing Tiers

Usage Limits

Endpoints

Code Examples

Check Usage

import os
import requests

BASE = "https://api.hebbrix.com/v1"
H = {"Authorization": f"Bearer {os.environ['HEBBRIX_API_KEY']}"}

# GET /v1/usage: dashboard-style overview with PDF-contract api_calls
# object exposed at the top level.
r = requests.get(f"{BASE}/usage", headers=H)
usage = r.json()

ac = usage["api_calls"]
print(f"API Calls: {ac['used']}/{ac['limit']}")  # limit = -1 for unlimited tiers
print(f"Remaining: {ac['remaining']}")
print(f"Percentage: {ac['percentage']:.1f}%")

# Summary block has success_rate, total_bytes_*, avg_latency_ms, etc.
print(f"Avg latency: {usage['summary']['avg_latency_ms']} ms")

Monitor Usage Programmatically

# Warn when nearing the quota. Handle "unlimited" (limit=-1) safely.
r = requests.get(f"{BASE}/usage", headers=H)
ac = r.json()["api_calls"]

if ac["limit"] > 0:
    percent_used = (ac["used"] / ac["limit"]) * 100
    if percent_used > 80:
        print(f"Warning: {percent_used:.1f}% of API calls used this period")
    if percent_used > 95:
        print("Critical: upgrade or wait for the quota reset")
else:
    print("Unlimited tier, no quota pressure")

Upgrade Subscription

# POST /v1/billing/upgrade: body accepts `tier` (preferred) or the
# legacy `plan` key. Both resolve to the same internal field.
r = requests.post(
    f"{BASE}/billing/upgrade",
    headers=H,
    json={"tier": "pro", "billing_interval": "monthly"},
)
new_sub = r.json()

# GET /v1/billing/subscription: current plan + renewal date
r = requests.get(f"{BASE}/billing/subscription", headers=H)
sub = r.json()
print(f"Status: {sub['status']}")
print(f"Renews: {sub['current_period_end']}")

Rate limits and headers

Successful responses do not promise a remaining-request or reset header. On a rate-limit failure, use the HTTP 429 status and Retry-After when present. The tier-aware defaults and error envelopes are documented together in Errors and rate limits.

Read quota and UTC period boundaries from GET /v1/usage/quota. Usage overview windows are rolling intervals, not lifetime API-key counters. API-key metadata and traffic from removed keys are different concepts.

Overage & Limits

• Period boundaries. Subscription credits follow the period returned by the billing API. The legacy API-call quota is measured by UTC calendar month; the Usage page is a separately selected rolling reporting window. Use the returned start/end timestamps rather than assuming these periods are identical.
• Instant Upgrades. Upgrades take effect immediately with pro-rated billing. New limits apply right away.

Billing response fields

Metered operations return a set of billing fields so you can show cost and remaining quota to your users. The table below documents the meaning and stability of each one.

Stability. The following fields are a stable public contract: quota_remaining, estimated_cost_usd, billed_tokens, actual_tokens, and token_multiplier. You can rely on their names and semantics across releases.

cURL Example

curl -X GET "https://api.hebbrix.com/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"