# Streams Source: https://www.hotdata.dev/docs/api-reference/streams Site index: https://www.hotdata.dev/llms.txt Post span or log rows to a table without declaring its columns: a stream's first request sets them. ## Create a stream `POST /v1/databases/{database_id}/streams` Create a stream: a table you post span or log rows to without declaring its columns. The first request sets the columns from its rows. Each key becomes a column typed from its values, and each key inside an object field also gets its own `field.key` column. Use `columns` to set a column's type or role in advance. The table is partitioned by day of its time column. With no `time_column`, Hotdata adds `_ingested_at` and sets it to the time each request arrives. The stream's status is `waiting_for_data` until the first request. Streams are available only where they are enabled. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `database_id` *(required)* | `string` | Database ID | **Request body** | Name | Type | Description | | --- | --- | --- | | `columns` | `StreamColumnHint`[] | Columns to define up front, for fields the first rows may lack or whose type or role they cannot show. Other columns come from the first request. | | `retention_days` | `integer` | Days of rows to keep, 1 or more. Stored but not yet enforced. | | `schema` | `string` | Schema of the table. Defaults to the database's default schema. | | `table` *(required)* | `string` | Table the stream writes to. It must not exist yet. | | `time_column` | `string` | Row field that holds each row's time; every row must have it. Omit it and `time_unit` to have Hotdata add an `_ingested_at` column with the time each request arrived. | | `time_unit` | `string` | Format of `time_column`: `ns`, `us`, `ms` or `s` for an integer since the Unix epoch, or `rfc3339` for text. Required with `time_column`, and only allowed with it. | **Fields of `columns`** | Name | Type | Description | | --- | --- | --- | | `columns[].name` *(required)* | `string` | Row field the column holds. | | `columns[].role` | `string` | `large_text` or `normal`. A `large_text` column is stored separately, so queries that do not use it do not read it. When omitted, the first request decides it. | | `columns[].type` | `string` | Column type: `string`, `int64`, `float64`, `boolean`, `timestamp(ns)`, `timestamp(us)`, `timestamp(ms)`, `timestamp(s)`, `list` or `map`. When omitted, the first request decides it. | **Example request** ```json { "columns": [ { "name": "IngestedAt", "role": "normal", "type": "timestamp(ns)" } ], "retention_days": 30, "schema": "public", "table": "traces", "time_column": "Timestamp", "time_unit": "ns" } ``` **Response** `201` — Stream created | Name | Type | Description | | --- | --- | --- | | `column_hints` | `StreamColumnHint`[] | Columns the stream was created with. Omitted when there are none. | | `columns` | `StreamColumn`[] | The stream's columns, in table order. Omitted until the first request sets them. | | `id` *(required)* | `string` | Stream ID. | | `last_flushed_at` | `string` | When rows were last stored. Null before the first time. | | `oldest_pending_age_ms` | `integer` | How long the oldest of those rows has waited, in milliseconds. Null when none waits. | | `pending_bytes` | `integer` | Bytes of accepted rows that the answering server has not stored yet. Null when it holds none. | | `retention_days` | `integer` | Days of rows to keep. Omitted when none was set. | | `rows` *(required)* | `integer` | Rows stored in the table. | | `schema` *(required)* | `string` | Schema of the stream's table. | | `status` *(required)* | `string` | `waiting_for_data` until the first request, then `active`. | | `table` *(required)* | `string` | Table the stream writes to. | | `time_column` | `string` | Row field that holds each row's time. Null when Hotdata sets the time in `_ingested_at`. | | `time_unit` | `string` | Format of `time_column`: `ns`, `us`, `ms`, `s` or `rfc3339`. Null when `time_column` is null. | **Fields of `column_hints`** | Name | Type | Description | | --- | --- | --- | | `column_hints[].name` *(required)* | `string` | Row field the column holds. | | `column_hints[].role` | `string` | `large_text` or `normal`. A `large_text` column is stored separately, so queries that do not use it do not read it. When omitted, the first request decides it. | | `column_hints[].type` | `string` | Column type: `string`, `int64`, `float64`, `boolean`, `timestamp(ns)`, `timestamp(us)`, `timestamp(ms)`, `timestamp(s)`, `list` or `map`. When omitted, the first request decides it. | **Fields of `columns`** | Name | Type | Description | | --- | --- | --- | | `columns[].from` | `StreamColumnSource` | | | `columns[].indexed` | `boolean` | True for the `large_text` column that has a text index. Omitted when false. | | `columns[].name` *(required)* | `string` | Column name. | | `columns[].role` *(required)* | `string` | `time`, `large_text`, `normal`, `map_key` or `extra`. | | `columns[].type` *(required)* | `string` | Column type: `string`, `int64`, `float64`, `boolean`, `timestamp(ns)`, `timestamp(us)`, `timestamp(ms)`, `timestamp(s)`, `list` or `map`. | **Example response** ```json { "column_hints": [ { "name": "IngestedAt", "role": "normal", "type": "timestamp(ns)" } ], "columns": [ { "from": { "key": "string", "map": "string" }, "indexed": true, "name": "string", "role": "string", "type": "string" } ], "id": "string", "last_flushed_at": "2026-01-01T00:00:00Z", "oldest_pending_age_ms": 0, "pending_bytes": 0, "retention_days": 0, "rows": 0, "schema": "string", "status": "string", "table": "string", "time_column": "string", "time_unit": "string" } ``` **Errors** | Status | Description | | ------ | ----------- | | `400` | Invalid table name, time column, time unit or column hint | | `404` | Database not found, or streams are not enabled | | `409` | A table of that name already exists | ## Get a stream `GET /v1/streams/{stream_id}` Get a stream: its table, status, time column and column hints. After the first request, it also lists each column with its type and role: `time`, `large_text`, `normal`, `map_key` or `extra`. A `map_key` column holds one key of an object field; `from` names the field and key. The `_extra` column keeps, as JSON text, any field that has no column and any value of the wrong type for its column. `pending_bytes` and `oldest_pending_age_ms` describe accepted rows that the answering server has not stored yet; both are null when it holds none. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `stream_id` *(required)* | `string` | Stream ID | **Response** `200` — The stream | Name | Type | Description | | --- | --- | --- | | `column_hints` | `StreamColumnHint`[] | Columns the stream was created with. Omitted when there are none. | | `columns` | `StreamColumn`[] | The stream's columns, in table order. Omitted until the first request sets them. | | `id` *(required)* | `string` | Stream ID. | | `last_flushed_at` | `string` | When rows were last stored. Null before the first time. | | `oldest_pending_age_ms` | `integer` | How long the oldest of those rows has waited, in milliseconds. Null when none waits. | | `pending_bytes` | `integer` | Bytes of accepted rows that the answering server has not stored yet. Null when it holds none. | | `retention_days` | `integer` | Days of rows to keep. Omitted when none was set. | | `rows` *(required)* | `integer` | Rows stored in the table. | | `schema` *(required)* | `string` | Schema of the stream's table. | | `status` *(required)* | `string` | `waiting_for_data` until the first request, then `active`. | | `table` *(required)* | `string` | Table the stream writes to. | | `time_column` | `string` | Row field that holds each row's time. Null when Hotdata sets the time in `_ingested_at`. | | `time_unit` | `string` | Format of `time_column`: `ns`, `us`, `ms`, `s` or `rfc3339`. Null when `time_column` is null. | **Fields of `column_hints`** | Name | Type | Description | | --- | --- | --- | | `column_hints[].name` *(required)* | `string` | Row field the column holds. | | `column_hints[].role` | `string` | `large_text` or `normal`. A `large_text` column is stored separately, so queries that do not use it do not read it. When omitted, the first request decides it. | | `column_hints[].type` | `string` | Column type: `string`, `int64`, `float64`, `boolean`, `timestamp(ns)`, `timestamp(us)`, `timestamp(ms)`, `timestamp(s)`, `list` or `map`. When omitted, the first request decides it. | **Fields of `columns`** | Name | Type | Description | | --- | --- | --- | | `columns[].from` | `StreamColumnSource` | | | `columns[].indexed` | `boolean` | True for the `large_text` column that has a text index. Omitted when false. | | `columns[].name` *(required)* | `string` | Column name. | | `columns[].role` *(required)* | `string` | `time`, `large_text`, `normal`, `map_key` or `extra`. | | `columns[].type` *(required)* | `string` | Column type: `string`, `int64`, `float64`, `boolean`, `timestamp(ns)`, `timestamp(us)`, `timestamp(ms)`, `timestamp(s)`, `list` or `map`. | **Example response** ```json { "column_hints": [ { "name": "IngestedAt", "role": "normal", "type": "timestamp(ns)" } ], "columns": [ { "from": { "key": "string", "map": "string" }, "indexed": true, "name": "string", "role": "string", "type": "string" } ], "id": "string", "last_flushed_at": "2026-01-01T00:00:00Z", "oldest_pending_age_ms": 0, "pending_bytes": 0, "retention_days": 0, "rows": 0, "schema": "string", "status": "string", "table": "string", "time_column": "string", "time_unit": "string" } ``` **Errors** | Status | Description | | ------ | ----------- | | `403` | The API key is limited to another database | | `404` | Stream not found, or streams are not enabled | ## Delete a stream `DELETE /v1/streams/{stream_id}` Delete a stream, its table and all its rows, including rows not stored yet. Requests to the stream return 404 as soon as the delete starts. When it finishes, the table name can be used again. If the delete fails, retry it. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `stream_id` *(required)* | `string` | Stream ID | **Response** `204` — Stream deleted **Errors** | Status | Description | | ------ | ----------- | | `403` | The API key is limited to another database | | `404` | Stream not found, or streams are not enabled | | `409` | The stream's table is busy. Retry shortly. | ## Append rows to a stream `POST /v1/streams/{stream_id}/spans/ingest/sync` Append rows to a stream. The body is a JSON object with a `spans` array of rows, up to 64 MiB. The first request sets the stream's columns and returns them. After that, fields match columns by name. A missing field is null. A field with no column, or a value of the wrong type, goes to the `_extra` column. Every row must carry the time column, unless Hotdata sets `_ingested_at`. The call returns once the rows are accepted; they can be queried within seconds. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `stream_id` *(required)* | `string` | Stream ID | **Request body** | Name | Type | Description | | --- | --- | --- | | `spans` *(required)* | `object`[] | Rows to append. Each row is an object of field names to values. | **Example request** ```json { "spans": [ { "Timestamp": 1763510400000000000, "SpanId": "a1b2", "Duration": 42 } ] } ``` **Response** `200` — Rows appended | Name | Type | Description | | --- | --- | --- | | `columns` | `StreamColumn`[] | The stream's columns. Present only on the request that sets them. | | `rows_added` *(required)* | `integer` | Rows the request added. | **Fields of `columns`** | Name | Type | Description | | --- | --- | --- | | `columns[].from` | `StreamColumnSource` | | | `columns[].indexed` | `boolean` | True for the `large_text` column that has a text index. Omitted when false. | | `columns[].name` *(required)* | `string` | Column name. | | `columns[].role` *(required)* | `string` | `time`, `large_text`, `normal`, `map_key` or `extra`. | | `columns[].type` *(required)* | `string` | Column type: `string`, `int64`, `float64`, `boolean`, `timestamp(ns)`, `timestamp(us)`, `timestamp(ms)`, `timestamp(s)`, `list` or `map`. | **Example response** ```json { "columns": [ { "from": { "key": "string", "map": "string" }, "indexed": true, "name": "string", "role": "string", "type": "string" } ], "rows_added": 0 } ``` **Errors** | Status | Description | | ------ | ----------- | | `400` | The body has no `spans` array, a row lacks the time column, or a value does not fit its column | | `403` | The API key is limited to another database | | `404` | Stream not found, or streams are not enabled | | `409` | The stream's table was changed by another writer | | `429` | Too many rows are waiting to be stored. Retry shortly. |