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

# Exports

> Create bulk CSV/XLSX exports of permit data, poll for completion, and download a signed URL. Plus warehouse-native Parquet delivery.

Exports turn a filtered slice of permit data into a downloadable **CSV or XLSX**
file. They run **asynchronously**: you create a job, poll until it's ready, then
download a short-lived signed URL.

> [!NOTE]
>
> Export volume is tier-gated: the Free tier includes **5,000 exported rows /
> month**; Pro is **unlimited**. See [Pricing](https://permitcore.io/pricing).

## The export flow

**1. Create the job**

`POST /v1/exports` returns an `export_id` and a `poll_url`.

**2. Poll until complete**

`GET /v1/exports/{export_id}` until `status` is `completed` (or `failed`).

**3. Download**

A completed job carries a `signed_url` — fetch it before `expires_at`.

## Create an export

`POST /v1/exports` — `application/json` body:

| Field | Type | Required | Notes |
| - | - | - | - |
| `cohort` | string | Yes | Segment key to export (e.g. `hvac`, `roofing`, `solar`, `signage`). |
| `metros` | string\[] | Yes | Jurisdiction slugs, e.g. `["chicago_il", "nyc"]`. |
| `format` | string | Yes | `csv` or `xlsx`. |
| `date_range` | object | Yes | `{ "start": "YYYY-MM-DD", "end": "YYYY-MM-DD" }` (by issued date). |
| `expires_in_hours` | integer | No | Signed-URL lifetime; defaults to the service default. |

```bash curl theme={null}
curl -X POST https://api.permitcore.io/v1/exports \
  -H "Authorization: Bearer $PERMITCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cohort": "hvac",
    "metros": ["nyc"],
    "format": "csv",
    "date_range": { "start": "2026-01-01", "end": "2026-06-30" }
  }'
```

```json 202 Accepted theme={null}
{
  "export_id": "exp_7a1c9f2e",
  "status": "pending",
  "poll_url": "/v1/exports/exp_7a1c9f2e"
}
```

## Poll an export

`GET /v1/exports/{export_id}` — `status` is one of `pending`, `running`,
`completed`, `failed`.

```json completed theme={null}
{
  "export_id": "exp_7a1c9f2e",
  "status": "completed",
  "signed_url": "https://…r2.dev/exports/exp_7a1c9f2e.csv?…",
  "expires_at": "2026-07-16T22:00:00Z",
  "row_count": 4821,
  "file_size_bytes": 1583204,
  "error_message": null
}
```

While `pending`/`running`, `signed_url` and the size/count fields are `null`.
On `failed`, `error_message` explains why. Poll with a few seconds of backoff;
most exports complete in well under a minute.

## List your exports

`GET /v1/exports?limit=&before_id=` — most recent first, keyset-paginated.

```json theme={null}
{
  "items": [
    {
      "export_id": "exp_7a1c9f2e",
      "cohort": "hvac",
      "metros": ["nyc"],
      "format": "csv",
      "status": "completed",
      "requested_at": "2026-07-16T20:41:00Z",
      "completed_at": "2026-07-16T20:41:18Z"
    }
  ],
  "next_before_id": null
}
```

Pass `next_before_id` back as `before_id` to page older.

## Warehouse-native delivery

`GET /v1/exports/warehouse/latest` returns a manifest of the latest full-dataset
drop — **Parquet + gzipped CSV** files with signed R2 URLs, for loading straight
into Snowflake / BigQuery / a lake. This is the bulk alternative to per-query
exports.

```json theme={null}
{
  "schema_version": 1,
  "data_as_of": "2026-07-15",
  "generated_at_utc": "2026-07-16T06:00:00Z",
  "signed_url_expires_in_hours": 24,
  "tables": { "…": "…" },
  "honesty_semantics": { "…": "…" },
  "files": [
    {
      "table": "permits",
      "format": "parquet",
      "filename": "permits.parquet",
      "row_count": 18243110,
      "bytes": 1364235776,
      "preserves_tristate_dq_flags": true,
      "signed_url": "https://…r2.dev/warehouse/permits.parquet?…"
    }
  ]
}
```

`preserves_tristate_dq_flags` marks files that carry PermitCore's
true/false/unknown data-quality flags intact (rather than collapsing unknown to
false) — so the honesty semantics survive the round-trip into your warehouse.

## Errors

Exports use the standard [RFC 9457 problem+json](https://docs.permitcore.io/errors.md) shape. An invalid
`cohort`, `metros`, or `date_range` returns `422`
([`invalid-request`](https://docs.permitcore.io/errors/invalid-request)); a key that lacks the required
scope returns `403` ([`missing-scope`](https://docs.permitcore.io/errors/missing-scope)); an unknown
`export_id` returns `404` ([`export-not-found`](https://docs.permitcore.io/errors/export-not-found)); too
many concurrent jobs returns `429`
([`export-concurrency-exceeded`](https://docs.permitcore.io/errors/export-concurrency-exceeded)); and an
exhausted export quota returns `429`
([`monthly-exports-quota-exceeded`](https://docs.permitcore.io/errors/monthly-exports-quota-exceeded) /
[`daily-exports-quota-exceeded`](https://docs.permitcore.io/errors/daily-exports-quota-exceeded)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.