API docs v1

Pricing

Request units vs credits, monthly quotas, and the per-endpoint cost map.

The Public API uses two independent meters:

  1. Request units, bound to the per-key rate limit and the monthly request quota of your API plan. Today every /v1/* call costs 0 or 1 request unit; heavier endpoints (report runs, batched prompt evaluations) will be priced higher as they ship.
  2. Credits, consumed by endpoints that hit a paid LLM or third-party search backend. Reservations come out of the same credit pool you already use inside the Rank Prompt UI.

Today no /v1/* endpoint debits credits, so every call only moves the request-unit meter. That changes the moment we ship the report endpoints; the canonical, machine-readable cost for every route is the table below, derived straight from the OpenAPI spec.

Cost map

Every /v1/* endpoint, its weight in request units, and any flat credit cost it carries:

/brands

19 endpoint s
Method Endpoint Request units Credits
GET /v1/brands 1 ·
POST /v1/brands 1 ·
DELETE /v1/brands/{brand_id} 1 ·
GET /v1/brands/{brand_id} 1 ·
PATCH /v1/brands/{brand_id} 1 ·
GET /v1/brands/{brand_id}/alias-suggestions 1 ·
DELETE /v1/brands/{brand_id}/alias-suggestions/{business_name} 1 ·
POST /v1/brands/{brand_id}/alias-suggestions/{business_name}/acceptances 1 ·
GET /v1/brands/{brand_id}/citations 2 ·
GET /v1/brands/{brand_id}/citations/by-domain 2 ·
GET /v1/brands/{brand_id}/facts 1 ·
PATCH /v1/brands/{brand_id}/facts 1 ·
POST /v1/brands/{brand_id}/facts 2 1
DELETE /v1/brands/{brand_id}/shares 1 ·
GET /v1/brands/{brand_id}/shares 1 ·
POST /v1/brands/{brand_id}/shares 5 ·
PATCH /v1/brands/{brand_id}/shares/{share_id} 1 ·
GET /v1/brands/{brand_id}/white-label 1 ·
PATCH /v1/brands/{brand_id}/white-label 1 ·

/citations

1 endpoint
Method Endpoint Request units Credits
GET /v1/citations/{citation_id} 1 ·

/jobs

3 endpoint s
Method Endpoint Request units Credits
GET /v1/jobs 2 ·
DELETE /v1/jobs/{job_id} 1 ·
GET /v1/jobs/{job_id} 1 ·

/me

3 endpoint s
Method Endpoint Request units Credits
GET /v1/me 0 ·
GET /v1/me/quota 0 ·
GET /v1/me/usage 0 ·

/region-configs

10 endpoint s
Method Endpoint Request units Credits
GET /v1/region-configs 1 ·
POST /v1/region-configs 2 ·
DELETE /v1/region-configs/{region_config_id} 1 ·
GET /v1/region-configs/{region_config_id} 1 ·
PATCH /v1/region-configs/{region_config_id} 1 ·
DELETE /v1/region-configs/{region_config_id}/prompts 2 ·
GET /v1/region-configs/{region_config_id}/prompts 1 ·
POST /v1/region-configs/{region_config_id}/prompts 2 ·
DELETE /v1/region-configs/{region_config_id}/prompts/{prompt_id} 1 ·
PATCH /v1/region-configs/{region_config_id}/prompts/{prompt_id} 1 ·

/reports

15 endpoint s
Method Endpoint Request units Credits
GET /v1/reports 1 ·
POST /v1/reports 2 ·
DELETE /v1/reports/{report_id} 1 ·
GET /v1/reports/{report_id} 3 ·
PATCH /v1/reports/{report_id} 1 ·
GET /v1/reports/{report_id}/ai-analysis 1 ·
DELETE /v1/reports/{report_id}/prompts 2 ·
POST /v1/reports/{report_id}/prompts 5 ·
DELETE /v1/reports/{report_id}/prompts/{prompt_id} 1 ·
PATCH /v1/reports/{report_id}/prompts/{prompt_id} 1 ·
POST /v1/reports/{report_id}/runs 5 ·
DELETE /v1/reports/{report_id}/shares 1 ·
GET /v1/reports/{report_id}/shares 1 ·
POST /v1/reports/{report_id}/shares 3 ·
PATCH /v1/reports/{report_id}/shares/{share_id} 1 ·

/scheduled-reports

14 endpoint s
Method Endpoint Request units Credits
GET /v1/scheduled-reports 1 ·
POST /v1/scheduled-reports 2 ·
DELETE /v1/scheduled-reports/{scheduled_report_id} 2 ·
GET /v1/scheduled-reports/{scheduled_report_id} 1 ·
PATCH /v1/scheduled-reports/{scheduled_report_id} 1 ·
GET /v1/scheduled-reports/{scheduled_report_id}/analytics 2 ·
POST /v1/scheduled-reports/{scheduled_report_id}/executions 5 ·
GET /v1/scheduled-reports/{scheduled_report_id}/prompt-history/{region_config_prompt_id} 1 ·
GET /v1/scheduled-reports/{scheduled_report_id}/region-configs 1 ·
POST /v1/scheduled-reports/{scheduled_report_id}/region-configs/{region_config_id} 1 ·
DELETE /v1/scheduled-reports/{scheduled_report_id}/shares 1 ·
GET /v1/scheduled-reports/{scheduled_report_id}/shares 1 ·
POST /v1/scheduled-reports/{scheduled_report_id}/shares 5 ·
PATCH /v1/scheduled-reports/{scheduled_report_id}/shares/{share_id} 1 ·

How to read this. A 0 request-unit cost means the endpoint is free and never moves your monthly quota (today only GET /v1/me and GET /v1/me/quota qualify, so they are safe to poll). For endpoints that hit paid backends (rolling out alongside the report APIs), the credit column will reflect either a flat cost or the wording “variable” when the exact reservation depends on the request payload (number of prompts, models selected, etc.).

Quotas vs rate limits

  • Monthly request quota comes from your plan and resets on the billing anniversary. Exceeding it returns request_quota_exceeded (429).
  • Per-minute rate limit smooths bursty traffic regardless of plan. See Rate limits for the response headers and the recommended back-off strategy.
  • Free endpoints (GET /v1/me, GET /v1/me/quota) cost 0 request units and never count against your quota, so they are safe to poll.

Inspecting your usage

GET /v1/me/quota returns your remaining request units for the current billing period plus current_period_end (Unix seconds) so you know when the counter resets. The same numbers are mirrored on every metered response via the X-RP-Quota-* headers documented in Rate limits, so you usually only need to call /v1/me/quota directly when bootstrapping a worker or building a dashboard. The endpoint itself is free (0 request units) and never counts against your quota.

curl https://api.rankprompt.com/v1/me/quota \
  -H "Authorization: Bearer rp_live_YOUR_KEY"