Idempotency
Retry a billable request safely: the same key replays the same result instead of charging twice.
Send an Idempotency-Key header on any billable request. If the request is repeated with the same key — because your process crashed, your load balancer retried, or your job runner is at-least-once — we replay the original result and charge nothing the second time.
curl -X POST 'https://api.boardwalkai.com/api/v1/projects/ai-search/jobs' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY' \
-H 'Idempotency-Key: nightly-utah-pull-2026-08-02' \
-H 'Content-Type: application/json' \
-d '{"query":"projects with unresolved traffic concerns","states":["UT"],"limit":50}'The rules
- Keys are scoped to the credit pool, so a teammate cannot collide with your key by accident and cannot replay your result either.
- Reusing a key with a different request body or filter set is
409 idempotency_key_reuse. Replaying is safe; changing the request under the key is not. - Reusing a key while the first request is still running is
409 idempotency_in_flightwith aRetry-After. Do not fan out the same key in parallel — the whole point is that only one of them charges. - Accepted key characters are
A-Z a-z 0-9 _ . : -, up to 255 — the same grammar asX-Request-Id, so there is one rule to learn.
Where the key is required
On most billable requests the key is optional and honoured. Two POSTs refuse to run without one — 400 invalid_request with error.param: "Idempotency-Key" — because each creates work whose key-less retry would be indistinguishable from a second submission:
| Route | What a replay returns |
|---|---|
POST /enrichments | The job the key already created: the same enrichmentJobId and the original accepted/skipped disposition, with status read live — by the time a retry lands the job may already be running or completed. No additional allowance is consumed. |
POST /alerts/{alertId}/run | The original run's delivery envelope with meta.creditsUsed: 0. A replay never re-runs, never re-bills, and never spends a manual-run attempt. |
Where it matters most
On POST /projects/ai-search/jobs. On County, State, and National the job is free. On API Only and the free trial, that route reserves credits up front for the effective limit (default 10, max 100). On completion it charges 1 credit per delivered record and refunds the unused portion. Failures refund the full reservation. Charge-exempt / unlimited pools may show creditsReserved: 0; always trust meta.creditsUsed on completed responses for what was actually spent. Two identical submits without an idempotency key can hold the whole pool while both run — with a key, the retry replays the same job instead of queueing a second one.
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.