CSV Export

EndpointsCopy Anchor Link

Auth is the same as the batch endpoints: Authorization: Bearer {YOUR_API_KEY} or the apiKey header.

Sync vs. Async export:

Quick StartCopy Anchor Link

Call POST /exports with the batch_ids you want combined into one CSV; delivery mode is decided for you by size.

Prefer clicking through instead? See Using the Dashboard for the same flow with checkboxes and an Export N Batches button.

curl -X POST \
  'https://api.repromptai.com/v1/{org_slug}/place_enrichment/exports' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 4a7c1e02-3f3d-4b1a-9c2e-8f6d2b1a9e40' \
  -d '{
    "batch_ids": ["batch_2024_03_15_123456", "batch_2024_03_16_654321"]
  }'

{
  "id": "e59f3b9a-6b7d-4e21-9d34-9d1b6c9b6a41",
  "status": "queued",
  "batch_ids": ["batch_2024_03_15_123456", "batch_2024_03_16_654321"],
  "batch_names": {
    "batch_2024_03_15_123456": "NYC Restaurants March 2024",
    "batch_2024_03_16_654321": "Chicago Retail March 2024"
  },
  "created_at": "2024-03-15T10:00:00Z",
  "updated_at": "2024-03-15T10:00:00Z",
  "status_url": "/v1/{org_slug}/place_enrichment/exports/e59f3b9a-6b7d-4e21-9d34-9d1b6c9b6a41",
  "download_url": null,
  "error": null,
  "metadata": null,
  "expired": false
}

Sync ExportsCopy Anchor Link

Small exports skip the export job entirely. A single batch (max 50,000 places) always qualifies; so does any combination of batches that stays roughly under 50,000 rows and 120 MB. You get 200 back with the CSV already in the body:

curl -X POST \
  'https://api.repromptai.com/v1/{org_slug}/place_enrichment/exports' \
  -H 'Authorization: Bearer {YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{"batch_ids": ["batch_2024_03_15_123456"]}' \
  -o place-enrichment.csv

Async ExportsCopy Anchor Link

Larger selections return 202 immediately: status: queued, a status_url to poll, and download_url: null until the job finishes.

There is no set limit to number of batches or total jobs to export, async export comfortably handles exports >1M jobs across many batches.

Idempotency-KeyCopy Anchor Link

Sending an Idempotency-Key is optional, not required. Its only job is to make retries safe:

• With a key: retry the same request (same key, same batch_ids) as many times as you want, like after a timeout, and you'll get back the original export job instead of a new one. Reuse the key with a different batch_ids set and you'll get 409, since that's not a retry.
• Without a key: every request creates a new export job, including retries. Fine for one-off calls; risky if your client retries automatically.

We recommend a UUID v4, generated once per export attempt and reused across that attempt's retries — not a new one per HTTP call.

Export LifecycleCopy Anchor Link

1. Queued: Export Job accepted; waiting for a worker to pick it up.
2. Running: A worker is generating the CSV.
3. Completed: download_url is set. Download it before the retention window closes.
4. Failed: Something went wrong — check error. Worker dispatch failures return 502 on create and mark the export job failed immediately; it's safe to retry.
5. Expired: The artifact aged past its 7-day retention window. download_url is null and expired is true.

Polling & DownloadingCopy Anchor Link

Status Response FieldsCopy Anchor Link

This is the shape returned by the 202 on create, by Get export status, and by each element of List exports.

Listing ExportsCopy Anchor Link

GET /exports?status=&cursor=&limit= returns { exports: [...], next_cursor }, newest first.

CSV ColumnsCopy Anchor Link

Every export has the same shape: batch_id, batch_name, place_id, status, then per-attribute columns — {field}_original (your inputs), {field}_enriched (the enriched value), {field}_status, plus confidence and reasoning columns. Columns that are blank across every row are dropped.

For what each attribute returns, see Place Job Results.

ErrorsCopy Anchor Link

Using the DashboardCopy Anchor Link

Exports work the same way without writing any code.

On Place Enrichment → Run Batches, check one or more batches and click Export N Batches. A confirm dialog — "Export N batches (~X jobs) as a single CSV. Large selections generate in the background…" — kicks off the same POST /exports under the hood.

• Small exports download instantly in the browser.
• Large exports show a "queued" toast with a View link to the Exports screen (sidebar → Exports, /place-enrichment/exports).
• The Exports screen lists background exports with status pills — Queued / Generating / Ready / Failed / Expired — and auto-polls until each one finishes. Ready rows get a Download button (a plain link that follows the 307 to S3); failed rows get Retry.
• Its subtitle states the rule plainly: "Background CSV exports, kept 7 days. Small exports download instantly and aren't listed here."

Idempotency is handled for you — the dashboard sends one key per export attempt.

Best PracticesCopy Anchor Link

• Send an Idempotency-Key for anything you might retry — a UUID v4 per export attempt, reused across that attempt's retries, not generated per HTTP call.
• Poll politely — every few seconds is enough; the export runs as a background export job either way.
• Download promptly — the signed URL expires in 1 hour. Call /download again for a fresh one if you miss the window.
• Check metadata.rows_exported — confirms the export covered the rows you expected before you rely on the file.

Next StepsCopy Anchor Link

• Batch Processing - create the batches you're exporting
• Place Job Results - full schema of the enriched attributes behind each CSV column