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: …
run: Run

A Workers Observability Query Object

id: str
account_id: str
dry: bool
granularity: float
query: RunQuery
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: …

Filtering best practices: use observability_keys and observability_values to confirm available fields and values. If searching for errors, filter for $metadata.error exists.

key: str

Filter field name. IMPORTANT: do not guess keys. Always use verified keys from previous query results or the observability_keys response. Preferred keys: $metadata.service, $metadata.origin, $metadata.trigger, $metadata.message, $metadata.error.

operation: Literal["includes", "not_includes", "starts_with", 25 more]
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"]
One of the following:
"string"
"number"
"boolean"
kind: Optional[Literal["filter"]]
value: Optional[Union[str, float, bool, null]]

Filter comparison value. IMPORTANT: must match actual values in your logs. Verify using previous query results or the /values endpoint. Ensure value type matches the field type. String comparisons are case-sensitive unless using specific operations. Regex uses ClickHouse RE2 syntax (no lookaheads/lookbehinds); examples: ^5\d{2}$ for HTTP 5xx, \bERROR\b for word boundary.

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"]
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
created: Optional[str]
statistics: Optional[RunStatistics]
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]
statistics: Statistics

The statistics object contains information about query performance from the database, it does not include any 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]]
agent_class: str
event_type_counts: Dict[str, float]
first_event_ms: float
has_errors: bool
last_event_ms: float
namespace: str
service: str
total_events: float
calculations: Optional[List[Calculation]]
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]]
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]
count: Optional[float]
events: Optional[List[EventsEvent]]
metadata: EventsEventMetadata
id: str

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

account: Optional[str]
cloud_service: Optional[str]
cold_start: Optional[int]
exclusiveMinimum
minimum0
cost: Optional[int]
exclusiveMinimum
minimum0
duration: Optional[int]
exclusiveMinimum
minimum0
end_time: Optional[int]
minimum0
error: Optional[str]
error_template: Optional[str]
fingerprint: Optional[str]
level: Optional[str]
message: Optional[str]
message_template: Optional[str]
metric_name: Optional[str]
origin: Optional[str]
parent_span_id: Optional[str]
provider: Optional[str]
region: Optional[str]
request_id: Optional[str]
service: Optional[str]
span_id: Optional[str]
span_name: Optional[str]
stack_id: Optional[str]
start_time: Optional[int]
minimum0
status_code: Optional[int]
exclusiveMinimum
minimum0
trace_duration: Optional[int]
exclusiveMinimum
minimum0
trace_id: Optional[str]
transaction_name: Optional[str]
trigger: Optional[str]
type: Optional[str]
url: Optional[str]
dataset: str
source: Union[str, object]
One of the following:
str
object
timestamp: int
minimum0
containers: Optional[object]

Cloudflare Containers event information enriches your logs so you can easily identify and debug issues.

workers: Optional[EventsEventWorkers]

Cloudflare Workers event information enriches your logs so you can easily identify and debug 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]
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]
truncated: Optional[bool]
fields: Optional[List[EventsField]]
key: str
type: str
series: Optional[List[EventsSeries]]
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]]]
metadata: InvocationMetadata
id: str

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

account: Optional[str]
cloud_service: Optional[str]
cold_start: Optional[int]
exclusiveMinimum
minimum0
cost: Optional[int]
exclusiveMinimum
minimum0
duration: Optional[int]
exclusiveMinimum
minimum0
end_time: Optional[int]
minimum0
error: Optional[str]
error_template: Optional[str]
fingerprint: Optional[str]
level: Optional[str]
message: Optional[str]
message_template: Optional[str]
metric_name: Optional[str]
origin: Optional[str]
parent_span_id: Optional[str]
provider: Optional[str]
region: Optional[str]
request_id: Optional[str]
service: Optional[str]
span_id: Optional[str]
span_name: Optional[str]
stack_id: Optional[str]
start_time: Optional[int]
minimum0
status_code: Optional[int]
exclusiveMinimum
minimum0
trace_duration: Optional[int]
exclusiveMinimum
minimum0
trace_id: Optional[str]
transaction_name: Optional[str]
trigger: Optional[str]
type: Optional[str]
url: Optional[str]
dataset: str
source: Union[str, object]
One of the following:
str
object
timestamp: int
minimum0
containers: Optional[object]

Cloudflare Containers event information enriches your logs so you can easily identify and debug issues.

workers: Optional[InvocationWorkers]

Cloudflare Workers event information enriches your logs so you can easily identify and debug 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]
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]
truncated: Optional[bool]
traces: Optional[List[Trace]]
root_span_name: str
root_transaction_name: str
service: List[str]
spans: float
trace_duration_ms: float
trace_end_ms: float
trace_id: str
trace_start_ms: float
errors: Optional[List[str]]
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