The credit model
The authoritative rate card: one credit per record delivered, what is free, and what never bills twice.
What that covers
| Rule | Detail |
|---|---|
| Representation does not change the price | A record costs the same in compact, standard and full. You are billed for the record, not the bytes. |
| AI search is the same rate | A record confirmed by a natural-language search costs the same as one matched by a structured filter. Candidates we reviewed and rejected cost you nothing. |
| Contact enrichment is included | A record costs 1 credit whether or not you asked for contacts, and whether or not we found any. |
| Errors are free | No 4xx or 5xx response is ever charged. A refused request leaves your balance exactly where it was. |
| Zero results are free | A query that matches nothing costs nothing. |
| Duplicates are collapsed before billing | Two filings for one development are merged into one record and charged once. |
| Unchanged re-delivery is free | A record this pool already holds, which has not changed since, is delivered again without a charge. |
| One pool | CSV exports, API calls and MCP tool calls all spend the same monthly balance. |
Every endpoint, and what it costs
Billable — 1 credit per record delivered
| Method | Path | Cost | Notes |
|---|---|---|---|
| GET | /alerts/{alertId}/matches | 1 credit / record | Records already delivered and billed by a scheduled run are re-readable here without a second charge; anything new to you bills once. |
| POST | /alerts/{alertId}/run | 1 credit / record | A manual run is a real delivery: records new to you bill at the standard rate. Runs are capped per alert per day. |
| GET | /documents/{id} | 1 credit / record | One source document, one credit. |
| POST | /projects/ai-search | 1 credit / record | The same rate as a structured search. You pay for confirmed matches that are delivered, not for the candidates that were reviewed and rejected. |
| POST | /projects/ai-search/jobs | 1 credit / record | Credits are reserved up front against the requested limit and settled down to the number of confirmed records actually delivered. |
| GET | /projects/search | 1 credit / record | Charged for the records actually delivered on the page, after duplicate projects are collapsed and after records you already hold unchanged are excluded. Zero results cost nothing. |
| GET | /projects/sync | 1 credit / record | Only records that are new to you, or that changed since you last received them, are billable. A sync page that returns nothing but unchanged records is free. |
| GET | /projects/{id} | 1 credit / record | One record, one credit — the same rate as a record inside a search page. |
Free — 0 credits
| Method | Path | Cost | Notes |
|---|---|---|---|
| GET | /account/credits | Free | Free. Your balance, your plan and your rate limit. |
| GET | /alerts | Free | Free. Configuring alerts never costs credits; only delivered records do. |
| POST | /alerts | Free | Free. |
| GET | /alerts/{alertId} | Free | Free. |
| PATCH | /alerts/{alertId} | Free | Free. |
| DELETE | /alerts/{alertId} | Free | Free. |
| GET | /alerts/{alertId}/deliveries | Free | Free. The delivery history and what each run charged. |
| GET | /alerts/{alertId}/deliveries/{deliveryId} | Free | Free. |
| POST | /alerts/{alertId}/dismissals/{projectId} | Free | Free. Dismissing a match stops it being re-offered. |
| DELETE | /alerts/{alertId}/dismissals/{projectId} | Free | Free. |
| POST, GET | /alerts/{alertId}/preview | Free | Free. Preview returns how many records a rule would deliver and what that would cost, not the records themselves. |
| POST | /analytics/aggregate | Free | Free. Returns counts and group keys, never a project id, name, address, contact or document. |
| GET | /analytics/datasets | Free | Free. What the analytics plane can and cannot answer, self-described. |
| POST | /analytics/rankings | Free | Free, and subject to the same small-group suppression floor as /aggregate. |
| GET | /health | Free | Free and unauthenticated. |
| GET | /locations/cities/{id} | Free | Free. |
| GET | /locations/counties/{id} | Free | Free. |
| GET | /locations/states | Free | Free. Resolve the ids you filter with. |
| GET | /locations/states/{id} | Free | Free. |
| GET | /locations/states/{id}/counties | Free | Free. |
| GET | /locations/states/{stateId}/counties/{countyId}/cities | Free | Free. |
| GET | /projects/ai-search/jobs/{id} | Free | Polling is free. The records the job delivers were charged when the job settled, not when you read them. |
| GET | /projects/count | Free | Free, always, including when your balance is zero. This is the endpoint that tells you what a query would cost before you buy it. |
| GET | /taxonomy | Free | Free. The complete land use taxonomy tree. |
| GET | /taxonomy/action-categories | Free | Free. |
| GET | /taxonomy/action-types | Free | Free. |
| GET | /taxonomy/asset-classes | Free | Free. |
| GET | /taxonomy/project-types | Free | Free. |
| GET | /taxonomy/subtypes | Free | Free. |
The free plane is not a teaser
Counting, the location tree, the taxonomy, alert configuration and the entire analytics surface are free permanently, on paid and trial keys alike, and GET /projects/count answers even when your balance is zero. A metered API that will not tell you what something costs until you have paid for it is a worse product, so we do not ship one.
Allowances
How many credits your plan includes each month depends on the geography you bought. Credits are shared across every export surface, and unused credits do not roll over. See plans and pricing for what a plan costs; this page is about what a credit buys.
Reading your balance
Read the shared balance
curl 'https://api.boardwalkai.com/api/v1/account/credits' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY'Response · HTTP 200
{
"data": {
"plan": "state",
"planDisplayName": "State",
"creditsLimit": 500,
"creditsUsed": 200,
"creditsRemaining": 300,
"periodStart": "2026-08-01",
"periodEnd": "2026-08-31",
"rateLimit": 60,
"rateLimitPer": "minute",
"isTeamPool": true,
"poolUserId": 8814
}
}The response shape on this page is the one the endpoint builds — the keys, their nesting and their types are asserted against the shipping code by a test. The numbers inside it are the scenario being walked through, not a measurement of the corpus.
Metered responses also carry X-Credits-Remaining, and meta.creditsUsed / meta.creditsRemaining on the body. Read one of those rather than keeping a local counter — the pool is shared, and someone else may be spending it.
Ready to make a call?
A free Boardwalk trial includes API access and a sandbox key. Counting, filtering, the location tree and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.