Get Table

Get Table

POST /api/v1/dl/get_table

Returns details for a single Tableflow table, looked up by UUID or by name.

Request

Field	Type	Required	Description
virtual_cluster_id	string	Yes	The ID of the Tableflow virtual cluster.
table_uuid	string	Optional*	The UUID of the table to retrieve.
table_name	string	Optional*	The name of the table to retrieve.
include_status	boolean	No	If true, includes Tableflow health, sync status, and lag information.

Caution

Exactly one of table_uuid or table_name must be specified. Providing both or neither will return an error.

CURL Example (by UUID)

curl https://api.warpstream.com/api/v1/dl/get_table \
  -H 'warpstream-api-key: XXXXXXXXXX' \
  -H 'Content-Type: application/json' \
  -d '{
    "virtual_cluster_id": "vci_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
    "table_uuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

CURL Example With Status

curl https://api.warpstream.com/api/v1/dl/get_table \
  -H 'warpstream-api-key: XXXXXXXXXX' \
  -H 'Content-Type: application/json' \
  -d '{
    "virtual_cluster_id": "vci_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX",
    "table_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "include_status": true
  }'

Response

{
  "table": {
    "table_name": "my_cluster.my_topic.a1b2c3d4",
    "table_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "table_location": "s3://my_bucket/warpstream/_tableflow/my_cluster.my_topic.a1b2c3d4-550e8400-e29b-41d4-a716-446655440000",
    "source_stream_name": "my_topic",
    "source_cluster_name": "my_cluster",
    "stats_estimated_byte_count": 1048576,
    "stats_estimated_row_count": 10000,
    "created_at_unix_nanos": 1700000000000000000
  }
}

Field	Type	Description
table.table_name	string	The full name of the table.
table.table_uuid	string	The unique identifier of the table.
table.table_location	string	The location (blob storage URL) where the Iceberg table’s data and metadata is stored.
table.source_stream_name	string	The source Kafka topic name.
table.source_cluster_name	string	The name of the source cluster.
table.stats_estimated_byte_count	integer	Estimated total size of the table in bytes.
table.stats_estimated_row_count	integer	Estimated total number of rows in the table.
table.created_at_unix_nanos	integer	Table creation timestamp in nanoseconds since Unix epoch.

Response With Status

When include_status is true, the response includes a status object.

{
  "table": {
    "table_name": "my_cluster.my_topic.a1b2c3d4",
    "table_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "table_location": "s3://my_bucket/warpstream/_tableflow/my_cluster.my_topic.a1b2c3d4-550e8400-e29b-41d4-a716-446655440000",
    "source_stream_name": "my_topic",
    "source_cluster_name": "my_cluster",
    "stats_estimated_byte_count": 1048576,
    "stats_estimated_row_count": 10000,
    "created_at_unix_nanos": 1700000000000000000
  },
  "status": {
    "health": {
      "status": "healthy",
      "message": "Table is active, synced, and lag signals are current.",
      "reasons": [
        "table_active",
        "pipeline_config_synced"
      ]
    },
    "iceberg_metadata_matches_deployed_config": true,
    "iceberg_metadata_pipeline_version": 12,
    "deployed_pipeline_version": 12,
    "table_status": "active",
    "ingestion_lag_known": true,
    "ingestion_lag_milliseconds": 60000,
    "query_lag_known": true,
    "query_lag_milliseconds": 90000,
    "total_offset_lag_count": 42,
    "partitions": [
      {
        "partition_id": 0,
        "offset_lag_count": 42,
        "time_lag_known": true,
        "time_lag_milliseconds": 60000
      }
    ]
  }
}

Field	Type	Description
status.health.status	string	Overall table health. Possible values include healthy, initializing, paused, and inactive.
status.health.message	string	Human-readable explanation of the current health state.
status.health.reasons	array of strings	Machine-readable reason codes for the health state.
status.iceberg_metadata_matches_deployed_config	boolean	Whether the table’s Iceberg metadata reflects the currently deployed Tableflow configuration.
status.iceberg_metadata_pipeline_version	integer	Pipeline configuration version recorded in the table’s Iceberg metadata, or -1 if unknown.
status.deployed_pipeline_version	integer	Currently deployed Tableflow pipeline configuration version, or -1 if unknown.
status.table_status	string	Table config status. Possible values are active, paused, inactive, and unknown.
status.ingestion_lag_known	boolean	Whether ingestion lag is available.
status.ingestion_lag_milliseconds	number or null	Maximum ingestion lag across table partitions, in milliseconds. Null when unknown.
status.query_lag_known	boolean	Whether query lag is available.
status.query_lag_milliseconds	number or null	Estimated time between source records being available and query engines being able to see them, in milliseconds. Null when unknown.
status.total_offset_lag_count	integer	Total number of source records pending ingestion across all partitions.
status.partitions	array	Per-partition lag details.
status.partitions[].partition_id	integer	Source topic partition ID.
status.partitions[].offset_lag_count	integer	Number of source records pending ingestion for this partition.
status.partitions[].time_lag_known	boolean	Whether time lag is available for this partition.
status.partitions[].time_lag_milliseconds	number or null	Time lag for this partition in milliseconds. Null when unknown.