Run a query

client.workers.observability.telemetry.query(, ?): TelemetryQueryResponse { run, statistics, agents, 5 more }

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

Run a temporary or saved query.

Security

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

User Service Key

Used when interacting with the Origin CA certificates API. View/change your key.

Example:

X-Auth-User-Service-Key: v1.0-144c9defac04969c7bfad8ef-631a41d003a32d25fe878081ef365c49503f7fada600da935e2851a1c7326084b85cbf6429c4b859de8475731dc92a9c329631e6d59e6c73da7b198497172b4cefe071d90d0f5d2719

Accepted Permissions (at least one required)

Workers Observability Write

ParametersExpand Collapse

params: TelemetryQueryParams { account_id, queryId, timeframe, 11 more }

account_id: string

Path param: Your Cloudflare account ID.

queryId: string

Body param: 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).

timeframe: Timeframe

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

from: number

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

to: number

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

chart?: boolean

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

compare?: boolean

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

dry?: boolean

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

granularity?: number

Body param: Number of time-series buckets. Only used when view is ‘calculations’. Omit to let the system auto-detect an appropriate granularity.

ignoreSeries?: boolean

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

limit?: number

Body param: Maximum number of events to return when view is ‘events’. Also controls the number of group-by rows when view is ‘calculations’.

maximum2000

offset?: string

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

offsetBy?: number

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

offsetDirection?: string

Body param: Pagination direction: ‘next’ for forward, ‘prev’ for backward.

parameters?: Parameters

Body param: 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.

calculations?: Array<Calculation>

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

operator: "uniq" | "count" | "max" | 35 more

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

One of the following:

"uniq"

"count"

"max"

"min"

"sum"

"avg"

"median"

"p001"

"p01"

"p05"

"p10"

"p25"

"p75"

"p90"

"p95"

"p99"

"p999"

"stddev"

"variance"

"COUNT_DISTINCT"

"COUNT"

"MAX"

"MIN"

"SUM"

"AVG"

"MEDIAN"

"P001"

"P01"

"P05"

"P10"

"P25"

"P75"

"P90"

"P95"

"P99"

"P999"

"STDDEV"

"VARIANCE"

alias?: string

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

key?: string

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).

keyType?: "string" | "number" | "boolean"

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

One of the following:

"string"

"number"

"boolean"

datasets?: Array<string>

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

filterCombination?: "and" | "or" | "AND" | "OR"

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

One of the following:

"and"

"or"

"AND"

"OR"

filters?: Array<UnionMember0 { filterCombination, filters, kind } | WorkersObservabilityFilterLeaf { key, operation, type, 2 more } >

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.

One of the following:

UnionMember0 { filterCombination, filters, kind }

filterCombination: "and" | "or" | "AND" | "OR"

One of the following:

"and"

"or"

"AND"

"OR"

filters: Array<UnionMember0 { filterCombination, filters, kind } | WorkersObservabilityFilterLeaf { key, operation, type, 2 more } >

One of the following:

UnionMember0 { filterCombination, filters, kind }

filterCombination: "and" | "or" | "AND" | "OR"

One of the following:

"and"

"or"

"AND"

"OR"

filters: Array<unknown>

kind: "group"

WorkersObservabilityFilterLeaf { key, operation, type, 2 more }

A filter condition applied to query results. Use the keys and values endpoints to discover available fields and their values before constructing filters.

key: string

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.

operation: "includes" | "not_includes" | "starts_with" | 25 more

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

One of the following:

"includes"

"not_includes"

"starts_with"

"regex"

"exists"

"is_null"

"in"

"not_in"

"eq"

"neq"

"gt"

"gte"

"lt"

"lte"

"="

"!="

">"

">="

"<"

"<="

"INCLUDES"

"DOES_NOT_INCLUDE"

"MATCH_REGEX"

"EXISTS"

"DOES_NOT_EXIST"

"IN"

"NOT_IN"

"STARTS_WITH"

type: "string" | "number" | "boolean"

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

One of the following:

"string"

"number"

"boolean"

kind?: "filter"

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

value?: string | number | boolean

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).

One of the following:

string

number

boolean

kind: "group"

WorkersObservabilityFilterLeaf { key, operation, type, 2 more }

A filter condition applied to query results. Use the keys and values endpoints to discover available fields and their values before constructing filters.

key: string

operation: "includes" | "not_includes" | "starts_with" | 25 more

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

One of the following:

"includes"

"not_includes"

"starts_with"

"regex"

"exists"

"is_null"

"in"

"not_in"

"eq"

"neq"

"gt"

"gte"

"lt"

"lte"

"="

"!="

">"

">="

"<"

"<="

"INCLUDES"

"DOES_NOT_INCLUDE"

"MATCH_REGEX"

"EXISTS"

"DOES_NOT_EXIST"

"IN"

"NOT_IN"

"STARTS_WITH"

type: "string" | "number" | "boolean"

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

One of the following:

"string"

"number"

"boolean"

kind?: "filter"

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

value?: string | number | boolean

One of the following:

string

number

boolean

groupBys?: Array<GroupBy>

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

type: "string" | "number" | "boolean"

Data type of the group-by field.

One of the following:

"string"

"number"

"boolean"

value: string

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

havings?: Array<Having>

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

key: string

Calculation alias or operator to filter on after aggregation.

operation: "eq" | "neq" | "gt" | 3 more

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

One of the following:

"eq"

"neq"

"gt"

"gte"

"lt"

"lte"

value: number

Threshold value to compare the calculation result against.

limit?: number

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

maximum2000

minimum0

needle?: Needle { value, isRegex, matchCase }

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

value: string | number | boolean

The text or pattern to search for.

maxLength1000

One of the following:

string

number

boolean

isRegex?: boolean

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

matchCase?: boolean

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

orderBy?: OrderBy { value, order }

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

value: string

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

order?: "asc" | "desc"

Sort direction: ‘asc’ for ascending, ‘desc’ for descending.

One of the following:

"asc"

"desc"

view?: "traces" | "events" | "calculations" | 3 more

Body param: 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.

One of the following:

"traces"

"events"

"calculations"

"invocations"

"requests"

"agents"

ReturnsExpand Collapse

TelemetryQueryResponse { run, statistics, agents, 5 more }

Complete results of a query run. The populated fields depend on the requested view type (events, calculations, invocations, traces, or agents).

run: Run { id, accountId, dry, 8 more }

The query run metadata including the query definition, execution status, and timeframe.

id: string

Unique identifier for this query run.

accountId: string

Cloudflare account ID that owns this query run.

dry: boolean

Whether this was a dry run (results not persisted).

granularity: number

Number of time-series buckets used for the query. Higher values produce more detailed series data.

query: Query { id, adhoc, created, 6 more }

A saved query definition with its parameters, metadata, and ownership information.

id: string

adhoc: boolean

If the query wasn’t explcitly saved

created: string

createdBy: string

description: string | null

maxLength1000

Query name

maxLength250

minLength1

parameters: Parameters { calculations, datasets, filterCombination, 6 more }

calculations?: Array<Calculation>

Create Calculations to compute as part of the query.

operator: "uniq" | "count" | "max" | 35 more

One of the following:

"uniq"

"count"

"max"

"min"

"sum"

"avg"

"median"

"p001"

"p01"

"p05"

"p10"

"p25"

"p75"

"p90"

"p95"

"p99"

"p999"

"stddev"

"variance"

"COUNT_DISTINCT"

"COUNT"

"MAX"

"MIN"

"SUM"

"AVG"

"MEDIAN"

"P001"

"P01"

"P05"

"P10"

"P25"

"P75"

"P90"

"P95"

"P99"

"P999"

"STDDEV"

"VARIANCE"

alias?: string

key?: string

keyType?: "string" | "number" | "boolean"

One of the following:

"string"

"number"

"boolean"

datasets?: Array<string>

Set the Datasets to query. Leave it empty to query all the datasets.

filterCombination?: "and" | "or" | "AND" | "OR"

Set a Flag to describe how to combine the filters on the query.

One of the following:

"and"

"or"

"AND"

"OR"

filters?: Array<UnionMember0 { filterCombination, filters, kind } | WorkersObservabilityFilterLeaf { key, operation, type, 2 more } >

Configure the Filters to apply to the query. Supports nested groups via kind: ‘group’.

One of the following:

UnionMember0 { filterCombination, filters, kind }

filterCombination: "and" | "or" | "AND" | "OR"

One of the following:

"and"

"or"

"AND"

"OR"

filters: Array<unknown>

kind: "group"

WorkersObservabilityFilterLeaf { key, operation, type, 2 more }

A filter condition applied to query results. Use the keys and values endpoints to discover available fields and their values before constructing filters.

key: string

operation: "includes" | "not_includes" | "starts_with" | 25 more

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

One of the following:

"includes"

"not_includes"

"starts_with"

"regex"

"exists"

"is_null"

"in"

"not_in"

"eq"

"neq"

"gt"

"gte"

"lt"

"lte"

"="

"!="

">"

">="

"<"

"<="

"INCLUDES"

"DOES_NOT_INCLUDE"

"MATCH_REGEX"

"EXISTS"

"DOES_NOT_EXIST"

"IN"

"NOT_IN"

"STARTS_WITH"

type: "string" | "number" | "boolean"

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

One of the following:

"string"

"number"

"boolean"

kind?: "filter"

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

value?: string | number | boolean

One of the following:

string

number

boolean

groupBys?: Array<GroupBy>

Define how to group the results of the query.

type: "string" | "number" | "boolean"

One of the following:

"string"

"number"

"boolean"

value: string

havings?: Array<Having>

Configure the Having clauses that filter on calculations in the query result.

key: string

operation: "eq" | "neq" | "gt" | 3 more

One of the following:

"eq"

"neq"

"gt"

"gte"

"lt"

"lte"

value: number

limit?: number

Set a limit on the number of results / records returned by the query

maximum100

minimum0

needle?: Needle { value, isRegex, matchCase }

Define an expression to search using full-text search.

value: Value

isRegex?: boolean

matchCase?: boolean

orderBy?: OrderBy { value, order }

Configure the order of the results returned by the query.

value: string

Configure which Calculation to order the results by.

order?: "asc" | "desc"

Set the order of the results

One of the following:

"asc"

"desc"

updated: string

updatedBy: string

status: "STARTED" | "COMPLETED"

Current execution status of the query run.

One of the following:

"STARTED"

"COMPLETED"

timeframe: Timeframe { from, to }

Time range for the query execution

from: number

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

to: number

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

userId: string

ID of the user who initiated the query run.

created?: string

ISO-8601 timestamp when the query run was created.

statistics?: Statistics { bytes_read, elapsed, rows_read, abr_level }

Query performance statistics from the database (does not include network latency).

bytes_read: number

Number of uncompressed bytes read from the table.

elapsed: number

Time in seconds for the query to run.

rows_read: number

Number of rows scanned from the table.

abr_level?: number

The level of Adaptive Bit Rate (ABR) sampling used for the query. If empty the ABR level is 1

updated?: string

ISO-8601 timestamp when the query run was last updated.

statistics: Statistics { bytes_read, elapsed, rows_read, abr_level }

Query performance statistics from the database. Includes execution time, rows scanned, and bytes read. Does not include network latency.

bytes_read: number

Number of uncompressed bytes read from the table.

elapsed: number

Time in seconds for the query to run.

rows_read: number

Number of rows scanned from the table.

abr_level?: number

The level of Adaptive Bit Rate (ABR) sampling used for the query. If empty the ABR level is 1

agents?: Array<Agent>

Durable Object agent summaries. Present when the query view is ‘agents’. Each entry represents an agent with its event counts and status.

agentClass: string

Class name of the Durable Object agent.

eventTypeCounts: Record<string, number>

Breakdown of event counts by event type.

firstEventMs: number

Timestamp of the earliest event from this agent in the queried window (Unix epoch ms).

hasErrors: boolean

Whether the agent emitted any error events in the queried window.

lastEventMs: number

Timestamp of the most recent event from this agent (Unix epoch ms).

namespace: string

Durable Object namespace the agent belongs to.

service: string

Worker service name that hosts this agent.

totalEvents: number

Total number of events emitted by this agent in the queried window.

calculations?: Array<Calculation>

Aggregated calculation results. Present when the query view is ‘calculations’. Contains computed metrics (count, avg, p99, etc.) with optional group-by breakdowns and time-series data.

aggregates: Array<Aggregate>

interval: number

sampleInterval: number

value: number

groups?: Array<Group>

key: string

value: string | number | boolean

One of the following:

string

number

boolean

calculation: string

series: Array<Series>

data: Array<Data>

interval: number

sampleInterval: number

value: number

firstSeen?: string

groups?: Array<Group>

key: string

value: string | number | boolean

One of the following:

string

number

boolean

lastSeen?: string

time: string

alias?: string

compare?: Array<Compare>

Comparison calculation results from the previous time period. Present when the compare option is enabled. Same structure as calculations.

aggregates: Array<Aggregate>

interval: number

sampleInterval: number

value: number

groups?: Array<Group>

key: string

value: string | number | boolean

One of the following:

string

number

boolean

calculation: string

series: Array<Series>

data: Array<Data>

interval: number

sampleInterval: number

value: number

firstSeen?: string

groups?: Array<Group>

key: string

value: string | number | boolean

One of the following:

string

number

boolean

lastSeen?: string

time: string

alias?: string

events?: Events { count, events, fields, series }

Individual event results. Present when the query view is ‘events’. Contains the matching log lines and their metadata.

count?: number

Total number of events matching the query (may exceed the number returned due to limits).

events?: Array<Event>

List of individual telemetry events matching the query.

"$metadata": Metadata { id, account, cloudService, 28 more }

Structured metadata extracted from the event. These fields are indexed and available for filtering and aggregation.

id: string

Unique event ID. Use as the cursor value for offset-based pagination.

account?: string

Cloudflare account identifier.

cloudService?: string

Cloudflare product that generated this event (e.g. workers, pages).

coldStart?: number

Whether this was a cold start (1) or warm invocation (0).

exclusiveMinimum

minimum0

cost?: number

Estimated cost units for this invocation.

exclusiveMinimum

minimum0

duration?: number

Span duration in milliseconds.

exclusiveMinimum

minimum0

endTime?: number

Span end time as a Unix epoch in milliseconds.

minimum0

error?: string

Error message, present when the log represents an error.

errorTemplate?: string

Templatized version of the error message used for grouping similar errors.

fingerprint?: string

Content-based fingerprint used to group similar events.

level?: string

Log level (e.g. log, debug, info, warn, error).

message?: string

Log message text.

messageTemplate?: string

Templatized version of the log message used for grouping similar messages.

metricName?: string

Metric name when the event represents a metric data point.

origin?: string

Origin of the event (e.g. fetch, scheduled, queue).

parentSpanId?: string

Span ID of the parent span in the trace hierarchy.

provider?: string

Infrastructure provider identifier.

region?: string

Cloudflare data center / region that handled the request.

requestId?: string

Cloudflare request ID that ties all logs from a single invocation together.

service?: string

Worker script name that produced this event.

spanId?: string

Span ID for this individual unit of work within a trace.

spanName?: string

Human-readable name for this span.

stackId?: string

Stack / deployment identifier.

startTime?: number

Span start time as a Unix epoch in milliseconds.

minimum0

statusCode?: number

HTTP response status code returned by the Worker.

exclusiveMinimum

minimum0

traceDuration?: number

Total duration of the entire trace in milliseconds.

exclusiveMinimum

minimum0

traceId?: string

Distributed trace ID linking spans across services.

transactionName?: string

Logical transaction name for this request.

trigger?: string

What triggered the invocation (e.g. GET /users, POST /orders, queue message).

type?: string

Event type classifier (e.g. cf-worker-event, cf-worker-log).

url?: string

Request URL that triggered the Worker invocation.

dataset: string

The dataset this event belongs to (e.g. cloudflare-workers).

source: string | unknown

Raw log payload. May be a string or a structured object depending on how the log was emitted.

One of the following:

string

unknown

timestamp: number

Event timestamp as a Unix epoch in milliseconds.

minimum0

"$containers"?: unknown

Cloudflare Containers event information that enriches your logs for identifying and debugging issues.

"$workers"?: UnionMember0 { eventType, requestId, scriptName, 9 more } | UnionMember1 { cpuTimeMs, eventType, outcome, 13 more }

Cloudflare Workers event information that enriches your logs for identifying and debugging issues.

One of the following:

UnionMember0 { eventType, requestId, scriptName, 9 more }

eventType: "fetch" | "scheduled" | "alarm" | 8 more

One of the following:

"fetch"

"scheduled"

"alarm"

"cron"

"queue"

"email"

"tail"

"rpc"

"websocket"

"workflow"

"unknown"

requestId: string

scriptName: string

durableObjectId?: string

entrypoint?: string

event?: Record<string, unknown>

executionModel?: "durableObject" | "stateless"

One of the following:

"durableObject"

"stateless"

outcome?: string

scriptVersion?: ScriptVersion { id, message, tag }

id?: string

message?: string

tag?: string

spanId?: string

traceId?: string

truncated?: boolean

UnionMember1 { cpuTimeMs, eventType, outcome, 13 more }

cpuTimeMs: number

eventType: "fetch" | "scheduled" | "alarm" | 8 more

One of the following:

"fetch"

"scheduled"

"alarm"

"cron"

"queue"

"email"

"tail"

"rpc"

"websocket"

"workflow"

"unknown"

outcome: string

requestId: string

scriptName: string

wallTimeMs: number

diagnosticsChannelEvents?: Array<DiagnosticsChannelEvent>

channel: string

message: string

timestamp: number

dispatchNamespace?: string

durableObjectId?: string

entrypoint?: string

event?: Record<string, unknown>

executionModel?: "durableObject" | "stateless"

One of the following:

"durableObject"

"stateless"

scriptVersion?: ScriptVersion { id, message, tag }

id?: string

message?: string

tag?: string

spanId?: string

traceId?: string

truncated?: boolean

fields?: Array<Field>

List of fields discovered in the matched events. Useful for building dynamic UIs.

key: string

Field name present in the matched events.

type: string

Data type of the field (string, number, or boolean).

series?: Array<Series>

Time-series data for the matched events, bucketed by the query granularity.

data: Array<Data>

aggregates: Aggregates { _count, _interval, _firstSeen, 2 more }

Deprecated_count: number

exclusiveMinimum

minimum0

Deprecated_interval: number

exclusiveMinimum

minimum0

Deprecated_firstSeen?: string

Deprecated_lastSeen?: string

Deprecatedbin?: unknown

interval: number

sampleInterval: number

errors?: number

groups?: Record<string, string | number | boolean>

Groups in the query results.

One of the following:

string

number

boolean

time: string

invocations?: Record<string, Array<Invocation>>

Events grouped by invocation (request ID). Present when the query view is ‘invocations’. Each key is a request ID mapping to all events from that invocation.

"$metadata": Metadata { id, account, cloudService, 28 more }

Structured metadata extracted from the event. These fields are indexed and available for filtering and aggregation.

id: string

Unique event ID. Use as the cursor value for offset-based pagination.

account?: string

Cloudflare account identifier.

cloudService?: string

Cloudflare product that generated this event (e.g. workers, pages).

coldStart?: number

Whether this was a cold start (1) or warm invocation (0).

exclusiveMinimum

minimum0

cost?: number

Estimated cost units for this invocation.

exclusiveMinimum

minimum0

duration?: number

Span duration in milliseconds.

exclusiveMinimum

minimum0

endTime?: number

Span end time as a Unix epoch in milliseconds.

minimum0

error?: string

Error message, present when the log represents an error.

errorTemplate?: string

Templatized version of the error message used for grouping similar errors.

fingerprint?: string

Content-based fingerprint used to group similar events.

level?: string

Log level (e.g. log, debug, info, warn, error).

message?: string

Log message text.

messageTemplate?: string

Templatized version of the log message used for grouping similar messages.

metricName?: string

Metric name when the event represents a metric data point.

origin?: string

Origin of the event (e.g. fetch, scheduled, queue).

parentSpanId?: string

Span ID of the parent span in the trace hierarchy.

provider?: string

Infrastructure provider identifier.

region?: string

Cloudflare data center / region that handled the request.

requestId?: string

Cloudflare request ID that ties all logs from a single invocation together.

service?: string

Worker script name that produced this event.

spanId?: string

Span ID for this individual unit of work within a trace.

spanName?: string

Human-readable name for this span.

stackId?: string

Stack / deployment identifier.

startTime?: number

Span start time as a Unix epoch in milliseconds.

minimum0

statusCode?: number

HTTP response status code returned by the Worker.

exclusiveMinimum

minimum0

traceDuration?: number

Total duration of the entire trace in milliseconds.

exclusiveMinimum

minimum0

traceId?: string

Distributed trace ID linking spans across services.

transactionName?: string

Logical transaction name for this request.

trigger?: string

What triggered the invocation (e.g. GET /users, POST /orders, queue message).

type?: string

Event type classifier (e.g. cf-worker-event, cf-worker-log).

url?: string

Request URL that triggered the Worker invocation.

dataset: string

The dataset this event belongs to (e.g. cloudflare-workers).

source: string | unknown

Raw log payload. May be a string or a structured object depending on how the log was emitted.

One of the following:

string

unknown

timestamp: number

Event timestamp as a Unix epoch in milliseconds.

minimum0

"$containers"?: unknown

Cloudflare Containers event information that enriches your logs for identifying and debugging issues.

"$workers"?: UnionMember0 { eventType, requestId, scriptName, 9 more } | UnionMember1 { cpuTimeMs, eventType, outcome, 13 more }

Cloudflare Workers event information that enriches your logs for identifying and debugging issues.

One of the following:

UnionMember0 { eventType, requestId, scriptName, 9 more }

eventType: "fetch" | "scheduled" | "alarm" | 8 more

One of the following:

"fetch"

"scheduled"

"alarm"

"cron"

"queue"

"email"

"tail"

"rpc"

"websocket"

"workflow"

"unknown"

requestId: string

scriptName: string

durableObjectId?: string

entrypoint?: string

event?: Record<string, unknown>

executionModel?: "durableObject" | "stateless"

One of the following:

"durableObject"

"stateless"

outcome?: string

scriptVersion?: ScriptVersion { id, message, tag }

id?: string

message?: string

tag?: string

spanId?: string

traceId?: string

truncated?: boolean

UnionMember1 { cpuTimeMs, eventType, outcome, 13 more }

cpuTimeMs: number

eventType: "fetch" | "scheduled" | "alarm" | 8 more

One of the following:

"fetch"

"scheduled"

"alarm"

"cron"

"queue"

"email"

"tail"

"rpc"

"websocket"

"workflow"

"unknown"

outcome: string

requestId: string

scriptName: string

wallTimeMs: number

diagnosticsChannelEvents?: Array<DiagnosticsChannelEvent>

channel: string

message: string

timestamp: number

dispatchNamespace?: string

durableObjectId?: string

entrypoint?: string

event?: Record<string, unknown>

executionModel?: "durableObject" | "stateless"

One of the following:

"durableObject"

"stateless"

scriptVersion?: ScriptVersion { id, message, tag }

id?: string

message?: string

tag?: string

spanId?: string

traceId?: string

truncated?: boolean

traces?: Array<Trace>

Trace summaries matching the query. Present when the query view is ‘traces’. Each entry represents a distributed trace with its spans, duration, and services involved.

rootSpanName: string

Name of the root span that initiated the trace.

rootTransactionName: string

Logical transaction name for the root span.

service: Array<string>

List of Worker services involved in the trace.

spans: number

Total number of spans in the trace.

traceDurationMs: number

Total duration of the trace in milliseconds.

traceEndMs: number

Trace end time as a Unix epoch in milliseconds.

traceId: string

Unique identifier for the distributed trace.

traceStartMs: number

Trace start time as a Unix epoch in milliseconds.

errors?: Array<string>

Error messages encountered during the trace, if any.

Run a query

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiEmail: process.env['CLOUDFLARE_EMAIL'], // This is the default and can be omitted
  apiKey: process.env['CLOUDFLARE_API_KEY'], // This is the default and can be omitted
});

const response = await client.workers.observability.telemetry.query({
  account_id: 'account_id',
  queryId: 'queryId',
  timeframe: { from: 0, to: 0 },
});

console.log(response.run);

{
  "errors": [
    {
      "message": "message"
    }
  ],
  "messages": [
    {
      "message": "Successful request"
    }
  ],
  "result": {
    "run": {
      "id": "id",
      "accountId": "accountId",
      "dry": true,
      "granularity": 0,
      "query": {
        "id": "id",
        "adhoc": true,
        "created": "created",
        "createdBy": "createdBy",
        "description": "Query description",
        "name": "x",
        "parameters": {
          "calculations": [
            {
              "operator": "uniq",
              "alias": "alias",
              "key": "key",
              "keyType": "string"
            }
          ],
          "datasets": [
            "string"
          ],
          "filterCombination": "and",
          "filters": [
            {
              "filterCombination": "and",
              "filters": [
                {}
              ],
              "kind": "group"
            }
          ],
          "groupBys": [
            {
              "type": "string",
              "value": "value"
            }
          ],
          "havings": [
            {
              "key": "key",
              "operation": "eq",
              "value": 0
            }
          ],
          "limit": 0,
          "needle": {
            "value": {
              "0": "s",
              "1": "t",
              "2": "r",
              "3": "i",
              "4": "n",
              "5": "g"
            },
            "isRegex": true,
            "matchCase": true
          },
          "orderBy": {
            "value": "value",
            "order": "asc"
          }
        },
        "updated": "updated",
        "updatedBy": "updatedBy"
      },
      "status": "STARTED",
      "timeframe": {
        "from": 0,
        "to": 0
      },
      "userId": "userId",
      "created": "created",
      "statistics": {
        "bytes_read": 0,
        "elapsed": 0,
        "rows_read": 0,
        "abr_level": 0
      },
      "updated": "updated"
    },
    "statistics": {
      "bytes_read": 0,
      "elapsed": 0,
      "rows_read": 0,
      "abr_level": 0
    },
    "agents": [
      {
        "agentClass": "agentClass",
        "eventTypeCounts": {
          "foo": 0
        },
        "firstEventMs": 0,
        "hasErrors": true,
        "lastEventMs": 0,
        "namespace": "namespace",
        "service": "service",
        "totalEvents": 0
      }
    ],
    "calculations": [
      {
        "aggregates": [
          {
            "count": 0,
            "interval": 0,
            "sampleInterval": 0,
            "value": 0,
            "groups": [
              {
                "key": "key",
                "value": "string"
              }
            ]
          }
        ],
        "calculation": "calculation",
        "series": [
          {
            "data": [
              {
                "count": 0,
                "interval": 0,
                "sampleInterval": 0,
                "value": 0,
                "firstSeen": "firstSeen",
                "groups": [
                  {
                    "key": "key",
                    "value": "string"
                  }
                ],
                "lastSeen": "lastSeen"
              }
            ],
            "time": "time"
          }
        ],
        "alias": "alias"
      }
    ],
    "compare": [
      {
        "aggregates": [
          {
            "count": 0,
            "interval": 0,
            "sampleInterval": 0,
            "value": 0,
            "groups": [
              {
                "key": "key",
                "value": "string"
              }
            ]
          }
        ],
        "calculation": "calculation",
        "series": [
          {
            "data": [
              {
                "count": 0,
                "interval": 0,
                "sampleInterval": 0,
                "value": 0,
                "firstSeen": "firstSeen",
                "groups": [
                  {
                    "key": "key",
                    "value": "string"
                  }
                ],
                "lastSeen": "lastSeen"
              }
            ],
            "time": "time"
          }
        ],
        "alias": "alias"
      }
    ],
    "events": {
      "count": 0,
      "events": [
        {
          "$metadata": {
            "id": "id",
            "account": "account",
            "cloudService": "cloudService",
            "coldStart": 1,
            "cost": 1,
            "duration": 1,
            "endTime": 0,
            "error": "error",
            "errorTemplate": "errorTemplate",
            "fingerprint": "fingerprint",
            "level": "level",
            "message": "message",
            "messageTemplate": "messageTemplate",
            "metricName": "metricName",
            "origin": "origin",
            "parentSpanId": "parentSpanId",
            "provider": "provider",
            "region": "region",
            "requestId": "requestId",
            "service": "service",
            "spanId": "spanId",
            "spanName": "spanName",
            "stackId": "stackId",
            "startTime": 0,
            "statusCode": 1,
            "traceDuration": 1,
            "traceId": "traceId",
            "transactionName": "transactionName",
            "trigger": "trigger",
            "type": "type",
            "url": "url"
          },
          "dataset": "dataset",
          "source": "string",
          "timestamp": 0,
          "$containers": {},
          "$workers": {
            "eventType": "fetch",
            "requestId": "requestId",
            "scriptName": "scriptName",
            "durableObjectId": "durableObjectId",
            "entrypoint": "entrypoint",
            "event": {
              "foo": "bar"
            },
            "executionModel": "durableObject",
            "outcome": "outcome",
            "scriptVersion": {
              "id": "id",
              "message": "message",
              "tag": "tag"
            },
            "spanId": "spanId",
            "traceId": "traceId",
            "truncated": true
          }
        }
      ],
      "fields": [
        {
          "key": "key",
          "type": "type"
        }
      ],
      "series": [
        {
          "data": [
            {
              "aggregates": {
                "_count": 1,
                "_interval": 1,
                "_firstSeen": "_firstSeen",
                "_lastSeen": "_lastSeen",
                "bin": {}
              },
              "count": 0,
              "interval": 0,
              "sampleInterval": 0,
              "errors": 0,
              "groups": {
                "foo": "string"
              }
            }
          ],
          "time": "time"
        }
      ]
    },
    "invocations": {
      "foo": [
        {
          "$metadata": {
            "id": "id",
            "account": "account",
            "cloudService": "cloudService",
            "coldStart": 1,
            "cost": 1,
            "duration": 1,
            "endTime": 0,
            "error": "error",
            "errorTemplate": "errorTemplate",
            "fingerprint": "fingerprint",
            "level": "level",
            "message": "message",
            "messageTemplate": "messageTemplate",
            "metricName": "metricName",
            "origin": "origin",
            "parentSpanId": "parentSpanId",
            "provider": "provider",
            "region": "region",
            "requestId": "requestId",
            "service": "service",
            "spanId": "spanId",
            "spanName": "spanName",
            "stackId": "stackId",
            "startTime": 0,
            "statusCode": 1,
            "traceDuration": 1,
            "traceId": "traceId",
            "transactionName": "transactionName",
            "trigger": "trigger",
            "type": "type",
            "url": "url"
          },
          "dataset": "dataset",
          "source": "string",
          "timestamp": 0,
          "$containers": {},
          "$workers": {
            "eventType": "fetch",
            "requestId": "requestId",
            "scriptName": "scriptName",
            "durableObjectId": "durableObjectId",
            "entrypoint": "entrypoint",
            "event": {
              "foo": "bar"
            },
            "executionModel": "durableObject",
            "outcome": "outcome",
            "scriptVersion": {
              "id": "id",
              "message": "message",
              "tag": "tag"
            },
            "spanId": "spanId",
            "traceId": "traceId",
            "truncated": true
          }
        }
      ]
    },
    "traces": [
      {
        "rootSpanName": "rootSpanName",
        "rootTransactionName": "rootTransactionName",
        "service": [
          "string"
        ],
        "spans": 0,
        "traceDurationMs": 0,
        "traceEndMs": 0,
        "traceId": "traceId",
        "traceStartMs": 0,
        "errors": [
          "string"
        ]
      }
    ]
  },
  "success": true
}

Returns Examples

{
  "errors": [
    {
      "message": "message"
    }
  ],
  "messages": [
    {
      "message": "Successful request"
    }
  ],
  "result": {
    "run": {
      "id": "id",
      "accountId": "accountId",
      "dry": true,
      "granularity": 0,
      "query": {
        "id": "id",
        "adhoc": true,
        "created": "created",
        "createdBy": "createdBy",
        "description": "Query description",
        "name": "x",
        "parameters": {
          "calculations": [
            {
              "operator": "uniq",
              "alias": "alias",
              "key": "key",
              "keyType": "string"
            }
          ],
          "datasets": [
            "string"
          ],
          "filterCombination": "and",
          "filters": [
            {
              "filterCombination": "and",
              "filters": [
                {}
              ],
              "kind": "group"
            }
          ],
          "groupBys": [
            {
              "type": "string",
              "value": "value"
            }
          ],
          "havings": [
            {
              "key": "key",
              "operation": "eq",
              "value": 0
            }
          ],
          "limit": 0,
          "needle": {
            "value": {
              "0": "s",
              "1": "t",
              "2": "r",
              "3": "i",
              "4": "n",
              "5": "g"
            },
            "isRegex": true,
            "matchCase": true
          },
          "orderBy": {
            "value": "value",
            "order": "asc"
          }
        },
        "updated": "updated",
        "updatedBy": "updatedBy"
      },
      "status": "STARTED",
      "timeframe": {
        "from": 0,
        "to": 0
      },
      "userId": "userId",
      "created": "created",
      "statistics": {
        "bytes_read": 0,
        "elapsed": 0,
        "rows_read": 0,
        "abr_level": 0
      },
      "updated": "updated"
    },
    "statistics": {
      "bytes_read": 0,
      "elapsed": 0,
      "rows_read": 0,
      "abr_level": 0
    },
    "agents": [
      {
        "agentClass": "agentClass",
        "eventTypeCounts": {
          "foo": 0
        },
        "firstEventMs": 0,
        "hasErrors": true,
        "lastEventMs": 0,
        "namespace": "namespace",
        "service": "service",
        "totalEvents": 0
      }
    ],
    "calculations": [
      {
        "aggregates": [
          {
            "count": 0,
            "interval": 0,
            "sampleInterval": 0,
            "value": 0,
            "groups": [
              {
                "key": "key",
                "value": "string"
              }
            ]
          }
        ],
        "calculation": "calculation",
        "series": [
          {
            "data": [
              {
                "count": 0,
                "interval": 0,
                "sampleInterval": 0,
                "value": 0,
                "firstSeen": "firstSeen",
                "groups": [
                  {
                    "key": "key",
                    "value": "string"
                  }
                ],
                "lastSeen": "lastSeen"
              }
            ],
            "time": "time"
          }
        ],
        "alias": "alias"
      }
    ],
    "compare": [
      {
        "aggregates": [
          {
            "count": 0,
            "interval": 0,
            "sampleInterval": 0,
            "value": 0,
            "groups": [
              {
                "key": "key",
                "value": "string"
              }
            ]
          }
        ],
        "calculation": "calculation",
        "series": [
          {
            "data": [
              {
                "count": 0,
                "interval": 0,
                "sampleInterval": 0,
                "value": 0,
                "firstSeen": "firstSeen",
                "groups": [
                  {
                    "key": "key",
                    "value": "string"
                  }
                ],
                "lastSeen": "lastSeen"
              }
            ],
            "time": "time"
          }
        ],
        "alias": "alias"
      }
    ],
    "events": {
      "count": 0,
      "events": [
        {
          "$metadata": {
            "id": "id",
            "account": "account",
            "cloudService": "cloudService",
            "coldStart": 1,
            "cost": 1,
            "duration": 1,
            "endTime": 0,
            "error": "error",
            "errorTemplate": "errorTemplate",
            "fingerprint": "fingerprint",
            "level": "level",
            "message": "message",
            "messageTemplate": "messageTemplate",
            "metricName": "metricName",
            "origin": "origin",
            "parentSpanId": "parentSpanId",
            "provider": "provider",
            "region": "region",
            "requestId": "requestId",
            "service": "service",
            "spanId": "spanId",
            "spanName": "spanName",
            "stackId": "stackId",
            "startTime": 0,
            "statusCode": 1,
            "traceDuration": 1,
            "traceId": "traceId",
            "transactionName": "transactionName",
            "trigger": "trigger",
            "type": "type",
            "url": "url"
          },
          "dataset": "dataset",
          "source": "string",
          "timestamp": 0,
          "$containers": {},
          "$workers": {
            "eventType": "fetch",
            "requestId": "requestId",
            "scriptName": "scriptName",
            "durableObjectId": "durableObjectId",
            "entrypoint": "entrypoint",
            "event": {
              "foo": "bar"
            },
            "executionModel": "durableObject",
            "outcome": "outcome",
            "scriptVersion": {
              "id": "id",
              "message": "message",
              "tag": "tag"
            },
            "spanId": "spanId",
            "traceId": "traceId",
            "truncated": true
          }
        }
      ],
      "fields": [
        {
          "key": "key",
          "type": "type"
        }
      ],
      "series": [
        {
          "data": [
            {
              "aggregates": {
                "_count": 1,
                "_interval": 1,
                "_firstSeen": "_firstSeen",
                "_lastSeen": "_lastSeen",
                "bin": {}
              },
              "count": 0,
              "interval": 0,
              "sampleInterval": 0,
              "errors": 0,
              "groups": {
                "foo": "string"
              }
            }
          ],
          "time": "time"
        }
      ]
    },
    "invocations": {
      "foo": [
        {
          "$metadata": {
            "id": "id",
            "account": "account",
            "cloudService": "cloudService",
            "coldStart": 1,
            "cost": 1,
            "duration": 1,
            "endTime": 0,
            "error": "error",
            "errorTemplate": "errorTemplate",
            "fingerprint": "fingerprint",
            "level": "level",
            "message": "message",
            "messageTemplate": "messageTemplate",
            "metricName": "metricName",
            "origin": "origin",
            "parentSpanId": "parentSpanId",
            "provider": "provider",
            "region": "region",
            "requestId": "requestId",
            "service": "service",
            "spanId": "spanId",
            "spanName": "spanName",
            "stackId": "stackId",
            "startTime": 0,
            "statusCode": 1,
            "traceDuration": 1,
            "traceId": "traceId",
            "transactionName": "transactionName",
            "trigger": "trigger",
            "type": "type",
            "url": "url"
          },
          "dataset": "dataset",
          "source": "string",
          "timestamp": 0,
          "$containers": {},
          "$workers": {
            "eventType": "fetch",
            "requestId": "requestId",
            "scriptName": "scriptName",
            "durableObjectId": "durableObjectId",
            "entrypoint": "entrypoint",
            "event": {
              "foo": "bar"
            },
            "executionModel": "durableObject",
            "outcome": "outcome",
            "scriptVersion": {
              "id": "id",
              "message": "message",
              "tag": "tag"
            },
            "spanId": "spanId",
            "traceId": "traceId",
            "truncated": true
          }
        }
      ]
    },
    "traces": [
      {
        "rootSpanName": "rootSpanName",
        "rootTransactionName": "rootTransactionName",
        "service": [
          "string"
        ],
        "spans": 0,
        "traceDurationMs": 0,
        "traceEndMs": 0,
        "traceId": "traceId",
        "traceStartMs": 0,
        "errors": [
          "string"
        ]
      }
    ]
  },
  "success": true
}