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:

Export key	Dataset keys	Month filters
consolidation_v1	group_consolidation_gsheets, group_consolidation_gsheets_dimensions	Supported
revenue_bridge_v1	revenue_bridge_ctrl_uniform	Not supported; full-table snapshot
stripe_journal_v1	stripe_journal_entries	Not supported; full-table snapshot

The definitions list describes supported exports. Check GET /api/parquet-exports/catalog for dataset availability in your tenant before requesting an optional reporting export. Revenue bridge and Stripe journal datasets appear only when their source tables exist in your tenant’s output dataset.

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

Revenue bridge and Stripe journal

Use the same snapshot, polling, manifest, and download flow with either reporting export key:

curl -X POST \
  "$API_BASE/api/parquet-exports/exports/revenue_bridge_v1/snapshots" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"clientRequestId": "revenue-bridge-nightly-2025-01-15"}'

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/parquet-exports/exports/revenue_bridge_v1/latest-status"

curl -H "Authorization: Bearer $TOKEN" \
  "$API_BASE/api/parquet-exports/exports/revenue_bridge_v1/latest"

Replace revenue_bridge_v1 with stripe_journal_v1 for the journal export, and use a distinct client request ID for each export and nightly run. Omit both accounting month fields on creation and latest/status requests; these definitions reject month filters with 400.

Both exports preserve the source table’s columns and row grain without additional aggregation. The revenue bridge dataset key stays revenue_bridge_ctrl_uniform, while its source follows the revenue bridge model selected by active Sheets connectors in the tenant’s output dataset. This includes customized revenue_bridge_ctrl_uniform_* models. With no configured bridge source, the default table is revenue_bridge_ctrl_uniform. If active connectors select different bridge models, or the selected table is missing, the dataset is unavailable rather than silently exporting a different model. Check the catalog’s sourceTableName before loading.

Stripe journal uses the configured journal table (normally fct_stripe_journal_entries). To reconcile with Sheets, compare the same source refresh and apply the same sheet-level filters and column selections downstream. Parquet does not reproduce spreadsheet formatting, formulas, or connector-specific filters.

Load every file of a completed reporting snapshot into staging and replace the whole destination table atomically. These full-table exports do not provide consolidation’s per-period change hashes.

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"
    ],
    "accountingMonthFrom": "2025-01",
    "accountingMonthTo": "2025-12",
    "clientRequestId": "advanced-2025"
  }'

Month filters require every selected dataset to support accounting-month slicing. Request full-table datasets such as ctrl_group_accounts_latest, revenue_bridge_ctrl_uniform, and stripe_journal_entries separately without month filters. Mixing sliced and full-table datasets with a month range returns 400.

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.