Usage and units
What a run costs, when it is charged, and how to read your usage.
Usage is counted in units. A unit is not money: prices per unit have not been announced. What is fixed today is how many units a run costs and when it is charged.
The charging rule#
A run is charged once, when it ends, and only if it ended ok or partial.
| The run ended | Units charged |
|---|---|
| ok | Charged |
| partial | Charged |
| failed | 0 |
| unsupported | 0 |
| cancelled | 0 |
How many units a charged run costs depends on the scraper's billing unit:
| Billing unit | A charged run costs | Meaning |
|---|---|---|
request | 1 unit | One unit for the run, however many records it returned. |
record | record_count units | One unit for each record the run returned. |
Each scraper states its billing unit on its page and in GET /v1/scrapers/{id}.
Some are billed per request and some per record: ats.board per request, linkedin.jobs_search per record.
The run itself shows what it cost, in units. It is 0 until the run ends. This ats.board run is billed per
request, so its records cost 1 unit together:
{
"id": "run_6cce2b12aaf37a10b5e1b885",
"scraper_id": "ats.board",
"scraper_version": 1,
"status": "ok",
"reason": null,
"input": {
"board_url": "https://boards.greenhouse.io/acme"
},
"record_count": 19,
"units": 1,
"diagnostics": {
"requests": 1,
"bytes": 232779,
"wall_ms": 565,
"facts": {
"careers_url": "https://boards.greenhouse.io/acme",
"discovery": "supplied",
"ats": "greenhouse",
"pages_read": 1,
"renders_refused": 0
}
},
"created_at": "2026-11-16T20:27:29.009834Z",
"started_at": "2026-11-16T20:27:29.013803Z",
"finished_at": "2026-11-16T20:27:29.582787Z"
}What that means in practice#
| Run | Units |
|---|---|
careers.company ends ok with 35 records | 1 |
careers.company ends ok with 0 records — the site was read and lists no openings | 1 |
careers.company ends partial with 12 records, reason render_required | 1 |
careers.company ends partial with 8 records, reason unverified_page_extraction | 1 |
ats.board ends unsupported, reason render_required | 0 |
careers.company ends failed, reason no_postings_recognised | 0 |
linkedin.jobs_search ends ok with 25 records | 25 |
web.fetch ends ok with the site's own 404 page | 1 |
web.fetch ends failed, reason blocked | 0 |
careers.company ends failed, reason no_careers_page | 0 |
A run you cancel, which ends cancelled — also when it had already found records | 0 |
A run you cancel that was already finishing and ends ok | 1 |
A request refused with an error (invalid_input, quota_exceeded, …) — no run is created | 0 |
Two of these deserve a second look:
- An
okrun with no records is charged. The work was done and the answer — "nothing there" — is the answer. - A
partialrun is charged in full. You received records. For a scraper billed perrecordyou pay for the records you received; for one billed perrequestyou pay the one unit.
You are never charged for a site we could not read or a page we cannot handle.
Reading runs, records, the catalogue or your usage costs nothing.
The allowance#
Each account has an allowance of units per calendar month, counted in UTC: it starts again on the 1st. The free allowance is 1,000 units a month.
When the units charged this month reach the allowance, starting a run is refused with 402 quota_exceeded, and
no run is created. The error says where you stand:
{
"error": {
"code": "quota_exceeded",
"message": "This month's units are used up.",
"details": {
"used_units": 1,
"allowance_units": 1
}
}
}The check is made when a run starts, so a run that was accepted is never stopped for the allowance: the run that
uses the last unit completes, and one billed per record can take the month's total past the allowance.
Your account's own allowance is the allowance_units number in the usage report below.
Read your usage#
GET /v1/usage reports the units charged in a period.
curl "https://api.enrichednow.com/v1/usage?from=2026-11-01&to=2026-11-30&group_by=scraper" \
-H "Authorization: Bearer $ENRICHEDNOW_API_KEY"| Parameter | Meaning |
|---|---|
from, to | The first and the last day of the period, both included, as UTC dates (2026-11-01). Default: from the 1st of the month to falls in, to today. A period is at most 366 days. |
group_by | day (the default) for one row per day, or scraper for one row per scraper. |
By scraper, there is a row only for a scraper that was charged in the period, the one with the most units first:
{
"period": {
"from": "2026-11-01",
"to": "2026-11-16"
},
"total_units": 1,
"allowance_units": 1000,
"rows": [
{
"key": "ats.board",
"units": 1,
"runs": 1
}
]
}By day, every day of the period has a row, also a day with no usage:
{
"period": {
"from": "2026-11-16",
"to": "2026-11-16"
},
"total_units": 1,
"allowance_units": 1000,
"rows": [
{
"key": "2026-11-16",
"units": 1,
"runs": 1
}
]
}| Field | Meaning |
|---|---|
period | The period the report covers: from and to. |
total_units | Units charged in the period. |
allowance_units | Your account's allowance for a calendar month — whatever the period asked for. |
rows[].key | The day (2026-11-16) or the scraper id, depending on group_by. |
rows[].units | Units charged for that day or scraper. |
rows[].runs | The number of charged runs — those that ended ok or partial — for that day or scraper. Runs that cost nothing are not counted. |
The console shows the same numbers on its usage page.
How usage is recorded#
Each charge is written once, to a ledger that is only ever added to: a charge is never edited or removed afterwards.