Alerts
Standing searches on a cadence. Configuration is free; delivered records bill at the standard rate.
An alert is a saved filter set plus a cadence. Each run produces a numbered delivery — a batch of records with its own charge — which you can then read.
The endpoints
| Endpoint | What it does |
|---|---|
POST /alerts | Create a rule. Free. |
GET /alerts | List your rules and how many you have active. Free. |
GET /alerts/{id} | Read one rule. Free. |
PATCH /alerts/{id} | Change filters, cadence, budget or recipients. Free. |
DELETE /alerts/{id} | Remove a rule. Free. |
POST /alerts/{id}/preview | How many records would this deliver, and what would it cost? Free, and delivers nothing. |
POST /alerts/{id}/run | Trigger a real run now. Billed like any delivery, and capped per day. |
GET /alerts/{id}/deliveries | The run history with per-run counts and charges. Free. |
GET /alerts/{id}/matches | The records from a delivery. Records already billed by the run are re-readable free. |
POST|DELETE /alerts/{id}/dismissals/{projectId} | Stop a match being re-offered. Free. |
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
},
"budget": {
"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
},
"deliveryMode": "new",
"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
},
"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.
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.
Email is a notification, not the payload
notify.email tells people that a delivery happened. The records come from the API. Building against the email would mean parsing a message we reserve the right to redesign.
Ready to make a call?
A free Boardwalk trial includes API access and a sandbox key. Counting, filtering, the location tree and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.