# Create a time series

Creates a new computed time series for a Warehouse source.

[endpoint]
base_url = "https://warehouse.betterstack.com"
path = "/api/v1/sources/{source_id}/time_series"
method = "POST"

[[path_param]]
name = "source_id"
description = "The ID of the Warehouse source to create the time series for."
required = true
type = "string"

[[body_param]]
name = "name"
description = "The name of the time series. Must contain only letters, numbers, and underscores."
required = true
type = "string"

[[body_param]]
name = "type"
description = "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`."
required = true
type = "string"

[[body_param]]
name = "sql_expression"
description = "The SQL expression used to compute the time series. For example `JSONExtract(raw, 'response_time', 'Nullable(Float64)')`."
required = true
type = "string"

[[body_param]]
name = "aggregations"
description = "An array of aggregation functions (e.g., `avg`, `min`, `max`). If omitted, no aggregations are applied."
required = false
type = "array"

[[body_param]]
name = "expression_index"
description = "The type of vector index to apply (e.g., `vector_similarity`). Only applicable for vector types (`array_bfloat16`, `array_float32`)."
required = false
type = "string"

[[body_param]]
name = "vector_dimension"
description = "The vector dimension if `expression_index` is `vector_similarity` (e.g., `512`). Supported values: 256, 384, 512, 768, 1024, 1536, 3072, 4096, 10752."
required = false
type = "integer"

[[body_param]]
name = "vector_distance_function"
description = "The distance function to use for vector similarity (e.g., `cosine`, `l2`)."
required = false
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''The newly created time series configuration.'''
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
    }
  }
}'''

[[response]]
status = 401
description = '''Unauthorized'''
body = '''{
  "errors": "Invalid authentication"
}'''

[[response]]
status = 404
description = '''Not Found'''
body = '''{
  "errors": "Source with the provided ID was not found"
}'''

[[response]]
status = 422
description = '''Unprocessable Entity - Validation Errors'''
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"]
  }
}'''
[/responses]

#### Example cURL

```shell
[label 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"]
  }'
```