Skip to content
Cloudflare API
Start here
API Reference
Workers

Observability

ObservabilityTelemetry

List keys
workers.observability.telemetry.keys(TelemetryKeysParams**kwargs) -> SyncSinglePage[TelemetryKeysResponse]
POST/accounts/{account_id}/workers/observability/telemetry/keys
Run a query
workers.observability.telemetry.query(TelemetryQueryParams**kwargs) -> TelemetryQueryResponse
POST/accounts/{account_id}/workers/observability/telemetry/query
List values
workers.observability.telemetry.values(TelemetryValuesParams**kwargs) -> SyncSinglePage[TelemetryValuesResponse]
POST/accounts/{account_id}/workers/observability/telemetry/values
ModelsExpand Collapse
class TelemetryKeysResponse: …
key: str
last_seen_at: float
type: Literal["string", "boolean", "number"]
One of the following:
"string"
"boolean"
"number"
class TelemetryQueryResponse: …

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

run: Run

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

id: str

Unique identifier for this query run.

account_id: str

Cloudflare account ID that owns this query run.

dry: bool

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

granularity: float

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

query: RunQuery

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

id: str
adhoc: bool

If the query wasn’t explcitly saved

created: str
created_by: str
description: Optional[str]
maxLength1000
name: str

Query name

maxLength250
minLength1
parameters: RunQueryParameters
calculations: Optional[List[RunQueryParametersCalculation]]

Create Calculations to compute as part of the query.

operator: Literal["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: Optional[str]
key: Optional[str]
key_type: Optional[Literal["string", "number", "boolean"]]
One of the following:
"string"
"number"
"boolean"
datasets: Optional[List[str]]

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

filter_combination: Optional[Literal["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: Optional[List[RunQueryParametersFilter]]

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

One of the following:
class RunQueryParametersFilterUnionMember0: …
filter_combination: Literal["and", "or", "AND", "OR"]
One of the following:
"and"
"or"
"AND"
"OR"
filters: List[object]
kind: Literal["group"]
class RunQueryParametersFilterWorkersObservabilityFilterLeaf: …

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

key: str

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: Literal["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: Literal["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: Optional[Literal["filter"]]

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

value: Optional[Union[str, float, bool, null]]

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:
str
float
bool
group_bys: Optional[List[RunQueryParametersGroupBy]]

Define how to group the results of the query.

type: Literal["string", "number", "boolean"]
One of the following:
"string"
"number"
"boolean"
value: str
havings: Optional[List[RunQueryParametersHaving]]

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

key: str
operation: Literal["eq", "neq", "gt", 3 more]
One of the following:
"eq"
"neq"
"gt"
"gte"
"lt"
"lte"
value: float
limit: Optional[int]

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

maximum100
minimum0
needle: Optional[RunQueryParametersNeedle]

Define an expression to search using full-text search.

value: RunQueryParametersNeedleValue
is_regex: Optional[bool]
match_case: Optional[bool]
order_by: Optional[RunQueryParametersOrderBy]

Configure the order of the results returned by the query.

value: str

Configure which Calculation to order the results by.

order: Optional[Literal["asc", "desc"]]

Set the order of the results

One of the following:
"asc"
"desc"
updated: str
updated_by: str
status: Literal["STARTED", "COMPLETED"]

Current execution status of the query run.

One of the following:
"STARTED"
"COMPLETED"
timeframe: RunTimeframe

Time range for the query execution

from_: float

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

to: float

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

user_id: str

ID of the user who initiated the query run.

created: Optional[str]

ISO-8601 timestamp when the query run was created.

statistics: Optional[RunStatistics]

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

bytes_read: float

Number of uncompressed bytes read from the table.

elapsed: float

Time in seconds for the query to run.

rows_read: float

Number of rows scanned from the table.

abr_level: Optional[float]

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

updated: Optional[str]

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

statistics: Statistics

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

bytes_read: float

Number of uncompressed bytes read from the table.

elapsed: float

Time in seconds for the query to run.

rows_read: float

Number of rows scanned from the table.

abr_level: Optional[float]

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

agents: Optional[List[Agent]]

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

agent_class: str

Class name of the Durable Object agent.

event_type_counts: Dict[str, float]

Breakdown of event counts by event type.

first_event_ms: float

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

has_errors: bool

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

last_event_ms: float

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

namespace: str

Durable Object namespace the agent belongs to.

service: str

Worker service name that hosts this agent.

total_events: float

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

calculations: Optional[List[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: List[CalculationAggregate]
count: float
interval: float
sample_interval: float
value: float
groups: Optional[List[CalculationAggregateGroup]]
key: str
value: Union[str, float, bool]
One of the following:
str
float
bool
calculation: str
series: List[CalculationSeries]
data: List[CalculationSeriesData]
count: float
interval: float
sample_interval: float
value: float
first_seen: Optional[str]
groups: Optional[List[CalculationSeriesDataGroup]]
key: str
value: Union[str, float, bool]
One of the following:
str
float
bool
last_seen: Optional[str]
time: str
alias: Optional[str]
compare: Optional[List[Compare]]

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

aggregates: List[CompareAggregate]
count: float
interval: float
sample_interval: float
value: float
groups: Optional[List[CompareAggregateGroup]]
key: str
value: Union[str, float, bool]
One of the following:
str
float
bool
calculation: str
series: List[CompareSeries]
data: List[CompareSeriesData]
count: float
interval: float
sample_interval: float
value: float
first_seen: Optional[str]
groups: Optional[List[CompareSeriesDataGroup]]
key: str
value: Union[str, float, bool]
One of the following:
str
float
bool
last_seen: Optional[str]
time: str
alias: Optional[str]
events: Optional[Events]

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

count: Optional[float]

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

events: Optional[List[EventsEvent]]

List of individual telemetry events matching the query.

metadata: EventsEventMetadata

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

id: str

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

account: Optional[str]

Cloudflare account identifier.

cloud_service: Optional[str]

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

cold_start: Optional[int]

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

exclusiveMinimum
minimum0
cost: Optional[int]

Estimated cost units for this invocation.

exclusiveMinimum
minimum0
duration: Optional[int]

Span duration in milliseconds.

exclusiveMinimum
minimum0
end_time: Optional[int]

Span end time as a Unix epoch in milliseconds.

minimum0
error: Optional[str]

Error message, present when the log represents an error.

error_template: Optional[str]

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

fingerprint: Optional[str]

Content-based fingerprint used to group similar events.

level: Optional[str]

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

message: Optional[str]

Log message text.

message_template: Optional[str]

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

metric_name: Optional[str]

Metric name when the event represents a metric data point.

origin: Optional[str]

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

parent_span_id: Optional[str]

Span ID of the parent span in the trace hierarchy.

provider: Optional[str]

Infrastructure provider identifier.

region: Optional[str]

Cloudflare data center / region that handled the request.

request_id: Optional[str]

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

service: Optional[str]

Worker script name that produced this event.

span_id: Optional[str]

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

span_name: Optional[str]

Human-readable name for this span.

stack_id: Optional[str]

Stack / deployment identifier.

start_time: Optional[int]

Span start time as a Unix epoch in milliseconds.

minimum0
status_code: Optional[int]

HTTP response status code returned by the Worker.

exclusiveMinimum
minimum0
trace_duration: Optional[int]

Total duration of the entire trace in milliseconds.

exclusiveMinimum
minimum0
trace_id: Optional[str]

Distributed trace ID linking spans across services.

transaction_name: Optional[str]

Logical transaction name for this request.

trigger: Optional[str]

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

type: Optional[str]

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

url: Optional[str]

Request URL that triggered the Worker invocation.

dataset: str

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

source: Union[str, object]

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

One of the following:
str
object
timestamp: int

Event timestamp as a Unix epoch in milliseconds.

minimum0
containers: Optional[object]

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

workers: Optional[EventsEventWorkers]

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

One of the following:
class EventsEventWorkersUnionMember0: …
event_type: Literal["fetch", "scheduled", "alarm", 8 more]
One of the following:
"fetch"
"scheduled"
"alarm"
"cron"
"queue"
"email"
"tail"
"rpc"
"websocket"
"workflow"
"unknown"
request_id: str
script_name: str
durable_object_id: Optional[str]
entrypoint: Optional[str]
event: Optional[Dict[str, object]]
execution_model: Optional[Literal["durableObject", "stateless"]]
One of the following:
"durableObject"
"stateless"
outcome: Optional[str]
script_version: Optional[EventsEventWorkersUnionMember0ScriptVersion]
id: Optional[str]
message: Optional[str]
tag: Optional[str]
span_id: Optional[str]
trace_id: Optional[str]
truncated: Optional[bool]
class EventsEventWorkersUnionMember1: …
cpu_time_ms: float
event_type: Literal["fetch", "scheduled", "alarm", 8 more]
One of the following:
"fetch"
"scheduled"
"alarm"
"cron"
"queue"
"email"
"tail"
"rpc"
"websocket"
"workflow"
"unknown"
outcome: str
request_id: str
script_name: str
wall_time_ms: float
diagnostics_channel_events: Optional[List[EventsEventWorkersUnionMember1DiagnosticsChannelEvent]]
channel: str
message: str
timestamp: float
dispatch_namespace: Optional[str]
durable_object_id: Optional[str]
entrypoint: Optional[str]
event: Optional[Dict[str, object]]
execution_model: Optional[Literal["durableObject", "stateless"]]
One of the following:
"durableObject"
"stateless"
script_version: Optional[EventsEventWorkersUnionMember1ScriptVersion]
id: Optional[str]
message: Optional[str]
tag: Optional[str]
span_id: Optional[str]
trace_id: Optional[str]
truncated: Optional[bool]
fields: Optional[List[EventsField]]

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

key: str

Field name present in the matched events.

type: str

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

series: Optional[List[EventsSeries]]

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

data: List[EventsSeriesData]
aggregates: EventsSeriesDataAggregates
Deprecated_count: int
exclusiveMinimum
minimum0
Deprecated_interval: float
exclusiveMinimum
minimum0
Deprecated_first_seen: Optional[str]
Deprecated_last_seen: Optional[str]
Deprecatedbin: Optional[object]
count: float
interval: float
sample_interval: float
errors: Optional[float]
groups: Optional[Dict[str, Union[str, float, bool]]]

Groups in the query results.

One of the following:
str
float
bool
time: str
invocations: Optional[Dict[str, List[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: InvocationMetadata

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

id: str

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

account: Optional[str]

Cloudflare account identifier.

cloud_service: Optional[str]

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

cold_start: Optional[int]

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

exclusiveMinimum
minimum0
cost: Optional[int]

Estimated cost units for this invocation.

exclusiveMinimum
minimum0
duration: Optional[int]

Span duration in milliseconds.

exclusiveMinimum
minimum0
end_time: Optional[int]

Span end time as a Unix epoch in milliseconds.

minimum0
error: Optional[str]

Error message, present when the log represents an error.

error_template: Optional[str]

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

fingerprint: Optional[str]

Content-based fingerprint used to group similar events.

level: Optional[str]

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

message: Optional[str]

Log message text.

message_template: Optional[str]

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

metric_name: Optional[str]

Metric name when the event represents a metric data point.

origin: Optional[str]

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

parent_span_id: Optional[str]

Span ID of the parent span in the trace hierarchy.

provider: Optional[str]

Infrastructure provider identifier.

region: Optional[str]

Cloudflare data center / region that handled the request.

request_id: Optional[str]

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

service: Optional[str]

Worker script name that produced this event.

span_id: Optional[str]

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

span_name: Optional[str]

Human-readable name for this span.

stack_id: Optional[str]

Stack / deployment identifier.

start_time: Optional[int]

Span start time as a Unix epoch in milliseconds.

minimum0
status_code: Optional[int]

HTTP response status code returned by the Worker.

exclusiveMinimum
minimum0
trace_duration: Optional[int]

Total duration of the entire trace in milliseconds.

exclusiveMinimum
minimum0
trace_id: Optional[str]

Distributed trace ID linking spans across services.

transaction_name: Optional[str]

Logical transaction name for this request.

trigger: Optional[str]

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

type: Optional[str]

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

url: Optional[str]

Request URL that triggered the Worker invocation.

dataset: str

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

source: Union[str, object]

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

One of the following:
str
object
timestamp: int

Event timestamp as a Unix epoch in milliseconds.

minimum0
containers: Optional[object]

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

workers: Optional[InvocationWorkers]

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

One of the following:
class InvocationWorkersUnionMember0: …
event_type: Literal["fetch", "scheduled", "alarm", 8 more]
One of the following:
"fetch"
"scheduled"
"alarm"
"cron"
"queue"
"email"
"tail"
"rpc"
"websocket"
"workflow"
"unknown"
request_id: str
script_name: str
durable_object_id: Optional[str]
entrypoint: Optional[str]
event: Optional[Dict[str, object]]
execution_model: Optional[Literal["durableObject", "stateless"]]
One of the following:
"durableObject"
"stateless"
outcome: Optional[str]
script_version: Optional[InvocationWorkersUnionMember0ScriptVersion]
id: Optional[str]
message: Optional[str]
tag: Optional[str]
span_id: Optional[str]
trace_id: Optional[str]
truncated: Optional[bool]
class InvocationWorkersUnionMember1: …
cpu_time_ms: float
event_type: Literal["fetch", "scheduled", "alarm", 8 more]
One of the following:
"fetch"
"scheduled"
"alarm"
"cron"
"queue"
"email"
"tail"
"rpc"
"websocket"
"workflow"
"unknown"
outcome: str
request_id: str
script_name: str
wall_time_ms: float
diagnostics_channel_events: Optional[List[InvocationWorkersUnionMember1DiagnosticsChannelEvent]]
channel: str
message: str
timestamp: float
dispatch_namespace: Optional[str]
durable_object_id: Optional[str]
entrypoint: Optional[str]
event: Optional[Dict[str, object]]
execution_model: Optional[Literal["durableObject", "stateless"]]
One of the following:
"durableObject"
"stateless"
script_version: Optional[InvocationWorkersUnionMember1ScriptVersion]
id: Optional[str]
message: Optional[str]
tag: Optional[str]
span_id: Optional[str]
trace_id: Optional[str]
truncated: Optional[bool]
traces: Optional[List[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.

root_span_name: str

Name of the root span that initiated the trace.

root_transaction_name: str

Logical transaction name for the root span.

service: List[str]

List of Worker services involved in the trace.

spans: float

Total number of spans in the trace.

trace_duration_ms: float

Total duration of the trace in milliseconds.

trace_end_ms: float

Trace end time as a Unix epoch in milliseconds.

trace_id: str

Unique identifier for the distributed trace.

trace_start_ms: float

Trace start time as a Unix epoch in milliseconds.

errors: Optional[List[str]]

Error messages encountered during the trace, if any.

class TelemetryValuesResponse: …
dataset: str
key: str
type: Literal["string", "boolean", "number"]
One of the following:
"string"
"boolean"
"number"
value: Union[str, float, bool]
One of the following:
str
float
bool

ObservabilityDestinations

Get Destinations
workers.observability.destinations.list(DestinationListParams**kwargs) -> SyncSinglePage[DestinationListResponse]
GET/accounts/{account_id}/workers/observability/destinations
Create Destination
workers.observability.destinations.create(DestinationCreateParams**kwargs) -> DestinationCreateResponse
POST/accounts/{account_id}/workers/observability/destinations
Update Destination
workers.observability.destinations.update(strslug, DestinationUpdateParams**kwargs) -> DestinationUpdateResponse
PATCH/accounts/{account_id}/workers/observability/destinations/{slug}
Delete Destination
workers.observability.destinations.delete(strslug, DestinationDeleteParams**kwargs) -> DestinationDeleteResponse
DELETE/accounts/{account_id}/workers/observability/destinations/{slug}
ModelsExpand Collapse
class DestinationListResponse: …
configuration: Configuration
destination_conf: str
headers: Dict[str, str]
job_status: ConfigurationJobStatus
error_message: str
last_complete: str
last_error: str
logpush_dataset: Literal["opentelemetry-traces", "opentelemetry-logs"]
One of the following:
"opentelemetry-traces"
"opentelemetry-logs"
type: Literal["logpush"]
url: str
enabled: bool
name: str
scripts: List[str]
slug: str
class DestinationCreateResponse: …
configuration: Configuration
destination_conf: str
logpush_dataset: Literal["opentelemetry-traces", "opentelemetry-logs"]
One of the following:
"opentelemetry-traces"
"opentelemetry-logs"
logpush_job: float
type: Literal["logpush"]
url: str
enabled: bool
name: str
scripts: List[str]
slug: str
class DestinationUpdateResponse: …
configuration: Configuration
destination_conf: str
logpush_dataset: Literal["opentelemetry-traces", "opentelemetry-logs"]
One of the following:
"opentelemetry-traces"
"opentelemetry-logs"
logpush_job: float
type: Literal["logpush"]
url: str
enabled: bool
name: str
scripts: List[str]
slug: str
class DestinationDeleteResponse: …
configuration: Configuration
destination_conf: str
logpush_dataset: Literal["opentelemetry-traces", "opentelemetry-logs"]
One of the following:
"opentelemetry-traces"
"opentelemetry-logs"
logpush_job: float
type: Literal["logpush"]
url: str
enabled: bool
name: str
scripts: List[str]
slug: str