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.

export API_BASE="https://api.control.dev"
export TOKEN="<control-oauth-access-token>"

1. List supported export definitions

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

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.

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.

3. Check the latest status

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.

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

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:

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:

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:

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.

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.