Rate Limits

Three independent ceilings apply to every tool call. The lowest one wins.

Per-user, per-month (plan-based)

Plan	All tools, monthly	verify_account, monthly
Free	500	50
Pro	10,000	1,000
Enterprise	100,000	10,000

Enterprise has a soft alert threshold at 500,000/month — it does not block, but a platform admin is notified.

verify_account has its own bucket because brand-safety vendors batch-check accounts and shouldn't share quota with normal reads.

Per-client (registered software)

Independent of which user authorized the client. Protects the platform from a runaway client even when many users have authorized it.

Client status	Per minute	Per hour
Verified	600	20,000
Unverified	60	2,000

To upgrade your client to verified, see Authentication → Verification status.

Per-user free-plan traffic gate

Free-plan users with more than 15,000 profile visits in a calendar month see Pro features (including outgoing webhooks, write tools that depend on Pro scopes) pause until the next month or an upgrade. Reads remain available; writes return traffic_gate.

Hitting a limit

When any limit is hit, the tool returns:

{
  "error": {
    "code": "rate_limited",
    "message": "Monthly call quota exceeded for plan: free",
    "data": {
      "scope": "user_monthly",
      "limit": 500,
      "remaining": 0,
      "reset_at": "2026-06-01T00:00:00Z"
    }
  }
}

scope is one of:

• user_monthly — plan-based monthly cap.
• verify_monthly — verify_account sub-bucket.
• client_minute — per-client per-minute cap.
• client_hour — per-client per-hour cap.
• traffic_gate — Free-plan visit threshold.

Headers

Every response includes:

X-Shuuka-RateLimit-Scope: user_monthly
X-Shuuka-RateLimit-Limit: 500
X-Shuuka-RateLimit-Remaining: 173
X-Shuuka-RateLimit-Reset: 1748736000

Use Remaining to back off proactively before you get a rate_limited error.

Best practices

• Cache Tier 1 reads. lookup_identity and verify_account results are stable for hours.
• Batch where possible. Tier 3 compare_accounts and rank_accounts operate on a list — one call instead of N.
• Use webhooks for state changes. Don't poll list_reports_about_me every minute. Subscribe to report.created and react.
• Respect step-up. Step-up failures count toward your client minute bucket. Don't loop.

Next

• Webhooks
• Examples