Keeping an agent inside its budget

The failure this prevents

A user asks an agent for "every apartment project in the thousand largest cities". A naive agent turns that into a thousand search calls. On County, State, and National those searches are free: the waste is time and rate-limit slots, not credits. On API Only and the trial, the route never overspends and never trims: a request delivers at most one page, billed whole or refused whole, so a single JSON search can never cost more than its limit (at most 100 credits), and the first page the balance cannot pay for gets a 402 rather than a surprise invoice. But a thousand 402s is still a bad afternoon for everyone.

The pattern

1. 1The agent's first call for any new task is GET /projects/count. It is free, it works at a zero balance, and it returns everything needed to decide: matchCount, billable.credits, affordability.affordable, and affordability.maxAffordableRecords.
2. 2If affordable is false, the whole remaining set does not fit the balance, not that the next call fails. The agent decides on purpose: narrow and count again, or page from the top and stop once maxAffordableRecords records are in hand. Counting is free; a blind attempt is a rate-limit slot.
3. 3When the agent does spend, it reads X-Credits-Remaining off the response rather than maintaining its own counter, because a teammate or another agent may be spending the same pool.
4. 4On a 402, the agent reads error.details.quote.affordableRecordCount (the limit to retry with) and follows quote.countUrl, a free URL that re-prices the exact filter set that just failed, instead of retrying blindly. A 402 with no quote is credits_exhausted: the balance cannot buy even one record, and the only moves are stopping or topping up.
5. 5For questions about shape rather than records, the agent uses the analytics plane, which is free.

curl 'https://api.boardwalkai.com/api/v1/projects/count?states=UT&assetClasses=Apartment%20Building&dateRange=all' \
  -H 'Authorization: Bearer bwk_live_YOUR_KEY'

{
  "data": {
    "matchCount": 5000,
    "matchCountIsExact": true,
    "matchCountBasis": "enumerated",
    "countedAs": "distinct_projects",
    "collapseApplied": true,
    "duplicatesCollapsed": 0,
    "scanCeiling": 10000,
    "billable": {
      "records": 5000,
      "credits": 0,
      "creditRate": 0,
      "isUpperBound": true,
      "nonBillable": {
        "alreadyDeliveredUnchanged": 0,
        "ledgerApplied": true
      }
    },
    "affordability": {
      "affordable": true,
      "blockReason": null,
      "shortfallCredits": 0,
      "maxAffordableRecords": 9223372036854776000,
      "boundBy": "period_balance",
      "unlimited": false
    },
    "ordering": {
      "sort": "meetingDate",
      "order": "desc",
      "tiebreak": null,
      "meaning": "Most recent meeting evidence first — the date of the meeting the record was extracted from, not when Boardwalk ingested it and not when the project was created."
    },
    "truncation": {
      "policy": "refuse",
      "wouldTruncate": false,
      "deliverableRecords": null,
      "explanation": "The whole match set fits inside the remaining balance: page through the metered route and every page will be delivered in full until the set is exhausted."
    }
  },
  "meta": {
    "schemaVersion": "2026-09-16",
    "representation": "standard",
    "deliveryMode": "all",
    "credits": {
      "limit": 500,
      "used": 0,
      "remaining": 500,
      "charged": 0,
      "periodStart": "2026-08-01",
      "periodEnd": "2026-08-31",
      "isTeamPool": true
    },
    "appliedFilters": {
      "states": [
        1
      ],
      "assetClasses": [
        "Apartment Building"
      ],
      "dateRange": "all"
    },
    "appliedDefaults": [
      "taxonomyMatchMode=primary_only",
      "includeGovernmentDecisions=false",
      "leadTypes=private",
      "sort=meetingDate",
      "order=desc"
    ],
    "resolvedFrom": {
      "states": [
        {
          "input": "UT",
          "id": 1
        }
      ]
    },
    "warnings": []
  },
  "links": {
    "self": "https://api.boardwalkai.com/api/v1/projects/count?states=UT&assetClasses=Apartment%20Building&dateRange=all",
    "search": "https://api.boardwalkai.com/api/v1/projects/search?states=UT&assetClasses=Apartment%20Building&dateRange=all",
    "docs": "https://boardwalkai.com/docs/api/budgets/"
  }
}

Rules of thumb for tool descriptions

• Tell the model that counting is free, and that on County, State, and National each new or changed record counts toward 100,000 export records a month. Find Contact Info is a separate credit. On API Only and the trial, searching costs 1 credit per new record.
• Give the model representation: "compact" as its default. It is the same price and 21 fields against standard's 71, which matters for context, not for cost.
• Never let a model choose a limit above what one task needs. The page ceiling is 100 records, and limit is the per-request exposure cap: a page is billed whole or refused whole, so one search can never spend more than limit credits. A loop over pages should be a deliberate decision, not a default.
• Surface meta.warnings to the model. They disclose applied defaults, trial truncation, and other conditions that can change how a result should be read.

Costs at a glance

Next