> ## Documentation index
> Fetch the complete documentation index at: https://leadmcp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Count matches

`POST /api/v1/contacts/search/count`

Authentication: API key.

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.

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.

### Body parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `filters` | object | no |  |  |

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `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. |

### Example request

```bash
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"]}}'
```

### Example response (200)

```json
{
  "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)."
}
```