Bulk Delivery

Bulk Delivery exports an entire filtered dataset to a single file. Instead of paging through millions of records 100 at a time, you submit the same filters you'd use on a list endpoint, pick an output format, and the API runs a background job that writes every matching row to a file in S3. Poll the job, and when it's done you get a signed URL to download the result.

It's the right tool when you want a whole slice of the dataset — every loan in a state, every originator at a company, every property in a set of ZIPs — landed as one file for a warehouse load, an offline analysis, or a hand-off to another system. For interactive, page-at-a-time reads, use the list endpoints instead.

Bulk Delivery is available for six resources:

Every endpoint behaves identically — only the entity and its columns differ. The examples below use agents; swap the path segment for any other resource.

How credits work

Bulk Delivery is metered by the number of rows delivered — a bigger export costs more, scaling with the row count.

• You're gated on the estimate at submission. Before queuing the job, the API estimates the result-set size (estimatedTotal) and requires enough balance to cover it. If you can't cover the worst case, submission returns 402 — the job never starts.
• You're charged on the actual delivered count. Billing lands when the job completes, against the rows actually written (chargedCount), which can be lower than the estimate.
• A failed job isn't charged. If the export fails, no credit is debited.

The completed job record reports exactly what you paid: chargedCount (rows billed), creditsCharged (credits debited), and creditLedgerId (the ledger entry).

Submit a job

Send a POST to the resource's bulk-delivery endpoint. The request body is the same filter shape as the list endpoint — flatFilters, advancedFilters, period, and sort all work exactly as documented in Pagination & Filtering — plus two delivery-specific fields:

curl -X POST https://api.modelmatch.com/v1/agents/bulk-delivery \
  -H "x-api-key: mm_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "flatFilters": { "state": "CA" },
    "format": "parquet",
    "fields": ["fullName", "city", "state", "transactionCount"]
  }'

A successful submission returns 202 Accepted with a job handle:

{
  "jobId": "job_abc123",
  "status": "queued",
  "entityType": "agents",
  "format": "parquet",
  "estimatedTotal": 18452,
  "maxRows": 100000
}

Row limits

A single delivery is capped at maxRows. If the estimated result set is larger, the API rejects the request with 400 and a delivery_exceeds_max_rows error rather than queuing a job you can't complete:

{
  "error": "delivery_exceeds_max_rows",
  "estimatedTotal": 820000,
  "maxRows": 100000
}

Tighten your filters or split the export by a dimension (state, period, ZIP range) and submit multiple jobs.

Poll for status

Poll the GET endpoint with your jobId until status is completed (or failed):

curl https://api.modelmatch.com/v1/agents/bulk-delivery/job_abc123 \
  -H "x-api-key: mm_your_key_here"

{
  "jobId": "job_abc123",
  "entityType": "agents",
  "format": "parquet",
  "status": "completed",
  "estimatedTotal": 18452,
  "processed": 18452,
  "bytes": 7340032,
  "chargedCount": 18452,
  "creditsCharged": 185,
  "creditLedgerId": "ledg_xyz789",
  "startedAt": "2026-06-25T18:40:00.000Z",
  "completedAt": "2026-06-25T18:43:12.000Z",
  "resultsUrl": "https://..."
}

Download the result

Once status is completed, fetch resultsUrl directly — it's a plain signed S3 link, no auth header needed:

curl -L "$(curl -s https://api.modelmatch.com/v1/agents/bulk-delivery/job_abc123 \
  -H 'x-api-key: mm_your_key_here' | jq -r .resultsUrl)" \
  -o agents.parquet

Cancel a job

Send a DELETE to the same path to cancel a queued or running job:

curl -X DELETE https://api.modelmatch.com/v1/agents/bulk-delivery/job_abc123 \
  -H "x-api-key: mm_your_key_here"

The job is marked cancelled immediately and the worker stops at its next page boundary. The response body is the job's settled status record. A delivery is billed once, at completion, so a cancelled job is never charged — no credits are debited and no partial file is written. Cancelling a job that has already finished (or was already cancelled) returns 409 and changes nothing.

Formats

Every format contains the same rows — the entity's list/summary record, one per row (optionally narrowed by fields). Pick based on how you'll consume the file:

Errors

All endpoints return the standard authentication errors (401, 403, 429). In addition:

A 402 is the one to handle gracefully — catch it, surface balance vs cost, and prompt the user to top up before retrying. For a 403 on submit, lower limit or narrow the filters to fit under 1,000 rows, or reach out to support for a limit increase rather than retrying.