Rate limits and quotas

Summary#

Two independent ceilings govern API usage. An hourly fair-use limit of 100 calls caps light, low-cost work and protects the platform from scraping. A monthly credit quota set by your plan caps expensive work. On top of those sit a set of payload, pagination and timeout limits per endpoint. This page lists all of them with exact numbers, so you can size a job before you run it.

Overview#

Which ceiling applies to a given call#

Every metered call carries a credit cost. That cost decides which ceiling applies:

The threshold is exactly 3. A call costing fewer than 3 credits is treated as light and is never blocked by the monthly quota; a call costing 3 or more is checked against it. POST /api/v1/analyze costs 6, so it is governed by your monthly quota and is not subject to the hourly limit.

The hourly fair-use limit#

The 429 body:

{
  "error": "Hourly fair-use limit reached (100 light-tool calls/hour). This protects our infrastructure from abuse while keeping your monthly usage unlimited. Please wait ~14 minutes for the next hourly reset.",
  "code": "hourly_rate_limit",
  "limit": 100,
  "used": 100,
  "reset_in_minutes": 14
}

Because the bucket is a clock hour rather than a sliding window, the wait is never more than 60 minutes and reset_in_minutes tells you exactly how long.

IP-keyed buckets#

Two paths are limited by IP address rather than by account:

Both share the same 100-per-hour ceiling, keyed on the connecting IP. Traffic from behind a shared egress address therefore shares one bucket.

The monthly credit quota#

Credits reset at the start of each UTC calendar month. Usage is the sum of AI runs and tool runs for that month.

The 429 when the allowance is spent:

{
  "error": "You've used all 10000 premium reports on the ENTERPRISE plan this month. Light tools (keyword research, SERP, content, technical audits) keep working. Quota resets on September 1, 2026 (in 26 days). Upgrade to continue using premium reports now.",
  "code": "quota_exceeded",
  "plan": "enterprise",
  "used": 10000,
  "quota": 10000,
  "cost": 6,
  "reset_at": "2026-09-01T00:00:00.000Z",
  "reset_date": "September 1, 2026",
  "days_until_reset": 26,
  "upgrade_url": "https://metricvaultai.com/index.html#pricing"
}

Read reset_at rather than parsing reset_date, and do not retry before it. See Quotas and rate limits and How credits work.

What the public API costs#

Usage from the API is attributed to the tool name domain_overview and appears in the same monthly totals as work done in the app. Query it with POST /api/usage, which returns used, quota, remaining, percent_used, near_limit, over_limit, days_until_reset and a per-tool breakdown.

The recommendations quota#

The Get Recommendations feature has its own separate monthly allowance, checked before the credit quota.

Below-tier calls return 403 with reco_upgrade_required; exhausted allowances return 429 with reco_quota_exceeded. The minimum plan and the per-plan numbers are operator-tunable, so treat the table as the current defaults rather than a contract.

Order of the gates#

The gates run in a fixed order, and the first failure wins:

1. No identifiable account and a cost above zero → 401 auth_required.
2. Account suspended → 403 account_suspended.
3. Free plan and a cost above zero → 403 upgrade_required.
4. Cost below 3 → hourly limit, then allow.
5. Cost of 3 or more → monthly quota check.
6. Any lookup failure → 503, failing closed.

Payload limits#

Pagination and range limits#

Timeouts#

Long-form article generation runs inline on POST /api/premium-ai. The per-completion budget scales with the requested length: 90 seconds for the large content types (6000 output tokens or more), 45 seconds otherwise. Both sit under Cloudflare's 100-second idle ceiling. Set a client timeout above the larger one.

Set a client timeout of at least 60 seconds on POST /api/v1/analyze. It runs a model call inside the request.

Retention#

Caching is explained in Result caching and freshness. Note that a cache hit still charges your credits: caching saves the provider bill and the wait, not the cost.

Practical sizing#

There is no concurrency limit on the public endpoint. Your monthly quota is the real ceiling, and a burst simply spends it faster.

Handling limits in a client#

• Read code first. hourly_rate_limit is worth waiting out; quota_exceeded is not.
• On hourly_rate_limit, sleep for reset_in_minutes and retry.
• On quota_exceeded, stop and alert a human. Retrying before reset_at will fail identically.
• On 503 with plan_check_failed or quota_check_failed, retry with exponential backoff. Nothing was charged.
• Poll POST /api/usage before a large job and abort if remaining is less than the job's cost.