API Reference

Workers

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Observability

ObservabilityTelemetry

List keys

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

Run a query

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

List values

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

ModelsExpand Collapse

TelemetryKeysResponse { key, lastSeenAt, type }

key: string

lastSeenAt: number

type: "string" or "boolean" or "number"

One of the following:

"string"

"boolean"

"number"

TelemetryQueryResponse { run, statistics, agents, 5 more }

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

A Workers Observability Query Object

id: string

accountId: string

dry: boolean

granularity: number

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

id: string

adhoc: boolean

If the query wasn’t explcitly saved

created: string

createdBy: string

description: string

maxLength1000

name: string

Query name

maxLength250

minLength1

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

calculations: optional array of { operator, alias, key, keyType }

Create Calculations to compute as part of the query.

operator: "uniq" or "count" or "max" or 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 string

key: optional string

keyType: optional "string" or "number" or "boolean"

One of the following:

"string"

"number"

"boolean"

datasets: optional array of string

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

filterCombination: optional "and" or "or" or "AND" or "OR"

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

One of the following:

"and"

"or"

"AND"

"OR"

filters: optional array of { filterCombination, filters, kind } or { key, operation, type, 2 more }

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

One of the following:

{ filterCombination, filters, kind }

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

One of the following:

"and"

"or"

"AND"

"OR"

filters: array of unknown

kind: "group"

WorkersObservabilityFilterLeaf { key, operation, type, 2 more }

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: string

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: "includes" or "not_includes" or "starts_with" or 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: "string" or "number" or "boolean"

One of the following:

"string"

"number"

"boolean"

kind: optional "filter"

value: optional string or number or boolean

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:

string

number

boolean

groupBys: optional array of { type, value }

Define how to group the results of the query.

type: "string" or "number" or "boolean"

One of the following:

"string"

"number"

"boolean"

value: string

havings: optional array of { key, operation, value }

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

key: string

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

One of the following:

"eq"

"neq"

"gt"

"gte"

"lt"

"lte"

value: number

limit: optional number

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

maximum100

minimum0

needle: optional { value, isRegex, matchCase }

Define an expression to search using full-text search.

value:

isRegex: optional boolean

matchCase: optional boolean

orderBy: optional { value, order }

Configure the order of the results returned by the query.

value: string

Configure which Calculation to order the results by.

order: optional "asc" or "desc"

Set the order of the results

One of the following:

"asc"

"desc"

updated: string

updatedBy: string

status: "STARTED" or "COMPLETED"

One of the following:

"STARTED"

"COMPLETED"

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

created: optional string

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

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: optional number

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

updated: optional string

statistics: { bytes_read, elapsed, rows_read, abr_level }

The statistics object contains information about query performance from the database, it does not include any 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: optional number

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

agents: optional array of { agentClass, eventTypeCounts, firstEventMs, 5 more }

agentClass: string

eventTypeCounts: map[number]

firstEventMs: number

hasErrors: boolean

lastEventMs: number

namespace: string

service: string

totalEvents: number

calculations: optional array of { aggregates, calculation, series, alias }

aggregates: array of { count, interval, sampleInterval, 2 more }

count: number

interval: number

sampleInterval: number

value: number

groups: optional array of { key, value }

key: string

value: string or number or boolean

One of the following:

string

number

boolean

calculation: string

series: array of { data, time }

data: array of { count, interval, sampleInterval, 4 more }

count: number

interval: number

sampleInterval: number

value: number

firstSeen: optional string

groups: optional array of { key, value }

key: string

value: string or number or boolean

One of the following:

string

number

boolean

lastSeen: optional string

time: string

alias: optional string

compare: optional array of { aggregates, calculation, series, alias }

aggregates: array of { count, interval, sampleInterval, 2 more }

count: number

interval: number

sampleInterval: number

value: number

groups: optional array of { key, value }

key: string

value: string or number or boolean

One of the following:

string

number

boolean

calculation: string

series: array of { data, time }

data: array of { count, interval, sampleInterval, 4 more }

count: number

interval: number

sampleInterval: number

value: number

firstSeen: optional string

groups: optional array of { key, value }

key: string

value: string or number or boolean

One of the following:

string

number

boolean

lastSeen: optional string

time: string

alias: optional string

events: optional { count, events, fields, series }

count: optional number

events: optional array of { "$metadata", dataset, source, 3 more }

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

id: string

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

account: optional string

cloudService: optional string

coldStart: optional number

exclusiveMinimum

minimum0

cost: optional number

exclusiveMinimum

minimum0

duration: optional number

exclusiveMinimum

minimum0

endTime: optional number

minimum0

error: optional string

errorTemplate: optional string

fingerprint: optional string

level: optional string

message: optional string

messageTemplate: optional string

metricName: optional string

origin: optional string

parentSpanId: optional string

provider: optional string

region: optional string

requestId: optional string

service: optional string

spanId: optional string

spanName: optional string

stackId: optional string

startTime: optional number

minimum0

statusCode: optional number

exclusiveMinimum

minimum0

traceDuration: optional number

exclusiveMinimum

minimum0

traceId: optional string

transactionName: optional string

trigger: optional string

type: optional string

url: optional string

dataset: string

source: string or unknown

One of the following:

string

unknown

timestamp: number

minimum0

"$containers": optional unknown

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

"$workers": optional { eventType, requestId, scriptName, 7 more } or { cpuTimeMs, eventType, outcome, 11 more }

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

One of the following:

{ eventType, requestId, scriptName, 7 more }

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

One of the following:

"fetch"

"scheduled"

"alarm"

"cron"

"queue"

"email"

"tail"

"rpc"

"websocket"

"workflow"

"unknown"

requestId: string

scriptName: string

durableObjectId: optional string

entrypoint: optional string

event: optional map[unknown]

executionModel: optional "durableObject" or "stateless"

One of the following:

"durableObject"

"stateless"

outcome: optional string

scriptVersion: optional { id, message, tag }

id: optional string

message: optional string

tag: optional string

truncated: optional boolean

{ cpuTimeMs, eventType, outcome, 11 more }

cpuTimeMs: number

eventType: "fetch" or "scheduled" or "alarm" or 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: optional array of { channel, message, timestamp }

channel: string

message: string

timestamp: number

dispatchNamespace: optional string

durableObjectId: optional string

entrypoint: optional string

event: optional map[unknown]

executionModel: optional "durableObject" or "stateless"

One of the following:

"durableObject"

"stateless"

scriptVersion: optional { id, message, tag }

id: optional string

message: optional string

tag: optional string

truncated: optional boolean

fields: optional array of { key, type }

key: string

type: string

series: optional array of { data, time }

data: array of { aggregates, count, interval, 3 more }

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

Deprecated_count: number

exclusiveMinimum

minimum0

Deprecated_interval: number

exclusiveMinimum

minimum0

Deprecated_firstSeen: optional string

Deprecated_lastSeen: optional string

Deprecatedbin: optional unknown

count: number

interval: number

sampleInterval: number

errors: optional number

groups: optional map[string or number or boolean]

Groups in the query results.

One of the following:

string

number

boolean

time: string

invocations: optional map[array of { "$metadata", dataset, source, 3 more } ]

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

id: string

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

account: optional string

cloudService: optional string

coldStart: optional number

exclusiveMinimum

minimum0

cost: optional number

exclusiveMinimum

minimum0

duration: optional number

exclusiveMinimum

minimum0

endTime: optional number

minimum0

error: optional string

errorTemplate: optional string

fingerprint: optional string

level: optional string

message: optional string

messageTemplate: optional string

metricName: optional string

origin: optional string

parentSpanId: optional string

provider: optional string

region: optional string

requestId: optional string

service: optional string

spanId: optional string

spanName: optional string

stackId: optional string

startTime: optional number

minimum0

statusCode: optional number

exclusiveMinimum

minimum0

traceDuration: optional number

exclusiveMinimum

minimum0

traceId: optional string

transactionName: optional string

trigger: optional string

type: optional string

url: optional string

dataset: string

source: string or unknown

One of the following:

string

unknown

timestamp: number

minimum0

"$containers": optional unknown

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

"$workers": optional { eventType, requestId, scriptName, 7 more } or { cpuTimeMs, eventType, outcome, 11 more }

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

One of the following:

{ eventType, requestId, scriptName, 7 more }

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

One of the following:

"fetch"

"scheduled"

"alarm"

"cron"

"queue"

"email"

"tail"

"rpc"

"websocket"

"workflow"

"unknown"

requestId: string

scriptName: string

durableObjectId: optional string

entrypoint: optional string

event: optional map[unknown]

executionModel: optional "durableObject" or "stateless"

One of the following:

"durableObject"

"stateless"

outcome: optional string

scriptVersion: optional { id, message, tag }

id: optional string

message: optional string

tag: optional string

truncated: optional boolean

{ cpuTimeMs, eventType, outcome, 11 more }

cpuTimeMs: number

eventType: "fetch" or "scheduled" or "alarm" or 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: optional array of { channel, message, timestamp }

channel: string

message: string

timestamp: number

dispatchNamespace: optional string

durableObjectId: optional string

entrypoint: optional string

event: optional map[unknown]

executionModel: optional "durableObject" or "stateless"

One of the following:

"durableObject"

"stateless"

scriptVersion: optional { id, message, tag }

id: optional string

message: optional string

tag: optional string

truncated: optional boolean

traces: optional array of { rootSpanName, rootTransactionName, service, 6 more }

rootSpanName: string

rootTransactionName: string

service: array of string

spans: number

traceDurationMs: number

traceEndMs: number

traceId: string

traceStartMs: number

errors: optional array of string

TelemetryValuesResponse { dataset, key, type, value }

dataset: string

key: string

type: "string" or "boolean" or "number"

One of the following:

"string"

"boolean"

"number"

value: string or number or boolean

One of the following:

string

number

boolean

ObservabilityDestinations

Get Destinations

GET/accounts/{account_id}/workers/observability/destinations

Create Destination

POST/accounts/{account_id}/workers/observability/destinations

Update Destination

PATCH/accounts/{account_id}/workers/observability/destinations/{slug}

Delete Destination

DELETE/accounts/{account_id}/workers/observability/destinations/{slug}

ModelsExpand Collapse

DestinationListResponse { configuration, enabled, name, 2 more }

configuration: { destination_conf, headers, jobStatus, 3 more }

destination_conf: string

headers: map[string]

jobStatus: { error_message, last_complete, last_error }

error_message: string

last_complete: string

last_error: string

logpushDataset: "opentelemetry-traces" or "opentelemetry-logs"

One of the following:

"opentelemetry-traces"

"opentelemetry-logs"

type: "logpush"

url: string

enabled: boolean

name: string

scripts: array of string

slug: string

DestinationCreateResponse { configuration, enabled, name, 2 more }

configuration: { destination_conf, logpushDataset, logpushJob, 2 more }

destination_conf: string

logpushDataset: "opentelemetry-traces" or "opentelemetry-logs"

One of the following:

"opentelemetry-traces"

"opentelemetry-logs"

logpushJob: number

type: "logpush"

url: string

enabled: boolean

name: string

scripts: array of string

slug: string

DestinationUpdateResponse { configuration, enabled, name, 2 more }

configuration: { destination_conf, logpushDataset, logpushJob, 2 more }

destination_conf: string

logpushDataset: "opentelemetry-traces" or "opentelemetry-logs"

One of the following:

"opentelemetry-traces"

"opentelemetry-logs"

logpushJob: number

type: "logpush"

url: string

enabled: boolean

name: string

scripts: array of string

slug: string

DestinationDeleteResponse { configuration, enabled, name, 2 more }

configuration: { destination_conf, logpushDataset, logpushJob, 2 more }

destination_conf: string

logpushDataset: "opentelemetry-traces" or "opentelemetry-logs"

One of the following:

"opentelemetry-traces"

"opentelemetry-logs"

logpushJob: number

type: "logpush"

url: string

enabled: boolean

name: string

scripts: array of string

slug: string