Skip to main content

The credit model

The authoritative rate card: 1 credit per project when contact info is delivered, what is free, and what never bills twice.

What that covers

RuleDetail
Free only inside your plan geographyA State plan searches and exports that state. A county plan those counties. National and API Only are nationwide. GET /locations/states marks each state entitled: true or false. A filter outside that set is 403 geographic_access_denied.
Representation does not change the priceSearching in compact, standard or full is free. Credits only spend on Find Contact Info.
AI search is freeA natural-language search costs the same as a structured filter: nothing. Candidates we reviewed and rejected also cost nothing.
Contact delivery is the only charge1 credit per project the first time this account receives email or phone. A project already unlocked for this pool is free to re-read. Empty lookups cost nothing.
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 Find Contact Info charges once for that project.
Already-unlocked projects are freeA project this pool has already unlocked is free to re-read, re-export, or enrich again.
One poolCSV Find Contact Info, API enrichments and MCP create_enrichment all spend the same monthly balance.

Every endpoint, and what it costs

Billable — 1 credit per project unlocked

MethodPathCostNotes
POST/enrichments1 credit / project unlockedCounty, State, and National: 1 credit per project the first time this account receives email or phone for it. Standalone API Only: included on records this pool has already purchased — unpurchased ids are skipped as notPurchased. A live free trial spends the separate 5-lookup grant (not the 50 record-export credits). Empty lookups cost nothing. Credits are charged when the job delivers contacts, not when it is queued.

Free — 0 credits

MethodPathCostNotes
GET/account/creditsFreeFree. Your balance, your plan, your rate limit and your enrichment allowance.
GET/account/preferencesFreeFree. The account's saved search preferences (types, geography, website).
PATCH/account/preferencesFreeFree. Update the account's saved search preferences.
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.
GET/alerts/{alertId}/matchesFreeFree, every time. Omit deliveryId to read every match except dismissed (pending review included) — the same set the website table shows. Passing a deliveryId re-reads a past API run. Neither path charges.
POST, GET/alerts/{alertId}/previewFreeFree. Preview returns how many records a rule would deliver and what that would cost, not the records themselves.
POST/alerts/{alertId}/runFreeFree. A manual run delivers matching records at no credit cost. Finding contact info on those records is a separate enrichment.
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/documents/{id}FreeCounty, State, and National: free. Standalone API Only and the free trial: 1 credit per source document the first time this pool receives it.
GET/enrichments/{id}FreeFree to poll. Progress counts for a submitted enrichment job.
POST/exportsFreeFree to queue a product CSV. Pass alertId, listId, or projectIds to export a saved set (optional extra filters stay inside those ids). Omit all three and the body is a new search. Find Contact Info on those rows is 1 credit per project the first time this account receives email or phone for it.
GET/exportsFreeFree. Lists export jobs for your team (including jobs queued with POST /exports or format=csv on search).
GET/exports/{id}FreeFree. Poll job status until ready.
GET/exports/{id}/downloadFreeFree re-download of a ready product-core CSV. Rows are free to queue. Find Contact Info on those rows, if you asked for it, was 1 credit per project unlocked.
GET/healthFreeFree and unauthenticated. A liveness probe, not part of the record contract: its response shape carries no schema guarantee and can change without a schema-version bump, which is why it is deliberately absent from the OpenAPI document. Do not generate a client against it or parse its body.
GET/listsFreeFree. Every list your membership resolves — your own and the ones shared with you.
POST/listsFreeFree. Creates a named membership list (the "new list" option on save).
GET/lists/{listId}FreeFree. One list's configuration and share state, plus results.billable.credits — what a full /results pull would charge right now. This is the free preflight for /results.
POST/lists/{listId}/projectsFreeFree. Adds project ids to a membership-backed list. Idempotent per id.
DELETE/lists/{listId}/projects/{projectId}FreeFree. Removes a project from a membership-backed list.
GET/lists/{listId}/resultsFreeCounty, State, and National: free. Standalone API Only and the free trial: 1 credit per delivered record that is new to this pool or changed since last delivery; unchanged owned records are free. Alert companions return the same match set as the alert (every match except dismissed, pending review included). Extra search filters apply only inside those existing ids. Filter and polygon lists return stored criteria plus a search link.
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.
POST/projects/ai-searchFreeNot part of the public API — you cannot call this with an API key. Any bwk_live_/csk_ key is refused with 400 invalid_request (error.param: "endpoint", details.asyncEndpoint) before anything is parsed; use POST /projects/ai-search/jobs instead. On the session-authenticated web product this path is free, like structured search.
POST/projects/ai-search/jobsFreeCounty, State, and National: free. Standalone API Only and the free trial: credits are reserved at 1 per requested record and settled against confirmed matches. Finding contact info on those records is a separate enrichment job (included on API Only after the record is purchased).
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.
DELETE/projects/ai-search/jobs/{id}FreeCancelling is free and gives credits back, never takes them: a queued job refunds its full reservation immediately; a running job settles at the next batch boundary, charging only confirmed records and refunding the rest.
GET/projects/countFreeFree, always, including when your balance is zero. How many projects match. On API Only and the trial it also prices the set; on County, State, and National, search is free.
GET/projects/searchFreeCounty, State, and National: free. Standalone API Only and the free trial: 1 credit per delivered record that is new to this pool or changed since last delivery; unchanged owned records are free. format=csv queues the full filter match and returns HTTP 202 with poll/download URLs. Find Contact Info is billed separately on County/State/National, and included on API Only records already purchased.
GET/projects/syncFreeCounty, State, and National: free. Standalone API Only and the free trial: 1 credit per new or changed record; unchanged owned records bill 0.
GET/projects/{id}FreeCounty, State, and National: free. Standalone API Only and the free trial: 1 credit the first time this pool receives the record. Email, phone, and LinkedIn stay withheld until Find Contact Info has unlocked the project (included on API Only after the record is purchased).
GET/reference/decision-bodiesFreeFree. Canonical values accepted by the decisionBodies filter.
GET/reference/owner-typesFreeFree. The owner-type vocabulary used by alert criteria and CSV output. Not accepted as a /projects/search filter — the ownerTypes filter was withdrawn on 2026-08-27.
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 Building Type 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, project types, 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. You can always see how many projects match before you page them or spend a Find Contact Info credit.

Allowances

On County, State, and National, the monthly allowance is Find Contact Info credits (50 per county, 300 per state, 2,500 nationwide). Searching records does not spend them. API Only includes 500 record credits per month. Unused credits do not roll over. See plans and pricing for plan prices; 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, 50 record-export credits (search, CSV, MCP), and 5 Find Contact Info lookups. Counting, taxonomy, location lookups and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.

Create a free accountSettings → APIConnect your AIPlans and pricing