Streams
Post span or log rows to a table without declaring its columns: a stream's first request sets them.
Create a stream
/v1/databases/{database_id}/streamsCreate 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<T> or map<T>. When omitted, the first request decides it. |
Example request
{
"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<T> or map<T>. 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<T> or map<T>. |
Example response
{
"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
/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<T> or map<T>. 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<T> or map<T>. |
Example response
{
"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
/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
/v1/streams/{stream_id}/spans/ingest/syncAppend 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
{
"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<T> or map<T>. |
Example response
{
"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. |