Models API Reference¶

Pydantic models for type-safe request and response handling.

Trigger Models¶

Trigger ¶

Bases: TriggerResponse

A Honeycomb trigger (response model).

Extends generated TriggerResponse with convenience properties.

NOTE: extra="allow" used only for response model to handle API fields not in spec. NOT for input validation.

dataset `property` ¶

dataset: str

Alias for dataset_slug for convenience.

TriggerCreate `module-attribute` ¶

TriggerCreate = (
    TriggerWithInlineQuery | TriggerWithQueryReference
)

TriggerThreshold `module-attribute` ¶

TriggerThreshold = BaseTriggerThreshold

TriggerThresholdOp `module-attribute` ¶

TriggerThresholdOp = BaseTriggerThresholdOp

TriggerAlertType `module-attribute` ¶

TriggerAlertType = BaseTriggerAlertType

SLO Models¶

SLO ¶

Bases: SLO

A Honeycomb SLO (response model).

Extends the generated SLO model with convenience properties.

dataset `property` ¶

dataset: str | None

Return the dataset to use for API operations.

For multi-dataset SLOs, returns "all" (required for API operations). For single-dataset SLOs, returns the dataset slug.

Returns:

Type	Description
`str \| None`	"all" for multi-dataset SLOs, single slug for single-dataset, None if unset.

datasets `property` ¶

datasets: list[str]

Return the list of datasets this SLO spans.

Returns:

Type	Description
`list[str]`	List of dataset slugs (empty list if unset).

target_percentage `property` ¶

target_percentage: float

Convert target_per_million to percentage for display.

Example

slo.target_per_million = 999000 slo.target_percentage 99.9

Returns:

Type	Description
`float`	Target as a percentage (e.g., 99.9 for 99.9%).

SLOCreate ¶

Bases: SLOCreate

Model for creating a new SLO.

Extends the generated SLOCreate model from the OpenAPI spec. The sli field accepts either a string alias or an SLOCreateSli object.

Example (string alias): >>> slo = SLOCreate( ... name="API Availability", ... sli="success_rate", ... time_period_days=30, ... target_per_million=999000, ... )

Example (explicit SLOCreateSli): >>> slo = SLOCreate( ... name="API Availability", ... sli=SLOCreateSli(alias="success_rate"), ... time_period_days=30, ... target_per_million=999000, ... )

Dataset Models¶

Dataset ¶

Bases: Dataset

A Honeycomb dataset (response model, extends generated Dataset).

DatasetCreate ¶

Bases: DatasetCreationPayload

Model for creating a new dataset (extends generated DatasetCreationPayload).

Board Models¶

Board ¶

Bases: Board

Honeycomb board (response model).

Extends generated Board with convenience methods. Overrides panels field to use wrapper types that handle incomplete API responses.

BoardCreate ¶

Bases: Board

Board creation model.

Uses the generated Board model which has optional id/links. Pydantic will exclude unset fields during serialization.

The Honeycomb Board API only supports flexible boards.

Example

from honeycomb.models.boards import BoardCreate board = BoardCreate( ... name="My Board", ... description="A test board", ... panels=[...], # QueryPanel, SLOPanel, or TextPanel objects ... )

Query Models¶

Query ¶

Bases: BaseModel

A Honeycomb query (response model).

QuerySpec ¶

Bases: Query

Query specification for creating queries.

Extends generated Query with custom validators and builder factory.

NOTE: Use QueryBuilder for constructing queries. Direct instantiation requires generated types (QueryCalculation, QueryFilter, etc.).

Example

QuerySpec.builder().count().last_1_hour().build()

validate_limit `classmethod` ¶

validate_limit(v: int | None) -> int | None

Validate that limit doesn't exceed 1000 for saved queries.

validate_compare_time_offset `classmethod` ¶

validate_compare_time_offset(v: int | None) -> int | None

Validate that compare_time_offset_seconds is a valid offset value.

builder `classmethod` ¶

builder() -> QueryBuilder

Create a QueryBuilder for fluent query construction.

Returns:

Type	Description
`QueryBuilder`	A new QueryBuilder instance

Example

spec = QuerySpec.builder().count().last_1_hour().build()

QueryResult ¶

Bases: QueryResultDetails

Query execution result with accessors.

Extends generated QueryResultDetails with enhanced data property that uses our QueryResultData type with .rows accessor.

Note: data will be None if the query is still processing. Poll until data is not None to get the complete results.

QueryBuilder¶

QueryBuilder ¶

Fluent builder for constructing QuerySpec objects.

The builder provides a chainable API for constructing queries. Each method returns self, allowing method chaining. Call build() to get the final QuerySpec, or build_for_trigger() to get a TriggerQuery with validation.

Examples:

>>> # Simple count query
>>> spec = QueryBuilder().last_1_hour().count().build()

>>> # Complex query with multiple calculations
>>> spec = (
...     QueryBuilder()
...     .last_24_hours()
...     .count()
...     .p99("duration_ms")
...     .avg("duration_ms")
...     .where("status", FilterOp.GREATER_THAN_OR_EQUAL, 500)
...     .breakdown("service", "endpoint")
...     .order_by_count()
...     .build()
... )

>>> # Trigger query (validates time_range <= 3600)
>>> trigger_query = (
...     QueryBuilder()
...     .last_30_minutes()
...     .p99("duration_ms")
...     .build_for_trigger()
... )

time_range ¶

time_range(seconds: int) -> QueryBuilder

Set the query time range in seconds (relative time).

Note: Mutually exclusive with start_time()/end_time(). Setting this clears any absolute time range.

Parameters:

Name	Type	Description	Default
`seconds`	`int`	Time range in seconds (e.g., 3600 for 1 hour)	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

start_time ¶

start_time(timestamp: int) -> QueryBuilder

Set absolute start time as Unix timestamp.

Note: Mutually exclusive with time_range(). Setting this clears any relative time range. Must be used with end_time().

Parameters:

Name	Type	Description	Default
`timestamp`	`int`	Start time as Unix timestamp (seconds since epoch)	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

end_time ¶

end_time(timestamp: int) -> QueryBuilder

Set absolute end time as Unix timestamp.

Note: Mutually exclusive with time_range(). Setting this clears any relative time range. Must be used with start_time().

Parameters:

Name	Type	Description	Default
`timestamp`	`int`	End time as Unix timestamp (seconds since epoch)	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

absolute_time ¶

absolute_time(start: int, end: int) -> QueryBuilder

Set absolute start and end times as Unix timestamps.

Convenience method equivalent to calling start_time(start).end_time(end).

Note: Mutually exclusive with time_range(). Setting this clears any relative time range.

Parameters:

Name	Type	Description	Default
`start`	`int`	Start time as Unix timestamp	required
`end`	`int`	End time as Unix timestamp	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

granularity ¶

granularity(seconds: int) -> QueryBuilder

Set the time granularity for bucketing results.

Parameters:

Name	Type	Description	Default
`seconds`	`int`	Granularity in seconds (e.g., 60 for 1-minute buckets)	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

last_10_minutes ¶

last_10_minutes() -> QueryBuilder

Set time range to last 10 minutes (600 seconds).

last_30_minutes ¶

last_30_minutes() -> QueryBuilder

Set time range to last 30 minutes (1800 seconds).

last_1_hour ¶

last_1_hour() -> QueryBuilder

Set time range to last 1 hour (3600 seconds).

last_2_hours ¶

last_2_hours() -> QueryBuilder

Set time range to last 2 hours (7200 seconds).

last_8_hours ¶

last_8_hours() -> QueryBuilder

Set time range to last 8 hours (28800 seconds).

last_24_hours ¶

last_24_hours() -> QueryBuilder

Set time range to last 24 hours (86400 seconds).

last_1_day ¶

last_1_day() -> QueryBuilder

Set time range to last 1 day (86400 seconds). Alias for last_24_hours().

last_7_days ¶

last_7_days() -> QueryBuilder

Set time range to last 7 days (604800 seconds).

last_14_days ¶

last_14_days() -> QueryBuilder

Set time range to last 14 days (1209600 seconds).

last_28_days ¶

last_28_days() -> QueryBuilder

Set time range to last 28 days (2419200 seconds).

calculate ¶

calculate(
    op: CalcOp | str, column: str | None = None
) -> QueryBuilder

Add a calculation to the query.

Parameters:

Name	Type	Description	Default
`op`	`CalcOp \| str`	Calculation operation (e.g., CalcOp.COUNT, "AVG")	required
`column`	`str \| None`	Column to calculate on (optional for COUNT)	`None`

Returns:

Type	Description
`QueryBuilder`	self for chaining

count ¶

count() -> QueryBuilder

Add a COUNT calculation.

sum ¶

sum(column: str) -> QueryBuilder

Add a SUM calculation on a column.

avg ¶

avg(column: str) -> QueryBuilder

Add an AVG calculation on a column.

min ¶

min(column: str) -> QueryBuilder

Add a MIN calculation on a column.

max ¶

max(column: str) -> QueryBuilder

Add a MAX calculation on a column.

count_distinct ¶

count_distinct(column: str) -> QueryBuilder

Add a COUNT_DISTINCT calculation on a column.

p50 ¶

p50(column: str) -> QueryBuilder

Add a P50 (median) calculation on a column.

p90 ¶

p90(column: str) -> QueryBuilder

Add a P90 calculation on a column.

p95 ¶

p95(column: str) -> QueryBuilder

Add a P95 calculation on a column.

p99 ¶

p99(column: str) -> QueryBuilder

Add a P99 calculation on a column.

heatmap ¶

heatmap(column: str) -> QueryBuilder

Add a HEATMAP calculation on a column.

concurrency ¶

concurrency() -> QueryBuilder

Add a CONCURRENCY calculation.

filter ¶

filter(
    column: str, op: FilterOp | str, value: Any
) -> QueryBuilder

Add a filter to the query.

Parameters:

Name	Type	Description	Default
`column`	`str`	Column to filter on	required
`op`	`FilterOp \| str`	Filter operator (e.g., FilterOp.EQUALS, ">=")	required
`value`	`Any`	Filter value	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

where ¶

where(
    column: str, op: FilterOp | str, value: Any
) -> QueryBuilder

Add a filter to the query. Alias for filter().

Parameters:

Name	Type	Description	Default
`column`	`str`	Column to filter on	required
`op`	`FilterOp \| str`	Filter operator (e.g., FilterOp.EQUALS, ">=")	required
`value`	`Any`	Filter value	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

where_equals ¶

where_equals(column: str, value: Any) -> QueryBuilder

Add an equality filter.

Parameters:

Name	Type	Description	Default
`column`	`str`	Column to filter on	required
`value`	`Any`	Value to match	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

where_exists ¶

where_exists(column: str) -> QueryBuilder

Add a filter for column existence.

Parameters:

Name	Type	Description	Default
`column`	`str`	Column that must exist	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

eq ¶

eq(column: str, value: Any) -> QueryBuilder

Filter where column equals value. Shortcut for where(column, FilterOp.EQUALS, value).

ne ¶

ne(column: str, value: Any) -> QueryBuilder

Filter where column does not equal value. Shortcut for where(column, FilterOp.NOT_EQUALS, value).

gt ¶

gt(column: str, value: Any) -> QueryBuilder

Filter where column > value. Shortcut for where(column, FilterOp.GREATER_THAN, value).

gte ¶

gte(column: str, value: Any) -> QueryBuilder

Filter where column >= value. Shortcut for where(column, FilterOp.GREATER_THAN_OR_EQUAL, value).

lt ¶

lt(column: str, value: Any) -> QueryBuilder

Filter where column < value. Shortcut for where(column, FilterOp.LESS_THAN, value).

lte ¶

lte(column: str, value: Any) -> QueryBuilder

Filter where column <= value. Shortcut for where(column, FilterOp.LESS_THAN_OR_EQUAL, value).

starts_with ¶

starts_with(column: str, value: str) -> QueryBuilder

Filter where column starts with value.

does_not_start_with ¶

does_not_start_with(
    column: str, value: str
) -> QueryBuilder

Filter where column does not start with value.

contains ¶

contains(column: str, value: str) -> QueryBuilder

Filter where column contains value.

does_not_contain ¶

does_not_contain(column: str, value: str) -> QueryBuilder

Filter where column does not contain value.

exists ¶

exists(column: str) -> QueryBuilder

Filter where column exists.

does_not_exist ¶

does_not_exist(column: str) -> QueryBuilder

Filter where column does not exist.

is_in ¶

is_in(column: str, values: list[Any]) -> QueryBuilder

Filter where column is in a list of values.

not_in ¶

not_in(column: str, values: list[Any]) -> QueryBuilder

Filter where column is not in a list of values.

filter_with ¶

filter_with(
    combination: FilterCombination | str,
) -> QueryBuilder

Set how multiple filters are combined.

Parameters:

Name	Type	Description	Default
`combination`	`FilterCombination \| str`	FilterCombination.AND or FilterCombination.OR	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

breakdown ¶

breakdown(*columns: str) -> QueryBuilder

Add columns to group results by.

Parameters:

Name	Type	Description	Default
`*columns`	`str`	Column names to group by	`()`

Returns:

Type	Description
`QueryBuilder`	self for chaining

group_by ¶

group_by(*columns: str) -> QueryBuilder

Add columns to group results by. Alias for breakdown().

Parameters:

Name	Type	Description	Default
`*columns`	`str`	Column names to group by	`()`

Returns:

Type	Description
`QueryBuilder`	self for chaining

order_by ¶

order_by(
    op: CalcOp | str,
    direction: (
        OrderDirection | str
    ) = OrderDirection.descending,
    column: str | None = None,
) -> QueryBuilder

Add an ordering specification.

Parameters:

Name	Type	Description	Default
`op`	`CalcOp \| str`	Calculation to order by	required
`direction`	`OrderDirection \| str`	Sort direction (default: descending)	`descending`
`column`	`str \| None`	Column for the calculation (if applicable)	`None`

Returns:

Type	Description
`QueryBuilder`	self for chaining

order_by_count ¶

order_by_count(
    direction: (
        OrderDirection | str
    ) = OrderDirection.descending,
) -> QueryBuilder

Order results by COUNT.

Parameters:

Name	Type	Description	Default
`direction`	`OrderDirection \| str`	Sort direction (default: descending)	`descending`

Returns:

Type	Description
`QueryBuilder`	self for chaining

limit ¶

limit(n: int) -> QueryBuilder

Set the maximum number of results.

Parameters:

Name	Type	Description	Default
`n`	`int`	Maximum number of results (max 1000 for saved queries)	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

having ¶

having(
    calculate_op: CalcOp | str,
    op: FilterOp | str,
    value: float,
    column: str | None = None,
) -> QueryBuilder

Add a having clause for post-aggregation filtering.

Parameters:

Name	Type	Description	Default
`calculate_op`	`CalcOp \| str`	Calculation to filter on	required
`op`	`FilterOp \| str`	Comparison operator	required
`value`	`float`	Threshold value	required
`column`	`str \| None`	Column for the calculation (if applicable)	`None`

Returns:

Type	Description
`QueryBuilder`	self for chaining

calculated_field ¶

calculated_field(
    name: str, expression: str
) -> QueryBuilder

Add an inline calculated field (derived column) for this query only.

Creates a computed column available within this query. For reusable derived columns, use the Derived Columns API instead.

Parameters:

Name	Type	Description	Default
`name`	`str`	Field name/alias to reference in calculations and breakdowns	required
`expression`	`str`	Formula using $column_name syntax See https://docs.honeycomb.io/reference/derived-column-formula/	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

Example

(QueryBuilder() ... .calculated_field("latency_bucket", ... "IF(LTE($duration_ms, 100), 'fast', 'slow')") ... .group_by("latency_bucket") ... .count())

compare_time_offset ¶

compare_time_offset(seconds: int) -> QueryBuilder

Compare against historical data offset by N seconds.

When set, the query results will include comparison data from the specified time in the past.

Parameters:

Name	Type	Description	Default
`seconds`	`int`	Offset in seconds. Must be one of: 1800 (30min), 3600 (1hr), 7200 (2hr), 28800 (8hr), 86400 (24hr), 604800 (7d), 2419200 (28d), 15724800 (6mo)	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

Example

QueryBuilder().last_1_hour().count().compare_time_offset(86400) # Compare to 24h ago

dataset ¶

dataset(dataset_slug: str) -> QueryBuilder

Set dataset scope for this query.

Parameters:

Name	Type	Description	Default
`dataset_slug`	`str`	Dataset slug to query against	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

Example

QueryBuilder().dataset("api-logs").last_1_hour().count()

environment_wide ¶

environment_wide() -> QueryBuilder

Mark query as environment-wide (all datasets).

Returns:

Type	Description
`QueryBuilder`	self for chaining

Example

QueryBuilder().environment_wide().last_1_hour().count()

get_dataset ¶

get_dataset() -> str

Get dataset scope (defaults to "all" if not set).

Returns:

Type	Description
`str`	Dataset slug or "all" for environment-wide

description ¶

description(desc: str) -> QueryBuilder

Set query description (optional).

For boards: This becomes the query annotation description.

Parameters:

Name	Type	Description	Default
`desc`	`str`	Query description (max 1023 chars)	required

Returns:

Type	Description
`QueryBuilder`	self for chaining

Example

(QueryBuilder("Request Count") ... .dataset("api-logs") ... .last_1_hour() ... .count() ... .description("Total requests over 24 hours"))

has_name ¶

has_name() -> bool

Check if query has name set.

Returns:

Type	Description
`bool`	True if name is set

get_name ¶

get_name() -> str | None

Get query name.

Returns:

Type	Description
`str \| None`	Query name or None

get_description ¶

get_description() -> str | None

Get query description.

Returns:

Type	Description
`str \| None`	Query description or None

build ¶

build() -> QuerySpec

Build a QuerySpec from the builder state.

Converts builder component types (Calculation, Filter, Order, Having) to generated API types (QueryCalculation, QueryFilter, etc.).

Returns:

Type	Description
`QuerySpec`	A QuerySpec configured with the builder's settings

Raises:

Type	Description
`ValueError`	If only one of start_time/end_time is set (must use both)

build_for_trigger ¶

build_for_trigger() -> dict[str, Any]

Build a trigger query dict from the builder state.

Trigger queries have additional constraints: - time_range must be <= 3600 seconds (1 hour) - No absolute time support - No orders, havings, or limit

Returns:

Type	Description
`dict[str, Any]`	A dict representing the inline query for triggers

Raises:

Type	Description
`ValueError`	If time_range > 3600 or absolute time is set

Calculation ¶

Bases: BaseModel

A calculation in a query.

Examples:

>>> Calculation(op=CalcOp.COUNT)
>>> Calculation(op=CalcOp.P99, column="duration_ms")
>>> Calculation(op="AVG", column="response_time")

validate_column_requirement ¶

validate_column_requirement() -> Self

Validate that column is provided when required by the operation.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to API dict format.

Filter ¶

Bases: BaseModel

A filter in a query.

Examples:

>>> Filter(column="status", op=FilterOp.EQUALS, value=200)
>>> Filter(column="error", op=FilterOp.EXISTS)  # No value needed
>>> Filter(column="service", op="in", value=["api", "web"])

validate_value_requirement ¶

validate_value_requirement() -> Self

Validate value is not provided for existence check operations.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to API dict format.

Order ¶

Bases: BaseModel

An ordering specification for query results.

Examples:

>>> Order(op=CalcOp.COUNT, order=OrderDirection.descending)
>>> Order(op=CalcOp.AVG, column="duration_ms", order=OrderDirection.ascending)

validate_column_requirement ¶

validate_column_requirement() -> Self

Validate that column is provided when required by the operation.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to API dict format.

Having ¶

Bases: BaseModel

A having clause for post-aggregation filtering.

Examples:

>>> Having(calculate_op=CalcOp.COUNT, op=FilterOp.GREATER_THAN, value=100)
>>> Having(calculate_op=CalcOp.AVG, column="duration_ms", op=">", value=500.0)

validate_column_requirement ¶

validate_column_requirement() -> Self

Validate that column is provided when required by the operation.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to API dict format.

CalcOp `module-attribute` ¶

CalcOp = QueryOp

FilterOp ¶

Bases: Enum

OrderDirection `module-attribute` ¶

OrderDirection = QueryOrderOrder

FilterCombination `module-attribute` ¶

FilterCombination = QueryFilterCombination

Models API Reference¶

Trigger Models¶

Trigger ¶

dataset property ¶

TriggerCreate module-attribute ¶

TriggerThreshold module-attribute ¶

TriggerThresholdOp module-attribute ¶

TriggerAlertType module-attribute ¶

SLO Models¶

SLO ¶

dataset property ¶

datasets property ¶

target_percentage property ¶

SLOCreate ¶

Dataset Models¶

Dataset ¶

DatasetCreate ¶

Board Models¶

Board ¶

BoardCreate ¶

Query Models¶

Query ¶

QuerySpec ¶

validate_limit classmethod ¶

validate_compare_time_offset classmethod ¶

builder classmethod ¶

QueryResult ¶

QueryBuilder¶

QueryBuilder ¶

time_range ¶

start_time ¶

end_time ¶

absolute_time ¶

granularity ¶

last_10_minutes ¶

last_30_minutes ¶

last_1_hour ¶

last_2_hours ¶

last_8_hours ¶

last_24_hours ¶

last_1_day ¶

last_7_days ¶

last_14_days ¶

last_28_days ¶

calculate ¶

count ¶

sum ¶

avg ¶

min ¶

max ¶

count_distinct ¶

p50 ¶

p90 ¶

p95 ¶

p99 ¶

heatmap ¶

concurrency ¶

filter ¶

where ¶

where_equals ¶

where_exists ¶

eq ¶

ne ¶

gt ¶

gte ¶

lt ¶

lte ¶

starts_with ¶

does_not_start_with ¶

contains ¶

does_not_contain ¶

exists ¶

does_not_exist ¶

is_in ¶

not_in ¶

filter_with ¶

breakdown ¶

group_by ¶

order_by ¶

order_by_count ¶

dataset `property` ¶

TriggerCreate `module-attribute` ¶

TriggerThreshold `module-attribute` ¶

TriggerThresholdOp `module-attribute` ¶

TriggerAlertType `module-attribute` ¶

dataset `property` ¶

datasets `property` ¶

target_percentage `property` ¶

validate_limit `classmethod` ¶

validate_compare_time_offset `classmethod` ¶

builder `classmethod` ¶

CalcOp `module-attribute` ¶

OrderDirection `module-attribute` ¶

FilterCombination `module-attribute` ¶