---
title: "Usage and allowances"
description: "How API and MCP calls draw on your plan, how to check usage before starting work, and what happens when you run out."
canonical_url: "https://developers.rankability.com/guides/usage"
section: "Get started"
last_updated: 2026-11-14
---

# 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

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:

```http
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:

```json
{
  "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:

```http
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.

### Plan a batch

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

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

Pooled accounts get a `batch` object:

```json
{
  "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.

```json
{
  "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:

```http
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

Read persisted GSC performance for one organization-owned client:

```http
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.

### 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

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"]`.

### How reservations work with the API

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.

### When you run out of credits

The API returns:

```json
{
  "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.
