Skip to content

Usage and allowances

How API and MCP calls draw on your plan, how to check usage before starting work, and what happens when you run out.

API and MCP work uses the same product entitlement as the application. There is no separate API balance:

  • Core accounts consume completed-outcome allowances: one content asset, one optimization, or one full-document rewrite.
  • Full-platform pooled accounts receive full tool access against general and burst percentage windows. Scheduled work remains protected.
  • Grandfathered full-platform accounts keep their existing price and unlimited-client promise while using pooled usage.

Check the active contract without starting or reserving work:

GET /usage
Authorization: Bearer rk_live_...

Scope required: copywriter:read or copywriter:run

The response identifies the connected organization (id and name; name is null when it cannot be resolved), product_mode, and metering_model. Core responses include exact allowance values. Pooled responses expose general and burst remaining percentages, recovery timestamps, protected scheduled-work state, and the billing usage-page path.

Pooled response example:

{
"contract_version": "platform-usage-v3-2026-08-23",
"product_mode": "full_platform",
"metering_model": "pooled_usage",
"outcomes": {
"content_asset": {
"charge_amount": null,
"charge_unit": null,
"usage_impact": "on_demand"
}
},
"shared_credits": null,
"pooled_usage": {
"general": {
"label": "7-day usage",
"remaining_percent": 70,
"state": "healthy",
"recovers_at": null
},
"burst": {
"label": "24-hour usage",
"remaining_percent": 82,
"state": "healthy",
"recovers_at": null
},
"scheduled_work": {
"state": "protected",
"label": "Scheduled work is protected"
},
"usage_path": "/settings?tab=billing#usage"
}
}

Check the impact of a supported operation without starting work:

GET /usage/estimate?operation=site_audit_run&max_pages=500

For pooled accounts this returns included: true, usage_impact, current window percentages, and no monetary or credit amount. If a window is exhausted, action endpoints return 429 usage_limit_reached with retry_at and usage_path. Stable Idempotency-Key retries continue to return an existing accepted action before the cap gate runs.

Add count to ask whether a batch of the same operation fits:

GET /usage/estimate?operation=page_audit_run&count=1500

Pooled accounts get a batch object:

{
"batch": {
"count": 1500,
"fits_now": false,
"max_count_now": 140,
"projected_general_remaining_percent": 0,
"projected_burst_remaining_percent": 0,
"earliest_fit_at": null,
"fits_in_one_window": false,
"advisory": true
}
}
  • fits_now: the whole batch fits both windows right now.
  • max_count_now: how many runs fit right now. Start that many, then check again.
  • earliest_fit_at: when the whole batch would fit if started then. null when it already fits, when it is larger than a full window (fits_in_one_window: false, so split it), or when the capacity in use is held by work still running.
  • advisory: the projection reserves nothing. The action endpoint still decides, and another job can use capacity in between.

Operations whose usage depends on provider results, such as search_intelligence_query, return fits_now: null with a reason. No unit amounts or prices are returned. count has no effect on Copywriter Core or credit accounts.

{
"contract_version": "platform-usage-v3-2026-08-23",
"product_mode": "copywriter_core",
"metering_model": "outcome_allowances",
"copywriter_plan": "scale",
"outcomes": {
"content_asset": {
"charge_amount": 1,
"charge_unit": "content_asset",
"charge_point": "usable_deliverable",
"limit": 100,
"used": 12,
"reserved": 2,
"remaining": 86
}
},
"shared_credits": null
}

The legacy GET /credits/balance endpoint remains available only to shared_credits accounts. Pooled accounts receive 410 credit_balance_retired and should use GET /usage.

Read the completed-outcome audit trail without starting work:

GET /usage/events?client_id=:clientId&operation_type=copywriter_quick&limit=50&offset=0
Authorization: Bearer rk_live_...

GET /usage/events is organization-scoped and paginated (maximum 100 rows). Shared-credit responses include the signed amount, balance_after, idempotency_key, and resulting artifact_id recorded in the credit ledger. Pooled responses identify the completed outcome, workload, source, client, artifact, and retry key with unit: "included_usage"; they do not fabricate a per-action price or expose internal capacity units. Core allowance-only completions may not create a credit transaction, so GET /usage remains authoritative for current allowance balances.

Query-level Google Search Console evidence

Section titled “Query-level Google Search Console evidence”

Read persisted GSC performance for one organization-owned client:

GET /clients/:id/gsc/search-performance?mode=queries&start_date=2026-07-01&end_date=2026-07-28&limit=50&offset=0
Authorization: Bearer rk_live_...

Scope required: clients:read

mode can be queries, pages, or query_pages. Optional filters include query_contains, page_contains, device, three-letter country, and search_type. Sort by clicks, impressions, ctr, position, query, or page. Requests are capped at 120 days and 100 rows; follow pagination.next_offset for another page. The default is the latest complete 28-day window ending three days ago. Position is impression-weighted across the selected rows. The response also reports the selected GSC property and stored sync freshness. An empty row set means no matching persisted evidence, not zero demand.

Copywriter is priced by completed outcome. Research source selection changes evidence coverage but does not change the completed-deliverable price.

Outcome Credits What it covers
Research and brief only 0 Research, evidence collection, and a brief without a completed draft
Completed new content asset 750 Standard auto, approved stepped draft, or Autopilot
Completed existing-content optimization 400 Persistent optimization project for an existing URL
Successful full-document rewrite 250 A user-requested rewrite of the current document
Automatic fact enrichment, retries, and repairs 0 additional Included finishing work

The legacy job-creation response reports credits_estimated alongside resolved research_platforms; use GET /usage as the authoritative cross-product entitlement contract.

Copywriter research breadth does not change the fixed outcome price. To keep automated pipelines focused and predictable:

  • Use the default for organic evidence. Omit research_platforms to run Google Organic plus the hidden compatibility video keys.
  • Add AI sources deliberately. Pass additional keys only when the job needs evidence from those platforms.
  • Do not treat a smaller platform list as a discount. A usable completed new content asset is 750 credits whether it uses the default or broader research.
  • Read the estimate back. Every job-creation response echoes the resolved research_platforms and a credits_estimated figure — log these so your automation can budget per run.

organic is always included regardless of what you send, so the minimum meaningful selection is ["organic"].

  1. Pre-check: When you create a job, the API checks the active product entitlement. No job is created when the required allowance or credit balance is unavailable.
  2. Reservation: One outcome allowance or the Full credit price is reserved when billable work is accepted. This prevents parallel jobs from overspending.
  3. Finalization: The reservation is consumed only when a usable deliverable exists.
  4. Release on failure: If the job fails before that point, the reservation is released.

The API returns:

{
"error": {
"code": "insufficient_credits",
"message": "Not enough credits. Purchase more credits or upgrade your plan.",
"details": {
"required": 750,
"available": 500
}
}
}

To get more credits, log in to Rankability and go to Settings > Billing to purchase a credit pack or upgrade your plan. Once your balance is replenished, API calls work again immediately.

Core accounts receive copywriter_allowance_exhausted instead. Its details identify the completed outcome, the one required unit, and the remaining allowance. Use GET /usage to inspect the period and all remaining outcome allowances.