Marrow
Docs Sign in

Usage and credits

Marrow shows account usage in Console and returns credit headers from API requests. Check balances, credit costs, quota headers, and credit errors here.

Quota and credit values are account-specific. For a customer API key, use GET /v1/access as the current authority for that key's scopes, context boundary, quotas, and credit balance. For each request, use the response headers returned by the API; the documentation does not publish fixed account limits.

Where to check usage

Open Marrow Console. Its Usage view shows:

  • monthly credits remaining;
  • onboarding credits remaining;
  • total credits remaining;
  • recent processing jobs;
  • recent account activity.

Account-level balances and recent activity live in Console. Signed-in CLI sessions and browser account sessions can also call the account usage endpoint:

GET /v1/account/usage
Authorization: Bearer <CLI session token>

Customer API keys do not authorize account-management endpoints.

The response includes credits, quota counters, recent ledger rows, and 30 UTC daily usage buckets:

{
  "schemaVersion": "marrow-account-usage-v1",
  "credits": {
    "balance": {
      "totalRemaining": 349
    },
    "monthly": {
      "remaining": 99,
      "resetAt": "2026-06-01T00:00:00.000Z"
    },
    "onboarding": {
      "remaining": 250
    }
  }
}

Credit costs

A new POST /v1/query operation reserves and settles one base query credit. Evidence and Context modes have no Product Answer provider charge. Answer mode may also spend provider-work credits; the operation and response credit headers report the amount actually settled. Listing or fetching stored labels, claims, events, and queue status does not spend a query credit.

Provider-backed file and URL previews spend processing credits when extraction runs. Record processing costs vary because the amount of text and processing work can differ by file or URL. Queueing the exact preview plan does not charge for that extraction a second time.

Monthly credits are used before onboarding credits. The monthly balance resets at the start of the account's current monthly period. Onboarding credits are a one-time balance for initial setup.

API headers

Successful queries, provider-backed previews, and credit-related errors include credit headers:

x-marrow-credit-cost: 1
x-marrow-credit-remaining: 349
x-marrow-credit-monthly-remaining: 99
x-marrow-credit-onboarding-remaining: 250
x-marrow-credit-monthly-period: 2026-05-01

The values above illustrate the header names, not an account entitlement. Credit headers report only account credit impact for the request.

Queries and record-processing requests each count against their own daily and monthly allowance. Provider-backed previews and live ingest requests use the record processing allowance. These requests carry the same quota headers, and metric names the allowance the request spent:

x-marrow-quota-metric: query
x-marrow-quota-daily-limit: <current daily limit>
x-marrow-quota-daily-remaining: <current daily remainder>
x-marrow-quota-daily-reset: <UTC reset timestamp>
x-marrow-quota-monthly-limit: <current monthly limit>
x-marrow-quota-monthly-remaining: <current monthly remainder>
x-marrow-quota-monthly-reset: <UTC reset timestamp>

Query operations report query; provider-backed previews and queued record submissions report ingest. A structural preview that makes no provider call does not spend the ingest allowance. Spending one allowance never draws down the other. GET /v1/access returns both counters for the current key.

Credit and quota errors

If credits run out, a query or provider-backed preview returns account_credits_exhausted and no additional paid processing is started. Queued record processing ends as a failed job with failure.retryable: false and a public credit message; private processing and ledger codes are not returned on the job.

A Query operation reserves its maximum possible cost, then refunds unused provider-work credits. Once canonical retrieval begins, the base query credit is retained even if later retrieval or Answer work fails; completed provider work may also remain charged. If settlement cannot be recorded, Marrow returns credit_settlement_failed and reports the standing debit. A failed provider-backed preview cannot be queued; its credit headers report any standing provider charge.

When either allowance is exhausted the request returns account_quota_exceeded and does not spend credits: questions stop when the query allowance is spent, live record submission stops when the ingest allowance is spent. The response carries retry-after with the seconds until that allowance resets. Wait for the reset, or reduce the work you are sending.

Reusing an idempotencyKey for an exact retry of a completed Query operation replays its stored result without spending query quota or credits again. Reuse with different inputs fails with idempotency_conflict. The same rule applies to an already queued record job: an exact replay does not spend another ingest unit.

Product request rate limits are shared by the account, so creating or rotating an API key does not reset the window. A limit hit returns rate_limited, also with retry-after.

  1. Create an account or sign in.
  2. Install the CLI and connect it with marrow auth login.
  3. Create or rotate API keys only when building apps or automation.
  4. Add one representative URL or file.
  5. Ask a question after processing succeeds.
  6. Review remaining credits in Console.