Alerts over the API

Save a search, put it on a cadence, and receive only what is new — configuration free, delivery billed per record.

Lead generation and business developmentHomebuilders and developers

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

bash

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

json

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

Credit costFree — 0 creditsFree.

See what it has delivered

What each run delivered, and what it charged

bash

curl 'https://api.boardwalkai.com/api/v1/alerts/alr_01K1QF3M0000ALERT000001/deliveries?limit=2' \
  -H 'Authorization: Bearer bwk_live_YOUR_KEY'

Response · HTTP 200

json

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

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.

Credit costFree — 0 creditsFree. The delivery history and what each run charged.

Credit cost1 credit per record deliveredRecords already delivered and billed by a scheduled run are re-readable here without a second charge; anything new to you bills once.

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.
`budget.maxRecordsPerRun`	A hard ceiling on how many records one run can deliver — and therefore on what one run can cost.
`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 triggers a real run — that one delivers and bills, and is capped per alert per day.

Credit costFree — 0 creditsFree. Preview returns how many records a rule would deliver and what that would cost, not the records themselves.

Credit cost1 credit per record deliveredA manual run is a real delivery: records new to you bill at the standard rate. Runs are capped per alert per day.

Alerts reference Never pay twice for the same record

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.

Create a free account Get your API key Plans and pricing