VEvenasolutions
Vena tables [Beta]

Create Vena Table Export

Changed on

Beta. Submits an asynchronous Vena Table snapshot export job and returns immediately with status SUBMITTED. Poll GET /exports/{exportId}/status until COMPLETED before calling GET /exports/{exportId}/data.

The create response uses id (not exportId) and returns a flat export resource rebuilt from the persisted job/step (exportType, modelId, tableId, whereClause, columnNames, timestamps). It does not echo a nested request object. errorReason is omitted on create (status is always SUBMITTED).

Row cap: A single export job can contain at most 20,000,000 rows. Create runs a pre-flight COUNT; if the result would exceed the cap, the API returns 400 EXPORT_ROW_LIMIT_EXCEEDED and does not enqueue a job. Use whereClause to narrow the result set. A zero-row result is allowed — the job is enqueued and /data returns an empty page after COMPLETED.

TTL: expiresTime is createdTime + 24 hours.

Not-found on create uses HTTP 400 (INVALID_PARAMETER on modelId / tableId), not 404. True HTTP 404 (NOT_FOUND / EXPORT_EXPIRED) applies to status and data endpoints.

exportType must be the exact token VENA_TABLE (case-sensitive, no surrounding whitespace). Blank, unknown, lowercase, or padded values return 400 INVALID_PARAMETER.

Unknown JSON properties on the request body are ignored (forwards-compatible).

post/exports

Request

Request body

exportType'VENA_TABLE' required

Export pipeline selector. v1 accepts the exact token VENA_TABLE only (case-sensitive, no surrounding whitespace). Blank, unknown, lowercase (vena_table), or padded (VENA_TABLE) values deserialize as missing and return 400 INVALID_PARAMETER (exportType must be VENA_TABLE.).

modelIdstring required

Model ID (JSON string Id)

tableIdstring required

Vena Table ID on the given model (JSON string Id)

whereClausestring required

Required VenaQL WHERE filter to scope the export and stay within the 20,000,000-row snapshot cap.

  • Missing / null → 400 INVALID_PARAMETER
  • Empty string ("") → export all permitted rows (small tables only)
  • Non-empty → must be valid VenaQL (validated at create time)

NULL checks — use IS NULL / IS NOT NULL: Comparisons with = / != against NULL evaluate to UNKNOWN and can silently return 0 rows even when syntax validation passes.

AvoidUse instead
Field = nullField IS NULL
Field != nullField IS NOT NULL
Field NOT IN ('a', null)Field NOT IN ('a', 'b') AND Field IS NOT NULL
Field BETWEEN null AND 100Field <= 100

Always quote string literals (Field = 'yes', not Field = yes). Vena Table cells are stored as strings — prefer Field = '123' over Field = 123.

LIKE: escape literal % / _ when needed (Field LIKE '10\_000' ESCAPE '\\').

columnNamesstring[] nullable

Optional column subset. Omitted or empty = all columns on the table. Each name must exist on the table.

Example request

{
  "modelId": "123456789012345678",
  "tableId": "987654321098765432",
  "whereClause": "Region = 'North America' AND Year = '2024'",
  "columnNames": [
    "Year",
    "Entity",
    "Amount"
  ]
}

Response

Export job accepted and enqueued. Body is a flat export resource: id, status=SUBMITTED, exportType, modelId, tableId, whereClause, columnNames, and timestamps. Poll status before fetching data.

idstring required

Export job ID. Use this in GET /exports/{exportId}/status and /data.

status'SUBMITTED' required

Initial job status on create — always SUBMITTED

exportType'VENA_TABLE' required

Export pipeline type

modelIdstring required

Model id for this export

tableIdstring required

Vena Table source id

whereClausestring

Filter applied when building the snapshot (may be empty)

columnNamesstring[]

Resolved columns included in the snapshot

createdTimestring date-time required
expiresTimestring date-time required

Absolute expiration instant. Equals createdTime + snapshot TTL (typically 24 hours).

errorReasonstring

Present only when status is ERROR — user-facing summary from the ETL job short message

Example response

{
  "id": "123456789012345678",
  "modelId": "123456789012345678",
  "tableId": "987654321098765432",
  "createdTime": "2026-08-05T12:00:00.000Z",
  "expiresTime": "2026-08-06T12:00:00.000Z"
}

Changes