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

# Start a CSV export

`POST /api/v1/contacts/search/export`

Authentication: API key.

Optional body field: `unmask: true` fills missing contact details up to your monthly unmask budget. The default exports rows as stored. Status includes `rows_unmasked` and `rows_masked_by_budget`. Send the same option to `POST /api/v1/contacts/search/count` for `unmask_preview: { rows, cached, new_unmasks, budget_remaining }` without spending budget. MCP `export_contacts` and `count_contacts` accept this option too.

Start an async export of search matches to CSV on S3. Same filters as `POST /api/v1/contacts/search` (no `offset`). Returns immediately with `export_id` (HTTP 202); poll `GET /api/v1/contacts/search/export/{export_id}` until `job_status` is `completed`, then use `export_url`. Free plan: capped at `min(creditsRemaining, total_available)`. Unlimited: subject to daily (500k) and monthly (6M) export caps. Optional `max_rows` (1-50,000) caps how many rows this export writes; omit to export all matches up to plan/credit/50k limits. 1 credit per row exported.

### Body parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `filters` | object | no |  |  |
| `max_per_company` | number | no |  |  |
| `max_rows` | number | no |  |  |
| `confirmed` | boolean | no |  |  |

### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `ok` | boolean | True when the request succeeded. |
| `export_id` | string | The identifier of the export job. |
| `job_status` | string | One of queued, running, completed or failed. |
| `rows_available` | number | The number of rows that matched the filters. |
| `export_row_cap` | number | The row cap applied to this export. |
| `rows_capped_by_credits` | boolean | True when the credit balance limited the export. |
| `message` | string | A plain sentence that explains the result. |

### Example request

```bash
curl -sS -X POST "https://leadmcp.ai/api/v1/contacts/search/export" \
  -H "X-API-Key: lb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filters": {
    "job_titles": ["Software Engineer"],
    "cities": ["San Francisco"]
  },
  "max_per_company": 3,
  "max_rows": 5000,
  "confirmed": true
}'
```

### Example response (202)

```json
{
  "ok": true,
  "export_id": "01KV8DNW282Y2V5YAQ51C2XWN1",
  "job_status": "queued",
  "rows_available": 46169,
  "export_row_cap": 5000,
  "rows_capped_by_credits": true,
  "message": "Export started. Poll GET /api/v1/contacts/search/export/{export_id} until job_status is completed."
}
```