API Reference›Streams
API Reference

Streams

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

NameTypeDescription
database_id (required)stringDatabase ID

Request body

NameTypeDescription
columnsStreamColumnHint[]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_daysintegerDays of rows to keep, 1 or more. Stored but not yet enforced.
schemastringSchema of the table. Defaults to the database's default schema.
table (required)stringTable the stream writes to. It must not exist yet.
time_columnstringRow 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_unitstringFormat 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
NameTypeDescription
columns[].name (required)stringRow field the column holds.
columns[].rolestringlarge_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[].typestringColumn 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

NameTypeDescription
column_hintsStreamColumnHint[]Columns the stream was created with. Omitted when there are none.
columnsStreamColumn[]The stream's columns, in table order. Omitted until the first request sets them.
id (required)stringStream ID.
last_flushed_atstringWhen rows were last stored. Null before the first time.
oldest_pending_age_msintegerHow long the oldest of those rows has waited, in milliseconds. Null when none waits.
pending_bytesintegerBytes of accepted rows that the answering server has not stored yet. Null when it holds none.
retention_daysintegerDays of rows to keep. Omitted when none was set.
rows (required)integerRows stored in the table.
schema (required)stringSchema of the stream's table.
status (required)stringwaiting_for_data until the first request, then active.
table (required)stringTable the stream writes to.
time_columnstringRow field that holds each row's time. Null when Hotdata sets the time in _ingested_at.
time_unitstringFormat of time_column: ns, us, ms, s or rfc3339. Null when time_column is null.
Fields of column_hints
NameTypeDescription
column_hints[].name (required)stringRow field the column holds.
column_hints[].rolestringlarge_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[].typestringColumn 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
NameTypeDescription
columns[].fromStreamColumnSource
columns[].indexedbooleanTrue for the large_text column that has a text index. Omitted when false.
columns[].name (required)stringColumn name.
columns[].role (required)stringtime, large_text, normal, map_key or extra.
columns[].type (required)stringColumn 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

StatusDescription
400Invalid table name, time column, time unit or column hint
404Database not found, or streams are not enabled
409A 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

NameTypeDescription
stream_id (required)stringStream ID

Response 200 — The stream

NameTypeDescription
column_hintsStreamColumnHint[]Columns the stream was created with. Omitted when there are none.
columnsStreamColumn[]The stream's columns, in table order. Omitted until the first request sets them.
id (required)stringStream ID.
last_flushed_atstringWhen rows were last stored. Null before the first time.
oldest_pending_age_msintegerHow long the oldest of those rows has waited, in milliseconds. Null when none waits.
pending_bytesintegerBytes of accepted rows that the answering server has not stored yet. Null when it holds none.
retention_daysintegerDays of rows to keep. Omitted when none was set.
rows (required)integerRows stored in the table.
schema (required)stringSchema of the stream's table.
status (required)stringwaiting_for_data until the first request, then active.
table (required)stringTable the stream writes to.
time_columnstringRow field that holds each row's time. Null when Hotdata sets the time in _ingested_at.
time_unitstringFormat of time_column: ns, us, ms, s or rfc3339. Null when time_column is null.
Fields of column_hints
NameTypeDescription
column_hints[].name (required)stringRow field the column holds.
column_hints[].rolestringlarge_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[].typestringColumn 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
NameTypeDescription
columns[].fromStreamColumnSource
columns[].indexedbooleanTrue for the large_text column that has a text index. Omitted when false.
columns[].name (required)stringColumn name.
columns[].role (required)stringtime, large_text, normal, map_key or extra.
columns[].type (required)stringColumn 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

StatusDescription
403The API key is limited to another database
404Stream 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

NameTypeDescription
stream_id (required)stringStream ID

Response 204 — Stream deleted

Errors

StatusDescription
403The API key is limited to another database
404Stream not found, or streams are not enabled
409The 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

NameTypeDescription
stream_id (required)stringStream ID

Request body

NameTypeDescription
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

NameTypeDescription
columnsStreamColumn[]The stream's columns. Present only on the request that sets them.
rows_added (required)integerRows the request added.
Fields of columns
NameTypeDescription
columns[].fromStreamColumnSource
columns[].indexedbooleanTrue for the large_text column that has a text index. Omitted when false.
columns[].name (required)stringColumn name.
columns[].role (required)stringtime, large_text, normal, map_key or extra.
columns[].type (required)stringColumn 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

StatusDescription
400The body has no spans array, a row lacks the time column, or a value does not fit its column
403The API key is limited to another database
404Stream not found, or streams are not enabled
409The stream's table was changed by another writer
429Too many rows are waiting to be stored. Retry shortly.