Database search

Count matches

Aggregated match count for a filter set, free (0 credits), no records returned, no pagination needed. Takes the same auth and the same filter body as POST /api/v1/contacts/search (limit, offset, and columns are ignored). Use it to size a query before searching or exporting, or for coverage analysis.

POST/api/v1/contacts/search/count

Counts are exact at any scale, with no upper cap, so there is no need to slice broad queries into segments. At least one filter (or where_sql) is required, an empty filters object returns 400 listing the accepted parameters.

exportable_rows is how many of the matches a single CSV export would write (min(total_matching, 50000), further bounded by remaining credits on the free plan); export_capped is true when the match count exceeds that.

Authorization

Header	Type	Required	Description
`X-API-Key`	string	required	Your API key, for example `lb_live_YOUR_API_KEY`. You can send the same key as `Authorization: Bearer` instead.

Body parameters

Name	Type	Required	Default	Description
`filters`	object	optional

Response

ok boolean: True when the request succeeded.
total_matching number: The exact number of contacts that match the filters.
max_export_rows number: The largest number of rows one export can write.
exportable_rows number: How many matches a single export would write.
export_capped boolean: True when the match count is above the export limit.
credits_used number: Plan credits this request spent.
creditsRemaining null: Plan credits left after this request. Null on unlimited plans.
message string: A plain sentence that explains the result.

curl -sS -X POST "https://leadmcp.ai/api/v1/contacts/search/count" \
  -H "X-API-Key: lb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":{"countries":["Ireland"],"seniority":["C-Team"]}}'

Response200

{
  "ok": true,
  "total_matching": 56721,
  "max_export_rows": 50000,
  "exportable_rows": 50000,
  "export_capped": true,
  "credits_used": 0,
  "creditsRemaining": null,
  "message": "Found 56721 matching contacts. Up to 50000 can be exported in one CSV (max 50000 per export)."
}