Explore documentation
  1. Welcome to Warehouse 👋
  2. Ingesting data
    1. Ingesting events
    2. S3 vs NVMe hosted data
    3. Host events in your S3 bucket
  3. Querying data
    1. Querying events & time series
    2. Writing ClickHouse SQL queries
    3. Query speeds
    4. Ad-hoc SQL API
    5. Generate client-facing APIs
    6. Visualizing data
  4. Vector embeddings
    1. Introduction to embeddings
    2. Using built-in embeddings
    3. Bringing your own embeddings
    4. Data structures and indices
  5. Use cases
    1. Retrieval Augmented Generation
  6. Management
    1. Controlling costs
  7. Warehouse API
    1. Getting an API token
    2. Warehouse sources API
    3. Warehouse source groups API
    4. Time series API
      1. List all time series GET
      2. Create a time series POST
      3. Remove a time series DELETE
    5. Embeddings API

Create a time series

Creates a new computed time series for a Warehouse source.

POST https://warehouse.betterstack.com/api/v1/sources/{source_id}/time_series

URL parameters

source_id
required string

The ID of the Warehouse source to create the time series for.

Headers

Authorization
required string

Bearer $TOKEN

Content-Type
required string

application/json

Body parameters

name
required string

The name of the time series. Must contain only letters, numbers, and underscores.

type
required string

The data type of the time series. Valid types are: string, string_low_cardinality, int64_delta, int64, uint64_delta, uint64, float64_delta, datetime64_delta, boolean, array_bfloat16, array_float32.

sql_expression
required string

The SQL expression used to compute the time series. For example JSONExtract(raw, 'response_time', 'Nullable(Float64)').

aggregations
array

An array of aggregation functions (e.g., avg, min, max). If omitted, no aggregations are applied.

expression_index
string

The type of vector index to apply (e.g., vector_similarity). Only applicable for vector types (array_bfloat16, array_float32).

vector_dimension
integer

The vector dimension if expression_index is vector_similarity (e.g., 512). Supported values: 256, 384, 512, 768, 1024, 1536, 3072, 4096, 10752.

vector_distance_function
string

The distance function to use for vector similarity (e.g., cosine, l2).

201

The newly created time series configuration.

Response body

{
  "data": {
    "id": "5215107",
    "type": "time_series",
    "attributes": {
      "name": "level",
      "sql_expression": "JSONExtract(raw, 'level', 'Nullable(String)')",
      "aggregations": [],
      "type": "string_low_cardinality",
      "expression_index": null
    }
  }
}
401

Unauthorized

Response body

{
  "errors": "Invalid authentication"
}
404

Not Found

Response body

{
  "errors": "Source with the provided ID was not found"
}
422

Unprocessable Entity - Validation Errors

Response body

{
  "errors": "Validation errors",
  "invalid_values": {
    "name": [
      "name must only contain letters, numbers, and underscores"
    ],
    "type": [
      "type must be one of string, string_low_cardinality, int64_delta, int64, uint64_delta, uint64, float64_delta, datetime64_delta, boolean, array_bfloat16, array_float32"
    ],
    "sql_expression": [
      "sql_expression is invalid"
    ]
  }
}

Example cURL

Example
curl --request POST \
  --url https://warehouse.betterstack.com/api/v1/sources/12345/time_series \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "response_time_avg",
    "type": "float64_delta",
    "sql_expression": "JSONExtract(raw, 'response_time', 'Nullable(Float64)')",
    "aggregations": ["avg", "min", "max"]
  }'

Previous article

List all time series

Next article

Remove a time series