Credits & Billing
Understand how API credit consumption works, which operations cost credits, and how to monitor your balance.
Credit model
DealSurface uses a monthly credit allowance system. Most read operations are free; credits are consumed only for operations that involve generating new data (DealMap generation, outreach generation).
Operation costs
| Endpoint | Credits | When charged |
|---|---|---|
| GET /products, /prospects, /excerpts | Free | Never |
| GET /dealmap, PATCH /dealmap/* | Free | Never |
| POST /dealmap/generate | 0 or 10 | Only when fresh org-chart data is fetched. Cached org data is reused for free. |
| POST /outreach | 1 | On every successful (200) response. |
DealMap generation billing
POST /dealmap/generate reuses cached org-chart data when available. Credits (10) are only charged when fresh org-chart data is fetched (indicated by generation_source: "org_fresh"). Use the force_refresh parameter with caution, as it forces a fresh org-chart fetch and always charges credits.
Monthly allowances
| Plan | Monthly credits |
|---|---|
| Trial | 50 |
| Professional | 1,000 |
| Enterprise | Custom |
Credit response headers
Billable endpoints include credit information in response headers:
| Header | Description |
|---|---|
X-Credits-Operation | The billing operation name. |
X-Credits-Remaining | Credits remaining this period. |
X-Credits-Period-End | ISO 8601 timestamp when allowance resets. |
X-Credits-Charged | Number of credits deducted (only if charged). |
X-Credits-Operation: prospect_outreach
X-Credits-Remaining: 187
X-Credits-Period-End: 2026-04-01T00:00:00Z
X-Credits-Charged: 1Insufficient credits
If your team has exhausted its monthly credits, billable endpoints return 402 Payment Required:
{
"error": "Insufficient credits",
"credits_remaining": 0,
"credits_required": 1,
"period_ends_at": "2026-04-01T00:00:00Z"
}