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

# Bulk Export

> Get your full dataset without signing in — the same CSV the dashboard Export button produces

# Bulk Export

The list endpoints return 100 rows a page, which is right for answering a
question and wrong for moving a dataset. When you want everything — a
spreadsheet, a CRM import, a warehouse load — use the export endpoints. They
run the same pipeline as the **Export** button in the dashboard and produce the
identical file, so nobody has to log in and click anything.

Exports are asynchronous. You start one, get a `jobId`, and poll until a
download link appears.

<Note>
  Your existing API key works. Exports need only read access — there is no new
  credential to create and no OAuth flow to complete.
</Note>

***

## Start an export

```bash theme={null}
curl -X POST https://api-v1.maverickintelligence.co/v1/exports \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"timeframe": "30d", "isHotLead": true}'
```

```json theme={null}
{
  "jobId": "8f14e45fceea167a5a36dedd4bea2543",
  "status": "processing",
  "statusUrl": "/v1/exports/8f14e45fceea167a5a36dedd4bea2543",
  "pollAfterSeconds": 5
}
```

Send an empty body (or no body at all) to export everything.

## Poll until it's ready

```bash theme={null}
curl https://api-v1.maverickintelligence.co/v1/exports/8f14e45fceea167a5a36dedd4bea2543 \
  -H "X-API-Key: mk_live_your_key_here"
```

While it runs:

```json theme={null}
{ "jobId": "8f14e45f...", "status": "processing", "createdAt": "2026-09-04T12:00:00+00:00" }
```

When it finishes:

```json theme={null}
{
  "jobId": "8f14e45f...",
  "status": "complete",
  "createdAt": "2026-09-04T12:00:00+00:00",
  "completedAt": "2026-09-04T12:01:12+00:00",
  "downloadUrl": "https://maverick-exports.s3.amazonaws.com/...",
  "downloadUrlExpiresInSeconds": 900,
  "rowCount": 4213,
  "partial": false
}
```

<Warning>
  `downloadUrl` is valid for **15 minutes from `completedAt`**, not from when you
  read it. A job that finished an hour ago has a dead link — start a new export
  rather than retrying the URL.
</Warning>

A large account takes a minute or two. Poll every 5 seconds or so.

## End to end

```python theme={null}
import time, requests

API = "https://api-v1.maverickintelligence.co/v1"
headers = {"X-API-Key": "mk_live_your_key_here"}

job = requests.post(
    f"{API}/exports",
    headers=headers,
    json={"timeframe": "30d", "isHotLead": True},
).json()

while True:
    status = requests.get(f"{API}/exports/{job['jobId']}", headers=headers).json()
    if status["status"] == "complete":
        csv = requests.get(status["downloadUrl"]).content
        open("hot_leads.csv", "wb").write(csv)
        print(f"{status['rowCount']} rows")
        break
    if status["status"] == "failed":
        raise RuntimeError(status.get("error", "export failed"))
    time.sleep(5)
```

## Filters

Every filter is optional. Arrays may be sent as JSON arrays or as
comma-separated strings.

| Filter                 | Type    | Notes                                                 |
| ---------------------- | ------- | ----------------------------------------------------- |
| `timeframe`            | string  | `24h`, `7d`, `30d`, `90d`, `all`                      |
| `dateField`            | string  | Which date `timeframe` applies to. Default `lastSeen` |
| `isHotLead`            | boolean | Only current hot leads                                |
| `industries`           | array   | Company industries                                    |
| `regions`              | array   | Regions                                               |
| `seniority`            | array   | Seniority levels                                      |
| `jobFunctions`         | array   | Job functions                                         |
| `domains`              | array   | Tracked site domains                                  |
| `pages`                | array   | Page paths the visitor saw                            |
| `campaigns`            | array   | Campaigns                                             |
| `trafficTypes`         | array   | Traffic types                                         |
| `adPlatforms`          | array   | Ad platforms                                          |
| `visitCountMin`        | integer | Minimum visits                                        |
| `hasBusinessEmail`     | boolean | Rows with a business email                            |
| `hasLinkedIn`          | boolean | Rows with a LinkedIn profile                          |
| `hasPhone`             | boolean | Rows with a phone number                              |
| `crmStatus`            | string  | `in_crm`, `not_in_crm`, `customers`                   |
| `search`               | string  | Free text across name, company, email                 |
| `sortBy` / `sortOrder` | string  | Ordering                                              |
| `filename`             | string  | Name of the downloaded file                           |

An unrecognised filter is a `400` naming the offending key. That is
deliberate — a silently ignored filter hands you a file with more rows than you
asked for.

## Limits

* **Three exports** may run at once per account. A fourth returns `429` with
  code `too_many_exports`.
* Export requests count against your normal hourly rate limit.
* Jobs and their rows expire after 7 days.

## From Claude

The [Claude connector](/claude-connector) exposes the same thing as the
`start_export` and `get_export_status` tools, so you can ask for a file in
plain language:

> *"Export every hot lead from the last 30 days and give me the download link."*

## Scoped keys

Partner client keys scoped to specific domains cannot export: an export is
account-wide, and the export pipeline has no per-client filter yet, so allowing
it would hand one client another client's visitors. Scoped keys get a `403`
with code `scope_not_supported`. Use an unscoped key, or read `/v1/people` with
a `domain` filter and page through it.