API credits, rate limits, and errors

Resolve Rankability's active usage contract and handle API request limits, crawler quotas, allowance or credit errors, and safe retries.

Reliable Rankability integrations treat request limits, job limits, outcome allowances or credits, and retries as separate controls. A request can be under the per-minute limit and still fail because a job is already running, the applicable usage is unavailable, or a crawler quota has been reached.

Request-rate headers

Current Rankability Core, Scale, and Agency plans allow 30, 60, and 120 Agent API requests per minute per key respectively. Existing full-platform plans currently allow 60. Do not hard-code those values. Read these headers on responses:

• X-RateLimit-Limit

• X-RateLimit-Remaining

• X-RateLimit-Reset

• Retry-After on a request-rate 429

The limit is enforced per API key in a sliding one-minute window. A 429 rate_limit_exceeded response identifies the current limit and reset interval.

Crawler daily page quotas

Scrape and Crawl also use a plan-aware daily page quota. Check it without fetching a page:

curl https://app.rankability.com/api/agent/v1/crawler/usage \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

Crawler responses expose X-Quota-Limit, X-Quota-Used, and X-Quota-Remaining. A daily quota failure returns 429 quota_exceeded and resets when the UTC date changes. This quota is separate from request rate limiting and credit affordability.

See Scrape, Crawl, and Extract API for page accounting and crawl limits.

Resolve the active usage contract

Before consequential Copywriter work, request the account's canonical usage contract:

curl https://app.rankability.com/api/agent/v1/usage \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

Scope required: any Copywriter, Tracker, Optimize, Page Auditor, or Site Auditor read/run scope. This lets an integration inspect the active contract before using the paid product it is authorized to run.

Read product_mode and metering_model before interpreting the response:

• copywriter_core with outcome_allowances returns the limit, used, reserved, and remaining units for content_asset, optimization, and full_document_rewrite. shared_credits is null.

• full_platform with shared_credits returns one organization credit balance. The per-outcome entries identify their credit charge and set allowance_applicability: "not_applicable"; their allowance-only fields remain null for backward compatibility.

contract_version identifies the Agent API wire format. source_contract_version identifies the underlying pricing or allowance policy used to populate that format, so it can change independently when pricing policy changes without a wire-format break.

For full-platform balances, treat available as the settled wallet balance after finalized ledger debits. It is not computed as purchased - used: included, rollover, and purchased are separate ledger buckets, and purchased credits are reduced when they are spent. used can therefore exceed included without implying a negative wallet or an invalid test balance. reserved is pending authorized work, while spendable_now = max(0, available - reserved) is the authoritative amount available for a new reservation.

cycle_state is current, reset_pending, or unavailable. Only a current cycle returns billing_cycle_start, billing_cycle_end, and next_reset_at; next_reset_at equals the current cycle end. When reconciliation cannot establish a renewed period, reset_pending returns those current-period fields as null and preserves the expired stored window only as last_known_billing_cycle_start and last_known_billing_cycle_end. Never present a last-known expired date as the next reset.

Estimate a specific MCP or Agent API operation

Use the read-only estimator before asking a user to approve spend:

curl "https://app.rankability.com/api/agent/v1/usage/estimate?operation=site_audit_run&max_pages=500" \
  -H "Authorization: Bearer rk_live_YOUR_KEY"

Supported operation names are create_content_auto, create_content_stepped, create_content_autopilot, optimize_page, page_audit_run, and site_audit_run. The response reports the active account unit, quantity, charge point, and assumptions. It never starts work or creates a reservation. A Site Auditor estimate is a maximum affordability ceiling; final billing uses successfully crawled pages and may be lower.

The response is private and uncached. Do not substitute GET /credits/balance for this decision: that endpoint is the legacy full-platform balance view.

When usage is consumed

Read endpoints normally do not start metered work. Run and write endpoints follow the billing contract of the product they invoke.

Operation	Billing behavior
Copywriter new content	Current plans consume 1 content-asset unit; full-platform accounts consume 750 credits. Research and brief work consume 0, and platform selection changes evidence coverage rather than the completed outcome.
Copywriter optimization	Current plans consume 1 optimization unit or 1 rewrite unit for the matching successful outcome. Full-platform accounts consume 400 credits for an optimization or 250 for a requested full-document rewrite.
Copywriter Autopilot	Consumes 1 content-asset unit or 750 full-platform credits after a usable draft exists. Pre-draft failures release the reservation; automatic finishing, retries, and repairs add no usage.
Researcher	Non-cached jobs charge at creation; a failed job refunds the charge. Valid cached results cost 0.
Optimize	Consumes 1 Core optimization allowance or 400 full-platform credits after a successful synchronous analysis.
Page Auditor	Reserves 150 credits at creation, finalizes on success, and releases the reservation after a failed audit.
Site Auditor	Checks affordability before starting and charges 1 credit per 5 successfully crawled pages only after completion. Cancelled or errored crawls cost 0.
Scrape	Charges 10 credits after a successful non-cached fetch.
Bounded Crawl	Checks the maximum page budget first and charges 10 credits per successfully crawled page after completion.
Extract	Charges 50 credits only after a successful extraction.
Tracker scans	Cost depends on the project's platforms, resolved locations, and Local Pack grid size.

The credit costs reference is the canonical cross-product rate table.

Structured errors

Agent API errors use this shape:

{
  "error": {
    "code": "invalid_input",
    "message": "Invalid request body",
    "details": {}
  }
}

Every authenticated Agent API response should include X-Request-Id. Log that ID, the method, route, status, and time. Do not log Bearer tokens, private content, or complete request bodies containing sensitive data.

Common statuses

HTTP status	Common code	Meaning
400	invalid_input, validation_error, invalid_operation	Missing, malformed, unsafe, or unsupported input
401	unauthorized	Missing or invalid authentication
402	copywriter_allowance_exhausted	The required Copywriter outcome allowance has no available unit; inspect outcome, required, and remaining
402	insufficient_credits, client_cap_exceeded	The operation cannot begin under the current full-platform balance or account limit
403	forbidden, plan_limit_exceeded	Missing scope or unavailable plan capability
404	not_found	The resource does not exist in the authenticated organization
409	conflict	A job is already running or the resource is in the wrong state
422	validation_error	A structured payload failed field-level validation
429	rate_limit_exceeded, quota_exceeded	Request, concurrency, or crawler quota reached
500	internal_error	Unexpected server failure
502	optimize_unavailable or provider failure	A required internal or external service was unavailable
504	optimize_timeout	A synchronous analysis exceeded its time budget

Retry safely

• Retry reads and documented polling calls with exponential backoff and jitter.

• For 429, respect Retry-After or the returned quota window.

• For 502 and 504, retry later with a bounded attempt count.

• Do not retry 400, 401, 402, 403, or 404 until the underlying input, key, allowance or balance, scope, or ID changes.

• On 409, inspect the returned state or existing run ID instead of creating duplicate work.

• Send a stable Idempotency-Key on supported create calls. Reusing only the URL or request body is not a substitute for that header.

• Store returned operation IDs before polling.

Start with Getting started with the API and use API use cases and integration patterns for complete workflow examples.