# 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) ```bash 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 ```bash 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 ```json { "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. ```json { "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 } ] } } ```
FieldTypeDescription
status.health.statusstringOverall table health. Possible values include healthy, initializing, paused, and inactive.
status.health.messagestringHuman-readable explanation of the current health state.
status.health.reasonsarray of stringsMachine-readable reason codes for the health state.
status.iceberg_metadata_matches_deployed_configbooleanWhether the table's Iceberg metadata reflects the currently deployed Tableflow configuration.
status.iceberg_metadata_pipeline_versionintegerPipeline configuration version recorded in the table's Iceberg metadata, or -1 if unknown.
status.deployed_pipeline_versionintegerCurrently deployed Tableflow pipeline configuration version, or -1 if unknown.
status.table_statusstringTable config status. Possible values are active, paused, inactive, and unknown.
status.ingestion_lag_knownbooleanWhether ingestion lag is available.
status.ingestion_lag_millisecondsnumber or nullMaximum ingestion lag across table partitions, in milliseconds. Null when unknown.
status.query_lag_knownbooleanWhether query lag is available.
status.query_lag_millisecondsnumber or nullEstimated time between source records being available and query engines being able to see them, in milliseconds. Null when unknown.
status.total_offset_lag_countintegerTotal number of source records pending ingestion across all partitions.
status.partitionsarrayPer-partition lag details.
status.partitions[].partition_idintegerSource topic partition ID.
status.partitions[].offset_lag_countintegerNumber of source records pending ingestion for this partition.
status.partitions[].time_lag_knownbooleanWhether time lag is available for this partition.
status.partitions[].time_lag_millisecondsnumber or nullTime lag for this partition in milliseconds. Null when unknown.