Alerts over the API
Save a search, put it on a cadence, and receive only what is new. Records are free; Find Contact Info is billed separately.
Who this is for
Lead-gen and BD teams who want a standing query rather than a polling loop, and builders tracking a competitive set.
The model
An alert is a saved filter set plus a cadence. On each run it evaluates the filters over the window since the last run and produces a delivery — a numbered batch of records with its own charge. You can then read that delivery's records.
Create one
Create a daily alert — configuration is free
curl -X POST 'https://api.boardwalkai.com/api/v1/alerts' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "Utah apartments, 50+ units",
"filters": {
"states": [
"UT"
],
"assetClasses": [
"Apartment Building"
],
"totalUnitCountMin": 50
},
"cadence": {
"frequency": "daily",
"timezone": "America/Denver",
"hourLocal": 7
},
"maxRecordsPerRun": 100,
"notify": {
"email": true,
"emailTo": [
"leads@example.com"
]
}
}'Response · HTTP 201
{
"data": {
"id": "alr_01K1QF3M0000ALERT000001",
"name": "Utah apartments, 50+ units",
"status": "active",
"filters": {
"states": [
"UT"
],
"assetClasses": [
"Apartment Building"
],
"totalUnitCountMin": 50
},
"specificRequirement": null,
"deliveryMode": "all",
"cadence": {
"frequency": "daily",
"timezone": "America/Denver",
"hourLocal": 7,
"backfillDays": 7,
"nextRunAt": "2026-08-03T07:00:00-06:00",
"lastWindowTo": null
},
"budget": {
"maxRecordsPerRun": 100
},
"notify": {
"email": true,
"emailTo": [
"leads@example.com"
],
"webhookUrl": null
},
"share": {
"mode": "private",
"members": []
},
"consecutiveFailures": 0,
"createdAt": "2026-08-02T14:12:00+00:00",
"updatedAt": "2026-08-02T14:12:00+00:00"
},
"meta": {
"creditsUsed": 0
}
}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.
See what it has delivered
What each run delivered, and what it charged
curl 'https://api.boardwalkai.com/api/v1/alerts/alr_01K1QF3M0000ALERT000001/deliveries?limit=2' \
-H 'Authorization: Bearer bwk_live_YOUR_KEY'Response · HTTP 200
{
"data": [
{
"id": "dlv_01K1QF3M0000DELIVERY002",
"alertId": "alr_01K1QF3M0000ALERT000001",
"sequence": 2,
"status": "delivered",
"window": {
"from": "2026-08-01T07:00:00-06:00",
"to": "2026-08-02T07:00:00-06:00"
},
"counts": {
"matched": 9,
"delivered": 9,
"billable": 7
},
"credits": {
"unit": "record",
"rate": 1,
"charged": 7,
"remaining": 286
},
"matchesUrl": "/api/v1/alerts/alr_01K1QF3M0000ALERT000001/matches?deliveryId=dlv_01K1QF3M0000DELIVERY002"
}
],
"meta": {
"limit": 2,
"offset": 0,
"creditsUsed": 0
}
}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.
Read counts beside credits: nine records matched, nine were delivered, seven were billable. The other two were records this pool already held, unchanged. The matchesUrl fetches the records themselves.
Cadence and budget
| Setting | What it does |
|---|---|
cadence.frequency | How often the alert runs. manual, daily, weekly or monthly. |
cadence.timezone / hourLocal | When in the customer's day it runs, so a "daily" alert lands before the standup rather than at 3am. |
cadence.backfillDays | How far back the first run looks. Useful when you want the standing query to start with recent history. |
maxRecordsPerRun | A hard ceiling on how many records one run can deliver — and therefore on what one run can cost. Also accepted nested as budget.maxRecordsPerRun. |
notify.email / emailTo | Who gets told. The email is a notification, not the payload; the records come from the API. |
Use maxRecordsPerRun as a spend control. It is the difference between a daily alert with a predictable ceiling and one that can empty a pool the week a large city publishes a backlog.
Test it before you trust it
POST /alerts/{alertId}/preview tells you how many records a rule would deliver and what that would cost, without delivering them. It is free. POST /alerts/{alertId}/run requires an `Idempotency-Key` header — without one it is refused with 400 invalid_request naming that header and nothing runs. It triggers a real run — that one delivers and bills, and is capped at 3 manual runs per alert per calendar day (the service clock): past that it refuses with 429 manual_runs_exhausted and a Retry-After pointing at the next day's midnight. Replaying an Idempotency-Key that already ran returns the original delivery and does not spend an attempt; scheduled cadence runs are never limited by this.
Next
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.