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.
Usage and allowances
Section titled “Usage and allowances”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 /usageAuthorization: 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=500For 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.
Plan a batch
Section titled “Plan a batch”Add count to ask whether a batch of the same operation fits:
GET /usage/estimate?operation=page_audit_run&count=1500Pooled 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.nullwhen 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=0Authorization: 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=0Authorization: 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.
Full-platform credit costs
Section titled “Full-platform credit costs”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.
Control your cost
Section titled “Control your cost”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_platformsto 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_platformsand acredits_estimatedfigure — 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"].
How reservations work with the API
Section titled “How reservations work with the API”- 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.
- Reservation: One outcome allowance or the Full credit price is reserved when billable work is accepted. This prevents parallel jobs from overspending.
- Finalization: The reservation is consumed only when a usable deliverable exists.
- Release on failure: If the job fails before that point, the reservation is released.
When you run out of credits
Section titled “When you run out of credits”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.
