RichAPI bills in credits. One credit costs $0.02 on the 1,000 and 5,000 credit packs, and less on larger packs. A call must return a successful (2xx) response to consume a credit. RichAPI records one row for every call. The workspace shows those rows in the Usage & Credits dashboard, in an emailed CSV export, and through the GET /usage endpoint.

How does RichAPI count credits?

RichAPI writes one usage row for every request that reaches an endpoint. Each row carries the endpoint name, the HTTP status, a billable flag, the credits charged, and the number of results returned. The credit amount is computed at the time of the call and stored on the row. The dashboard, the CSV export, and the GET /usage endpoint all read those same stored rows, so the three always agree.

Credit totals cover every API key in the workspace, not the single key that sent a request. Aggregation runs in UTC.

Recorded per call	Meaning
`called_at`	UTC time of the call.
`api_name`	The endpoint that was called.
`api_key_name`	The API key that sent the call. Present in the CSV export.
`status_code`	The HTTP status returned.
`billable`	`true` for a call that consumed credits.
`credits`	Credits charged for this call. `0` for a non-billable call.
`result_count`	Results returned. Populated for per-result endpoints.
`latency_ms`	Elapsed milliseconds for the call.
`job_id`	The asynchronous job the call belongs to.
`request_id`	Correlation id for the call.
`cache_hit`	`true` for a response served from cache.
`is_status_check`	`true` for an asynchronous job status poll.

Which calls does RichAPI bill?

RichAPI bills a call under two conditions: the response status is 2xx, and the call is not an asynchronous job status poll. Every other call is recorded at 0 credits and shown as Free.

Call	Billed?	Credits
`2xx` response	Yes	The endpoint price.
`2xx` response served from cache	Yes	The endpoint price.
`email_finder` or `phone_finder` call that finds nothing (`"billed": false`)	No	`0`
`4xx` response (bad request, no credits, rate limit)	No	`0`
`5xx` response	No	`0`
Asynchronous job status poll	No	`0`

CAUTION: A successful call that returns zero results still costs the endpoint base price. A per-result endpoint with no base price costs 0 credits for a response with zero results.

What are the three billing models?

RichAPI uses three billing models. The endpoint catalog states which model an endpoint uses.

Model	Pricing fields	Charge
Per call	`credits_per_call`	A flat price for each successful call.
Per result	`credits_per_result`	The rate multiplied by the results returned.
Base plus per result	`base_credits_per_call` and `credits_per_result`	A base price for the call, plus the rate multiplied by the results returned.

The formula RichAPI applies is:

per call             credits = credits_per_call
per result           credits = credits_per_result × result_count
base plus per result credits = base_credits_per_call + (credits_per_result × result_count)

How does per-call billing work?

Per-call billing charges one flat price for each successful call. The number of results makes no difference to the price.

Worked example — Profile Enrichment (**enrich_profile**), 1 credit per call.

Successful calls	Credits	Cost
1	1	$0.02
100	100	$2.00
2,500	2,500	$50.00

Arithmetic: 2,500 calls × 1 credit = 2,500 credits. 2,500 credits × $0.02 = $50.00.

How does per-result billing work?

Per-result billing charges the rate for every result the response actually returns. RichAPI does not charge for the number of results requested.

Worked example — People Search (**people_search**), 0.1 credits per result.

A request asks for 100 results. The response returns 73 results. RichAPI charges for 73.

Results returned	Credits	Cost
25	2.5	$0.05
73	7.3	$0.146
100	10	$0.20

Arithmetic: 73 results × 0.1 credits = 7.3 credits. 7.3 credits × $0.02 = $0.146.

RichAPI reserves credits before it calls the provider. The reservation uses the requested limit. If a request sends no limit, the reservation uses the endpoint page size. After the response arrives, RichAPI commits the real amount and refunds the difference. The balance therefore dips during a long call. The balance recovers at the end of the call.

How does base plus per-result billing work?

Base plus per-result billing charges a fixed base price for the call, and then adds the per-result rate for every result returned.

Worked example — Lead Search (**lead_search**), 10 base credits plus 0.5 credits per result.

Results returned	Credits	Cost
0	10 + 0 = 10	$0.20
25	10 + 12.5 = 22.5	$0.45
100	10 + 50 = 60	$1.20

Arithmetic: 10 base credits + (25 results × 0.5 credits) = 22.5 credits. 22.5 credits × $0.02 = $0.45.

How to read the usage dashboard

The dashboard lives at /home/<workspace>/usage. The page is titled Usage & Credits. The page has three sections.

Open the workspace.
Select Usage & Credits in the navigation.
Read the Overview card for the workspace totals.
Read the Breakdown charts for the split by category and by endpoint.
Open the Activity section for the per-endpoint table and the call log.

What does the Overview card show?

The Overview card shows these metrics.

Metric	Meaning
Org Credit Balance	Credits left in the organization balance, which every workspace in the organization shares. Organization owners always see it. Other members see it when the workspace has no monthly spend limit.
Credit Balance	Credits left under the monthly spend limit of the workspace, with the caption `<n> allocated`. Shown only when the workspace has a spend limit.
Plan Credit Balance	Enrichment Pass credits left. Shown only while the organization has an active Enrichment Pass.
Total API Calls	Calls in the selected date range, with a percentage delta against the previous period of equal length.
Credits Used	Credits consumed in the selected date range, with the same percentage delta.
Most Used API	The endpoint with the most calls in the range, and its call count.

When the workspace has a monthly spend limit, a This team's spend limit card under the metrics shows the credits spent in this cycle against the limit.

What do the Breakdown charts show?

The Breakdown section holds two charts.

Chart	What it shows	Interaction
Credits by Category	A donut of credits grouped by endpoint category.	Click a slice or a legend label to filter the bar chart and the table below. Click Clear filter to remove the filter.
Top Endpoints	A bar chart of the top 10 endpoints.	Toggle between Calls and Credits.

What does the Activity section show?

The Activity section has two tabs.

API Usage Breakdown lists one row per endpoint.

Column	Meaning
Endpoint	The endpoint display name.
Category	The endpoint category.
Calls	Calls in the selected range.
Credits	Credits consumed in the selected range.

Click Calls or Credits to sort the table. The table shows five rows and a Show all**<n>**endpoints control.

Recent Calls lists one row per individual call, newest first.

Column	Meaning
Endpoint	The endpoint display name.
Called	Relative time. The tooltip shows the exact UTC timestamp.
Status	The HTTP status. Green for `2xx`, red for anything else, Unknown for a missing status.
Billable	Billable or Free.
Credits	Credits charged for that call.

Select Details on a row to expand Latency, Provider, Cache hit, Results, Your price, and Job ID.

Use the Search endpoint... box to filter by endpoint name. Use the all / ok / error control to filter by status. The table loads 25 rows at a time behind a Load more button.

Which date ranges can the dashboard show?

The date range picker sits at the top right of the page. The default range is the last 30 days.

Preset	Range
Today	The current day.
Last 7 days	Today and the six days before it.
Last 30 days	Today and the 29 days before it.
This month	The first day of the current month through today.
Last month	The whole previous calendar month.

Pick any two dates in the calendar for a custom range. A range must not exceed 90 days.

How to export usage as a CSV

The export produces one row per API call. RichAPI builds the file in the background and emails a download link to the account email of the person who requested the export.

Open the Usage & Credits page.
Select Export CSV at the top right.
Pick the date range in the Date range picker.
Select All data in this range, or select Filtered data.
For filtered data, pick an Endpoint and a Billable value.
Select Export.

CAUTION: An export range must not exceed 90 days. The dialog rejects a longer range and shows the day count.

Export filter	Values
Endpoint	Any endpoint, or one endpoint from the catalog.
Billable	Any, Billable only, Free only.

The endpoint and billable filters are the only export filters. The search text and the status filter in the Recent Calls table do not apply to an export.

The emailed file is a gzipped CSV named usage_<start>_<end>.csv.gz. The file holds these columns, in this order:

CSV column	Meaning
`called_at`	UTC time of the call.
`api_name`	The endpoint that was called.
`api_key_name`	The API key that sent the call.
`status_code`	The HTTP status returned.
`billable`	`true` for a call that consumed credits.
`credits`	Credits charged for this call.
`job_id`	The asynchronous job the call belongs to.
`request_id`	Correlation id for the call.
`latency_ms`	Elapsed milliseconds for the call.
`result_count`	Results returned.
`plan_credits`	Enrichment Pass credits that the call used. Empty when bundle credits paid for the whole call. `credits` always holds the whole charge.

The download link is valid for 7 days. The link carries a signed token in the path, so the link works from an email client with no API key. Treat the link as a password.

Method: GET
URL: https://api.richapi.ai/api/v1/usage/export/download/{token}
Authentication: none. The token in the path is the only credential.
Response: 302 redirect to a short-lived download URL. 404 for an invalid or expired link.

How to query usage with the API

GET /usage returns credit consumption for the current month, a named month, several months, or a custom date range. The endpoint is free.

Method: GET
URL: https://api.richapi.ai/api/v1/usage
Authentication: the x-api-key header
Response: synchronous JSON
Cost: 0 credits

Send a GET request to https://api.richapi.ai/api/v1/usage.
Set the x-api-key header to your API key.
Add month, months, include_previous, or start_date to select a window.
Add include=history to receive the individual calls.

cURL

curl -X GET "https://api.richapi.ai/api/v1/usage?month=2026-07"   
  -H "x-api-key: YOUR_API_KEY"

Python

import requests

response = requests.get(
    "https://api.richapi.ai/api/v1/usage",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={"month": "2026-07"},
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch(
  "https://api.richapi.ai/api/v1/usage?month=2026-07",
  {
    method: "GET",
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  },
);

const data = await response.json();
console.log(data);

Which parameters does GET /usage accept?

Parameter	Type	Required	Default	Description
`month`	string	No	Current month	Month in `YYYY-MM` format. Mutually exclusive with `months`, `include_previous`, and `start_date`.
`months`	integer	No	—	Number of recent months to include, from 1 to 12. Mutually exclusive with `month`, `include_previous`, and `start_date`.
`include_previous`	boolean	No	—	Include the current and the previous month. Mutually exclusive with `month`, `months`, and `start_date`.
`start_date`	string (date)	No	—	First day of a custom range, `YYYY-MM-DD`, UTC, inclusive. Mutually exclusive with `month`, `months`, and `include_previous`. The range must not exceed 90 days.
`end_date`	string (date)	No	Today	Last day of the custom range, inclusive. Requires `start_date`.
`sort_by`	string	No	`credits`	Sort the `apis` list. One of `credits`, `calls`, `name`.
`order`	string	No	`desc`	Sort order. One of `asc`, `desc`.
`filter`	string	No	—	Filter `apis` by a case-insensitive substring of `api_name` or `display_name`.
`include`	string	No	—	Comma-separated extras. `history` adds the `history` array. An unrecognised value returns `400`.
`history_limit`	integer	No	`5`	Number of recent calls to return, from 1 to 1000. Ignored unless `include=history`.

What does GET /usage return?

{
  "months": ["2026-07"],
  "total_credits": 42.5,
  "total_cost": 0.85,
  "credit_value": 0.02,
  "total_records": 2,
  "apis": {
    "enrich_profile": {
      "calls": 25,
      "credits": 25,
      "display_name": "Profile Enrichment",
      "category": "Enrichment"
    },
    "people_search": {
      "calls": 5,
      "credits": 17.5,
      "display_name": "People Search",
      "category": "Search"
    }
  },
  "credits_by_category": {
    "Enrichment": 25.0,
    "Search": 17.5
  }
}

Arithmetic check: 25 credits + 17.5 credits = 42.5 credits. 42.5 credits × $0.02 = $0.85.

What does each usage response field mean?

Field	Type	Description
`months`	array of string	The months the response covers. In date-range mode, the first and the last month can be covered only in part.
`start_date`	string (date)	First day covered. Present only for a request that sends `start_date`.
`end_date`	string (date)	Last day covered, inclusive. Present only for a request that sends `start_date`.
`total_credits`	number	Credits consumed across the window, rounded to two decimals.
`total_cost`	number	`total_credits` × `credit_value`, in US dollars.
`credit_value`	number	Dollar value of one credit. `0.02`.
`total_records`	integer	Number of endpoints in `apis` after the `filter` is applied.
`apis`	object	One entry per endpoint, keyed by endpoint name.
`apis.<name>.calls`	integer	Calls to that endpoint in the window.
`apis.<name>.credits`	number	Credits consumed by that endpoint, rounded to two decimals.
`apis.<name>.display_name`	string	Human-readable endpoint name.
`apis.<name>.category`	string, nullable	Endpoint category.
`credits_by_category`	object	Total credits grouped by category.
`credits_remaining`	number, nullable	Credits left in the organization balance. `null` when RichAPI cannot read the balance.
`monthly_breakdown`	object	Per-month totals. Present only for a request that covers more than one month.
`history`	array	Recent individual calls, newest first. Present only for a request with `include=history`.
`history_count`	integer	Number of entries in `history`. Present only for a request with `include=history`.

How to list individual calls

Add include=history and history_limit to receive the per-call rows. The rows cover every API key in the workspace. The rows include non-billable calls, so the rows describe the same calls the credit totals were computed from.

curl -X GET "https://api.richapi.ai/api/v1/usage?start_date=2026-07-01&end_date=2026-07-29&include=history&history_limit=100"   
  -H "x-api-key: YOUR_API_KEY"

`history` field	Type	Description
`timestamp`	number	Unix timestamp of the call.
`api_name`	string	The endpoint that was called.
`status_code`	integer	The HTTP status returned.
`billable`	boolean	`true` for a call that consumed credits.
`credits`	number	Credits charged for the call.
`your_price`	number	Dollar price of the call.
`job_id`	string, nullable	The asynchronous job the call belongs to.
`provider_used`	null	Always `null`.
`is_status_check`	boolean	`true` for an asynchronous job status poll. Status polls are never billable.
`cache_hit`	boolean	`true` for a response served from cache.
`latency_ms`	integer, nullable	Elapsed milliseconds for the call.
`result_count`	integer	Results returned.

How to explain a usage discrepancy

Compare the dashboard, the CSV export, and GET /usage before you open a ticket. All three read the same rows. The table below lists the causes of an apparent difference.

Symptom	Cause	What to do
A call appears in the log but costs 0 credits.	The response was not `2xx`, or the call was an asynchronous status poll.	Read the Status and Billable columns. A Free row is correct.
A search cost less than the request asked for.	Per-result billing charges the results returned, not the results requested.	Read `result_count` in the CSV export or in the `history` array.
The balance dropped and then recovered.	RichAPI reserves credits before the provider call, then commits the real amount and refunds the difference.	Read the committed amount in the Recent Calls row.
Totals are higher than one key explains.	Credit totals cover every API key in the workspace.	Group the CSV export by `api_key_name`.
A day boundary is off by one.	Aggregation runs in UTC. A local-time day starts and ends at a different instant.	Compare against UTC, or use `called_at` in the CSV export.
A total ends in an unexpected decimal.	`total_credits` and each endpoint total are rounded to two decimals.	Sum the per-call `credits` values in the CSV export.
A cached response was billed.	A cached response is a `2xx` response, so RichAPI bills the call.	Read the Cache hit field in the row details.
The Recent Calls table shows fewer rows than the range holds.	The dashboard loads at most 500 calls for a range.	Export the range to CSV for the complete set.

What errors does GET /usage return?

Status	Meaning	What to do
`400`	A query parameter is invalid, two window parameters conflict, or `include` holds an unrecognised value.	Correct the parameter that the message names. Send only one of `month`, `months`, `include_previous`, `start_date`.
`400`	The date range exceeds 90 days.	Shorten the range. The response returns `max_range_days`.
`401`	The API key is missing or wrong.	Send a valid key in the `x-api-key` header.

Frequently asked questions

How much is one RichAPI credit worth?

One RichAPI credit is worth $0.02 at list price, on the 1,000 and 5,000 credit packs. Larger packs cost less per credit. The GET /usage response returns this value in the credit_value field, and returns the dollar total in total_cost.

Does RichAPI charge for failed API calls?

No. RichAPI charges a credit only for a 2xx response. A 4xx response and a 5xx response both cost 0 credits, and both appear in the usage log marked Free.

Does a per-result endpoint charge for the results I requested?

No. A per-result endpoint charges for the results the response actually returns. A request for 100 People Search results that returns 73 results costs 73 × 0.1 = 7.3 credits, that is $0.146.

Are asynchronous job status polls billed?

No. A job status poll is recorded with is_status_check set to true and credits set to 0. Poll a job as often as you need.

Does the usage dashboard cover all my API keys?

Yes. The dashboard totals and the history rows cover every API key in the workspace. The CSV export names the key for each call in the api_key_name column.

How far back can I query usage?

A custom date range must not exceed 90 days per request. The same 90-day limit applies to a CSV export. Send several requests to cover a longer period.

Where does the usage export arrive?

RichAPI emails a download link to the account email of the person who requested the export. The link is valid for 7 days and needs no API key.

Next: Reading Your Call Log and Exporting Usage

Tracking Credit Usage and Billing