Two shared pools

Who this is for

Anyone on a team plan who is about to be surprised by a balance. If two people use Boardwalk and one of them uses the API, this page is the one that prevents the surprise.

The rule

A state plan starts the month with 200 Find Contact Info credits and 100,000 export records. A search returns 40 projects; 12 were already delivered and have not changed, so the page uses 28 export records and 0 contact credits. A teammate then asks for contacts on 10 of those projects and 7 return an email or phone: 7 contact credits, and the export counter stays at 28. Downloading the same 40 again, with nothing changed, still returns the file and adds 0 to either counter.

Check the balance before you assume it

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

{
  "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"
  }
}

isTeamPool: true is the field that matters here. It says the numbers you are reading are the team's, not yours, and that a colleague can move them while you are not looking. poolUserId identifies the pool so two seats can tell they are drawing on the same one.

What this means in practice

• Do not build a client that assumes its own balance is the whole story. Read X-Credits-Remaining off each response, or re-read the balance, rather than decrementing a local counter.
• Before a large pull, price it with the free count endpoint. It reads the same pool and reports the same remaining figure.
• A 402 is not a failure of your credentials. Your key is fine; the pool is empty.

Next