POST /accounts/{account_id}/workers/observability/telemetry/query

Your Cloudflare account ID.

Default value: "application/json"

When true, executes the query without persisting the results. Useful for validation or previewing.

Default value: false

When true, omits time-series data from the response and returns only aggregated values. Reduces response size when series are not needed.

Default value: false

Timeframe for the query using Unix timestamps in milliseconds. Narrower timeframes produce faster responses and more specific results.

End timestamp for the query timeframe (Unix timestamp in milliseconds)

Start timestamp for the query timeframe (Unix timestamp in milliseconds)

Query parameters defining what data to retrieve — filters, calculations, group-bys, and ordering. In practice this should always be provided for ad-hoc queries. Only omit when executing a previously saved query by queryId. Use the keys and values endpoints to discover available fields before building filters.

Datasets to query. Leave empty to query all available datasets.

Filters to narrow query results. Use the keys and values endpoints to discover available fields before building filters. Supports nested groups via kind: 'group'. Maximum nesting depth is 4.

Child filter nodes. Each can be a leaf filter or another nested group.

Logical operator for combining child filters: 'and' (all must match) or 'or' (any must match).

Valid values:

• "AND"
• "and"
• "or"
• "OR"

Filter field name. Use verified keys from previous query results or the keys endpoint. Common keys include $metadata.service, $metadata.origin, $metadata.trigger, $metadata.message, and $metadata.error.

Comparison operator. String operators: includes, not_includes, starts_with, ends_with, regex. Existence: exists, is_null. Set membership: in, not_in (comma-separated values). Numeric: eq, neq, gt, gte, lt, lte.

Valid values:

• "not_in"
• "eq"
• "regex"
• ">"
• "NOT_IN"
• "is_null"
• "<"
• "ends_with"
• "INCLUDES"
• "!="
• "<="
• "includes"
• "lte"
• "not_includes"
• "MATCH_REGEX"
• "starts_with"
• "gt"
• "gte"
• "exists"
• "="
• "EXISTS"
• "lt"
• "in"
• "IN"
• "DOES_NOT_INCLUDE"
• ">="
• "DOES_NOT_EXIST"
• "ENDS_WITH"
• "neq"
• "STARTS_WITH"

Data type of the filter field. Must match the actual type of the key being filtered.

Valid values:

• "string"
• "boolean"
• "number"

Comparison value. Must match actual values in your data — verify with the values endpoint. Ensure the value type (string/number/boolean) matches the field type. String comparisons are case-sensitive. Regex uses RE2 syntax (no lookaheads/lookbehinds).

Discriminator for leaf filter nodes. Always 'filter' when present; may be omitted.

Valid values:

• "filter"

Maximum number of group-by rows to return in calculation results. A value of 10 is a sensible default for most use cases.

Logical operator for combining top-level filters: 'and' (all must match) or 'or' (any must match). Defaults to 'and'.

Valid values:

• "AND"
• "and"
• "or"
• "OR"

Ordering for grouped calculation results. Only effective when a group-by is present.

Sort direction: 'asc' for ascending, 'desc' for descending.

Valid values:

• "desc"
• "asc"

Alias of the calculation to order results by. Must match the alias (or operator) of a calculation in the query.

Full-text search expression applied across all event fields. Matches events containing the specified text.

The text or pattern to search for.

When true, performs a case-sensitive search. Defaults to case-insensitive.

When true, treats the value as a regular expression (RE2 syntax).

Fields to group calculation results by. Only applicable when the query view is 'calculations'. Produces per-group aggregate values.

Data type of the group-by field.

Valid values:

• "string"
• "boolean"
• "number"

Field name to group results by (e.g. $metadata.service, $metadata.statusCode).

Post-aggregation filters applied to calculation results. Use to filter groups after aggregation (e.g. only groups where count > 100).

Calculation alias or operator to filter on after aggregation.

Numeric comparison operator: eq, neq, gt, gte, lt, lte.

Valid values:

• "gt"
• "gte"
• "eq"
• "lte"
• "neq"
• "lt"

Threshold value to compare the calculation result against.

Aggregation calculations to compute (e.g. count, avg, p99). Each calculation produces aggregate values and optional time-series data.

Aggregation operator to apply. Examples: count, avg, sum, min, max, median, p90, p95, p99, uniq, stddev, variance.

Valid values:

• "count"
• "MAX"
• "p10"
• "COUNT_DISTINCT"
• "P05"
• "sum"
• "median"
• "p90"
• "P99"
• "MIN"
• "P999"
• "P75"
• "P25"
• "P01"
• "stddev"
• "p001"
• "COUNT"
• "P95"
• "VARIANCE"
• "min"
• "p01"
• "p25"
• "p75"
• "p99"
• "p95"
• "STDDEV"
• "AVG"
• "MEDIAN"
• "P10"
• "max"
• "variance"
• "uniq"
• "P90"
• "p05"
• "P001"
• "avg"
• "p999"
• "SUM"

Field name to calculate over. Must exist in the data — verify with the keys endpoint. Omit for operators that don't require a key (e.g. count).

Data type of the key. Required when key is provided to ensure correct aggregation.

Valid values:

• "string"
• "boolean"
• "number"

Custom label for this calculation in the results. Useful for distinguishing multiple calculations.

Controls the shape of the response. 'events': individual log lines matching the query. 'calculations': aggregated metrics (count, avg, p99, etc.) with optional group-by breakdowns and time-series. 'invocations': events grouped by request ID. 'traces': distributed trace summaries. 'agents': Durable Object agent summaries.

Valid values:

• "requests"
• "calculations"
• "agents"
• "traces"
• "events"
• "invocations"

Default value: "calculations"

Numeric offset for paginating grouped/pattern results (top-N lists). Use together with limit. Not used by cursor-based pagination.

When true, includes time-series data in the response.

Maximum number of events to return when view is 'events'. Also controls the number of group-by rows when view is 'calculations'.

Default value: 50

Identifier for the query. When parameters are omitted, this ID is used to load a previously saved query's parameters. When providing parameters inline, pass any identifier (e.g. an ad-hoc ID).

Pagination direction: 'next' for forward, 'prev' for backward.

Number of time-series buckets. Only used when view is 'calculations'. Omit to let the system auto-detect an appropriate granularity.

When true, includes a comparison dataset from the previous time period of equal length.

Cursor for pagination in event, trace, and invocation views. Pass the $metadata.id of the last returned item to fetch the next page.