> For the complete documentation index, see [llms.txt](https://docs.warpstream.com/warpstream/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.warpstream.com/warpstream/reference/api-reference/tableflow/get-table.md). # 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. | {% hint style="warning" %} **Exactly one** of `table_uuid` or `table_name` must be specified. Providing both or neither will return an error. {% endhint %} #### 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.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.warpstream.com/warpstream/reference/api-reference/tableflow/get-table.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.