Billing & Credits
Credits are charged after each query based on two factors: the number of locations returned and the response format. If a brand is not found (404), no credits are charged.
Free trial
Every new account starts on a trial key, created automatically when you sign up.
| Limit | Default |
|---|---|
| Duration | 5 days from signup |
| Credits | 50 |
| Max locations per request | 50 |
The trial key is a normal bm_live_* key — use it exactly like any paid key. Calls that would return more than 50 locations are truncated to 50, with these response headers so your client knows there's more data behind an upgrade:
| Header | Description |
|---|---|
X-Trial-Cap-Applied | Present and true when the response was truncated |
X-Total-Available | Total locations the unfiltered query would have returned |
When the trial ends — whichever comes first: 5 days, 50 credits used, or you hit 0 credits — the key returns 402 TRIAL_EXPIRED (or TRIAL_EXHAUSTED) on every call with an upgrade_url pointing to /billing. Pick any tier below to convert.
One trial per account, ever. The trial key stays visible in your dashboard for 30 days after expiry so you can copy it into the same place when you upgrade.
Base tier — by location count
| Locations Returned | Base Credits |
|---|---|
| 1–500 | 1 |
| 501–2,000 | 2 |
| 2,001–5,000 | 3 |
| 5,001–10,000 | 5 |
| 10,000+ | 8 |
Format multiplier
Map rendering uses Puppeteer and requires significantly more compute than data-only queries.
| Format | Type | Multiplier |
|---|---|---|
json | Data only | 1x |
csv | Data only | 1x |
geojson | Data only | 1x |
png | Map render | 2x |
jpeg | Map render | 2x |
Total credits = base tier x format multiplier.
Cost examples
| Query | Locations | Format | Total Credits |
|---|---|---|---|
| Sweetgreen, all US | 152 | json | 1 (1 x 1) |
| Sweetgreen, all US | 152 | png | 2 (1 x 2) |
| McDonald's, all US | 4,190 | csv | 3 (3 x 1) |
| McDonald's, all US | 4,190 | png | 6 (3 x 2) |
| Starbucks, all US | 7,609 | jpeg | 10 (5 x 2) |
Reduce your cost by adding filters. Querying "Starbucks" with state="CA" returns ~1,000 locations (2 credits as JSON) instead of 7,609 nationwide (5 credits).
Billing response headers
Every response includes billing headers so you can track usage programmatically:
| Header | Description |
|---|---|
X-Credits-Charged | Number of credits deducted for this request |
X-Credits-Remaining | Credits remaining on your API key |
X-Credits-Low | Present and true when balance drops below 50 |
X-Credits-Charged: 3
X-Credits-Remaining: 997
X-Credits-Low: true // only when balance < 50Brand not found (404)? You are never charged. Credits are only deducted when locations are successfully returned.