> ## Documentation Index
> Fetch the complete documentation index at: https://control-dev.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Parquet API quickstart

> List exports, request a snapshot, poll status, and download changed files.

Use the public Control API at `https://api.control.dev`. The examples assume you completed [Parquet authentication](/product-docs/data-exports/parquet-authentication).

```bash theme={null}
export API_BASE="https://api.control.dev"
export TOKEN="<control-oauth-access-token>"
```

## 1. List supported export definitions

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/parquet-exports/exports"
```

Use the returned `exportKey`. The recommended key is currently `consolidation_v1`.

## 2. Request a snapshot

```bash theme={null}
curl -X POST \
  "$API_BASE/api/parquet-exports/exports/consolidation_v1/snapshots" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accountingMonthFrom": "2025-01",
    "accountingMonthTo": "2025-12",
    "clientRequestId": "warehouse-2025-full"
  }'
```

Save the returned snapshot `id`.

<Warning>
  Do not send `datasetKeys` to the export-definition endpoint. The `exportKey` determines its datasets. Use `POST
      /api/parquet-exports/snapshots` only when intentionally requesting a custom set of catalog dataset keys.
</Warning>

## 3. Check the latest status

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/parquet-exports/exports/consolidation_v1/latest-status?accountingMonthFrom=2025-01&accountingMonthTo=2025-12"
```

`latest-status` can return an in-progress snapshot. Use `latest` when you only want the latest completed snapshot for the same export and optional month range.

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/parquet-exports/exports/consolidation_v1/latest?accountingMonthFrom=2025-01&accountingMonthTo=2025-12"
```

## 4. Read the snapshot and manifest

```bash theme={null}
export SNAPSHOT_ID="<snapshot-id>"

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/parquet-exports/snapshots/$SNAPSHOT_ID"

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/parquet-exports/snapshots/$SNAPSHOT_ID/manifest"
```

Compare the manifest's slice/period keys and `contentHash` values with your last successful ingestion.

## 5. Download files

The snapshot response contains root-relative authenticated artifact download paths. Prefix the returned path with `API_BASE`, download only paths returned by the Control API, and keep the bearer token attached:

```bash theme={null}
curl -L \
  -H "Authorization: Bearer $TOKEN" \
  "$API_BASE<artifact-download-path>" \
  --output control-export.parquet
```

## Custom dataset snapshots

Advanced consumers can inspect the public and raw catalogs:

```bash theme={null}
curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/parquet-exports/catalog"

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/parquet-exports/raw/catalog"
```

Then request explicit dataset keys:

```bash theme={null}
curl -X POST \
  "$API_BASE/api/parquet-exports/snapshots" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "datasetKeys": [
      "group_ctrl_uniform_transactions_v2",
      "ctrl_group_accounts_latest"
    ],
    "accountingMonthFrom": "2025-01",
    "accountingMonthTo": "2025-12",
    "clientRequestId": "advanced-2025"
  }'
```

Prefer the versioned export definition unless you specifically need lower-level tables.

To inspect downloaded files locally, use the [DuckDB example in Parquet exports](/product-docs/data-exports/parquet-overview#example-query-a-snapshot-with-duckdb).

## Common errors

| Response                     | Likely cause                                                                           |
| ---------------------------- | -------------------------------------------------------------------------------------- |
| `400` unsupported export key | The path contains a dataset key instead of a valid `exportKey`. List `/exports` first. |
| `400` invalid request        | The month range or request body does not match the selected endpoint.                  |
| `401`                        | The bearer token is missing, expired, or invalid.                                      |
| `403`                        | Tenant membership or the Parquet feature is missing.                                   |
| `404` from `latest`          | No completed snapshot exists for that export and exact month range.                    |