API Reference

Workers

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Observability

ObservabilityTelemetry

List keys

client.workers.observability.telemetry.keys(TelemetryKeysParams { account_id, datasets, filters, 5 more } params, RequestOptionsoptions?): SinglePage<TelemetryKeysResponse { key, lastSeenAt, type } >

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

Run a query

client.workers.observability.telemetry.query(TelemetryQueryParams { account_id, queryId, timeframe, 11 more } params, RequestOptionsoptions?): TelemetryQueryResponse { run, statistics, agents, 5 more }

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

List values

client.workers.observability.telemetry.values(TelemetryValuesParams { account_id, datasets, key, 5 more } params, RequestOptionsoptions?): SinglePage<TelemetryValuesResponse { dataset, key, type, value } >

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

ModelsExpand Collapse

TelemetryKeysResponse { key, lastSeenAt, type }

key: string

lastSeenAt: number

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

One of the following:

"string"

"boolean"

"number"

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

name: string

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

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

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>

count: number

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>

count: number

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>

count: number

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>

count: number

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

count: number

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.

TelemetryValuesResponse { dataset, key, type, value }

dataset: string

key: string

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

One of the following:

"string"

"boolean"

"number"

value: string | number | boolean

One of the following:

string

number

boolean

ObservabilityDestinations

Get Destinations

client.workers.observability.destinations.list(DestinationListParams { account_id, order, orderBy, 2 more } params, RequestOptionsoptions?): SinglePage<DestinationListResponse { configuration, enabled, name, 2 more } >

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

Create Destination

client.workers.observability.destinations.create(DestinationCreateParams { account_id, configuration, enabled, 2 more } params, RequestOptionsoptions?): DestinationCreateResponse { configuration, enabled, name, 2 more }

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

Update Destination

client.workers.observability.destinations.update(stringslug, DestinationUpdateParams { account_id, configuration, enabled } params, RequestOptionsoptions?): DestinationUpdateResponse { configuration, enabled, name, 2 more }

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

Delete Destination

client.workers.observability.destinations.delete(stringslug, DestinationDeleteParams { account_id } params, RequestOptionsoptions?): DestinationDeleteResponse { configuration, enabled, name, 2 more }

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

ModelsExpand Collapse

DestinationListResponse { configuration, enabled, name, 2 more }

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

destination_conf: string

headers: Record<string, string>

jobStatus: JobStatus { error_message, last_complete, last_error }

error_message: string

last_complete: string

last_error: string

logpushDataset: "opentelemetry-traces" | "opentelemetry-logs"

One of the following:

"opentelemetry-traces"

"opentelemetry-logs"

type: "logpush"

url: string

enabled: boolean

name: string

scripts: Array<string>

slug: string

DestinationCreateResponse { configuration, enabled, name, 2 more }

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

destination_conf: string

logpushDataset: "opentelemetry-traces" | "opentelemetry-logs"

One of the following:

"opentelemetry-traces"

"opentelemetry-logs"

logpushJob: number

type: "logpush"

url: string

enabled: boolean

name: string

scripts: Array<string>

slug: string

DestinationUpdateResponse { configuration, enabled, name, 2 more }

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

destination_conf: string

logpushDataset: "opentelemetry-traces" | "opentelemetry-logs"

One of the following:

"opentelemetry-traces"

"opentelemetry-logs"

logpushJob: number

type: "logpush"

url: string

enabled: boolean

name: string

scripts: Array<string>

slug: string

DestinationDeleteResponse { configuration, enabled, name, 2 more }

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

destination_conf: string

logpushDataset: "opentelemetry-traces" | "opentelemetry-logs"

One of the following:

"opentelemetry-traces"

"opentelemetry-logs"

logpushJob: number

type: "logpush"

url: string

enabled: boolean

name: string

scripts: Array<string>

slug: string