List Vena Table Endpoint

In this article, we explain how the Vena Table endpoints return table metadata for a data model, and how that metadata relates to Vena Tables in the Vena web app. These endpoints let integrations discover which Vena Tables exist on a model, what columns they contain, and (optionally) how large a table is — before starting an export.

Together with the asynchronous Vena Table export APIs (POST /api/public/v1/exports), the list and get endpoints give you everything you need to build an integration that:

1. Discovers available tables on a model
2. Inspects column schemas
3. Estimates size for capacity planning
4. Starts an export with the correct modelId, tableId, and optional column subset

These endpoints belong to the Public Export API family, alongside the Hierarchy and Intersections endpoints. They share the same authentication (HTTP Basic), error envelope, and license gate.

Endpoints overview

Base URL: https://{hub}.vena.io (for example https://us1.vena.io)

Auth: HTTP Basic — Vena API username and API key

License: The Public Export API feature must be enabled for the customer. If it is not, both endpoints return 422.

Why two endpoints?

Listing every table with a live row count requires COUNT(*) against the staging database for each table. For large tables that can take several seconds each, the list endpoint intentionally omits estimatedRowCount.

Use the workflow below:

1. Call list to discover table id, name, and columnNames.
2. When you need a size estimate for capacity planning, call get for that specific venaTableId.
3. Start an export with the chosen table id (and optional column names).

List Vena Tables (Beta)

GET /api/public/v1/models/{modelId}/venaTables
Authorization: Basic <credentials>
Accept: application/json

Path parameters

Example response

{
  "data": [
    {
      "id": "1000000000001",
      "name": "General Ledger Transactions",
      "columnNames": [
        "Account",
        "CostCenter",
        "PostingDate",
        "Amount"
      ]
    },
    {
      "id": "1000000000002",
      "name": "Headcount",
      "columnNames": [
        "Employee",
        "Department",
        "HireDate"
      ]
    }
  ],
  "metadata": {
    "recordsReturned": 2
  }
}

The list response uses the same data / metadata envelope as the Hierarchy and Intersections endpoints.

Response fields

Important: estimatedRowCount is not included in the response for this endpoint. To retrieve the estimated oy count for a specific Vena Table, use the Get a single Vena Table endpoint to get it.

Behavior notes

• Tables are sorted alphabetically by name (case-insensitive).
• Operational tables (OPERATIONAL) are excluded.
• If the model has no Vena Tables, the response is still 200 with an empty list:

{
  "data": [],
  "metadata": {
    "recordsReturned": 0
  }
}

• Pagination is not supported in v1 — all non-operational tables for the model are returned in one response.
• Data-level row permissions are not applied. Any caller with model-level read access sees all tables on that model.

Get a single Vena Table (Beta)

GET /api/public/v1/models/{modelId}/venaTables/{venaTableId}
Authorization: Basic <credentials>
Accept: application/json

Path parameters

Example response

{
  "id": "1000000000001",
  "name": "General Ledger Transactions",
  "estimatedRowCount": 2457812,
  "columnNames": [
    "Account",
    "CostCenter",
    "PostingDate",
    "Amount"
  ]
}

Unlike the list endpoint, the get endpoint returns a single object — not wrapped in a data array.

Response fields

estimatedRowCount

estimatedRowCount is computed when you call the GET endpoint. It is not a stored field on the Vena Table.

• On success, it reflects the current staging row count.
• If the count query fails or times out, the API returns 0 and still responds with 200. Treat 0 as “count unavailable or empty,” not as a hard failure of the metadata call.

Use this value for capacity planning before you start an export — for example, to decide page sizes, timeouts, or whether to filter with a whereClause.

Relating discovery to export

A typical integration flow:

List Vena Tables  →  pick table id / columnNames
        ↓
Get Vena Table    →  optional size check (estimatedRowCount)
        ↓
Create export     →  POST /api/public/v1/exports  (modelId + tableId + optional columnNames)

The list and get endpoints are metadata-only. They do not return row data. To extract table rows, use the Public Export API export job endpoints.

Errors

Structured errors use this JSON envelope (same as hierarchy and intersections). Missing path resources always use NOT_FOUND:

{
  "error": {
    "type": "NOT_FOUND",
    "title": "Not Found",
    "message": "The data model 9999999999 was not found. Ensure the modelId is correct and try again."
  }
}

Create-export (POST /exports) is different: missing modelId / tableId in the request body return 400 with INVALID_PARAMETER . List and get use path params, so those cases are HTTP 404 with NOT_FOUND.

Common status codes

404 variants

All 404s share type: NOT_FOUND and title: Not Found. Distinguish them by message.

List — model missing or other tenant

{
  "error": {
    "type": "NOT_FOUND",
    "title": "Not Found",
    "message": "The data model 9999999999 was not found. Ensure the modelId is correct and try again."
  }
}

Cross-tenant model access returns 404 NOT_FOUND (not 403) to avoid leaking whether a model exists in another tenant.

Get — model missing

Same NOT_FOUND shape as above.

Get — table missing, wrong model, or operational

{
  "error": {
    "type": "NOT_FOUND",
    "title": "Not Found",
    "message": "The VenaTable 8888888888 was not found in model 123456789012345678."
  }
}

Operational tables are treated as not found on the Public Export API surface.

Field reference summary

Conclusion

The Vena Table endpoints expose table metadata as a data object so integrations can discover what is available to export without hard-coding table names or relying the UI.

• Use list for fast discovery of all tables and their columnNames on a model.
• Use get when you need a live size estimate for one table.
• Combine these with the Hierarchy, Intersections, and export job endpoints to move Vena data into downstream systems with confidence.