Skip to main content

The credit model

The authoritative rate card: one credit per record delivered, what is free, and what never bills twice.

What that covers

RuleDetail
Representation does not change the priceA record costs the same in compact, standard and full. You are billed for the record, not the bytes.
AI search is the same rateA 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 includedA record costs 1 credit whether or not you asked for contacts, and whether or not we found any.
Errors are freeNo 4xx or 5xx response is ever charged. A refused request leaves your balance exactly where it was.
Zero results are freeA query that matches nothing costs nothing.
Duplicates are collapsed before billingTwo filings for one development are merged into one record and charged once.
Unchanged re-delivery is freeA record this pool already holds, which has not changed since, is delivered again without a charge.
One poolCSV 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

MethodPathCostNotes
GET/alerts/{alertId}/matches1 credit / recordRecords already delivered and unchanged since a scheduled run are re-readable here without a second charge; anything new or changed bills once.
POST/alerts/{alertId}/run1 credit / recordA manual run is a real delivery: records new to you or changed since their last delivery bill at the standard rate. Runs are capped per alert per day.
GET/documents/{id}1 credit / recordOne source document, one credit.
POST/projects/ai-search1 credit / recordThe same rate as a structured search. You pay for confirmed matches that are new to you or changed since their last delivery; rejected candidates and unchanged re-deliveries are free.
POST/projects/ai-search/jobs1 credit / recordCredits are reserved up front against the requested limit and settled down to confirmed records that are new to you or changed since their last delivery. Unused reservation, including unchanged re-deliveries, is refunded.
GET/projects/search1 credit / recordJSON pages: charged for records actually delivered after collapse, with unchanged re-delivery free. Zero results cost nothing. format=csv does not use this search charge — it reserves product export credits (1 per core CSV row) and returns HTTP 202 with poll/download URLs.
GET/projects/sync1 credit / recordOnly 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 / recordOne credit when the record is new to you or changed since your last delivery; an unchanged re-read is free, just like the same record inside a search page.

Free — 0 credits

MethodPathCostNotes
GET/account/creditsFreeFree. Your balance, your plan and your rate limit.
GET/alertsFreeFree. Configuring alerts never costs credits; only delivered records do.
POST/alertsFreeFree.
GET/alerts/{alertId}FreeFree.
PATCH/alerts/{alertId}FreeFree.
DELETE/alerts/{alertId}FreeFree.
GET/alerts/{alertId}/deliveriesFreeFree. The delivery history and what each run charged.
GET/alerts/{alertId}/deliveries/{deliveryId}FreeFree.
POST/alerts/{alertId}/dismissals/{projectId}FreeFree. Dismissing a match stops it being re-offered.
DELETE/alerts/{alertId}/dismissals/{projectId}FreeFree.
POST, GET/alerts/{alertId}/previewFreeFree. Preview returns how many records a rule would deliver and what that would cost, not the records themselves.
POST/analytics/aggregateFreeFree. POST only (GET returns 404/405). Returns counts and group keys, never a project id, name, address, contact or document.
GET/analytics/datasetsFreeFree. GET only. What the analytics plane can and cannot answer, self-described.
POST/analytics/rankingsFreeFree. POST only (GET returns 405). Same small-group suppression floor as /aggregate.
GET/exportsFreeFree. Lists export jobs for your team (including jobs queued with format=csv on search). Credits were reserved when the job was created.
GET/exports/{id}FreeFree. Poll job status until ready.
GET/exports/{id}/downloadFreeFree re-download of a ready product-core CSV. Creating the job reserved export credits (1 per row) when you queued it.
GET/healthFreeFree and unauthenticated.
GET/locations/cities/{id}FreeFree.
GET/locations/counties/{id}FreeFree.
GET/locations/statesFreeFree. Resolve the ids you filter with.
GET/locations/states/{id}FreeFree.
GET/locations/states/{id}/countiesFreeFree.
GET/locations/states/{stateId}/counties/{countyId}/citiesFreeFree.
GET/projects/ai-search/jobs/{id}FreePolling is free. The records the job delivers were charged when the job settled, not when you read them.
GET/projects/countFreeFree, always, including when your balance is zero. This is the endpoint that tells you what a query would cost before you buy it.
GET/reference/decision-bodiesFreeFree. Canonical values accepted by the decisionBodies filter.
GET/reference/owner-typesFreeFree. Owner-type values accepted by ownerTypes filters.
GET/reference/request-typesFreeFree. Canonical values accepted by the requestTypes filter.
GET/reference/statusesFreeFree. Canonical status filter tokens plus display aliases (e.g. scheduled).
GET/taxonomyFreeFree. The complete land use taxonomy tree.
GET/taxonomy/action-categoriesFreeFree.
GET/taxonomy/action-typesFreeFree.
GET/taxonomy/asset-classesFreeFree.
GET/taxonomy/project-typesFreeFree.
GET/taxonomy/subtypesFreeFree.

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

bash
curl 'https://api.boardwalkai.com/api/v1/account/credits' \
  -H 'Authorization: Bearer bwk_live_YOUR_KEY'

Response · HTTP 200

json
{
  "data": {
    "plan": "single_state",
    "planDisplayName": "State",
    "creditsLimit": 500,
    "creditsUsed": 200,
    "creditsRemaining": 300,
    "periodStart": "2026-08-01",
    "periodEnd": "2026-08-31",
    "resetsAt": "2026-09-01T00:00:00+00:00",
    "rateLimit": 60,
    "rateLimitPer": "minute",
    "isTeamPool": true,
    "poolUserId": 8814
  },
  "meta": {
    "requestId": "req_01K1QF3M0000EXAMPLE0001"
  }
}

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, taxonomy, location lookups and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.

Create a free accountGet your API keyPlans and pricing