Prepare live tail

POST/accounts/{account_id}/workers/observability/telemetry/live-tail

Prepare websocket server for live tail.

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

Path ParametersExpand Collapse

account_id: string

Body ParametersJSONExpand Collapse

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 object { filterCombination, filters, kind } or object { key, operation, type, 2 more }

Apply filters to the query. Supports nested groups via kind: ‘group’.

One of the following:

object { filterCombination, filters, kind }

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

One of the following:

"and"

"or"

"AND"

"OR"

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

One of the following:

object { 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 object { 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" or "not_includes" or "starts_with" or 27 more

Comparison operator. String operators: includes, not_includes, starts_with, ends_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"

"ends_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"

"ENDS_WITH"

type: "string" or "number" or "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 "filter"

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

value: optional string or number or 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 object { 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" or "not_includes" or "starts_with" or 27 more

One of the following:

"includes"

"not_includes"

"starts_with"

"ends_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"

"ENDS_WITH"

type: "string" or "number" or "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 "filter"

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

value: optional string or number or boolean

One of the following:

string

number

boolean

scriptId: optional string

ReturnsExpand Collapse

errors: array of object { message }

message: string

messages: array of object { message }

message: "Successful request"

result: object { wsUrl }

wsUrl: string

WebSocket URL clients connect to in order to stream live tail events.

formaturi

success: true

Prepare live tail

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/observability/telemetry/live-tail \
    -H 'Content-Type: application/json' \
    -H "X-Auth-Email: $CLOUDFLARE_EMAIL" \
    -H "X-Auth-Key: $CLOUDFLARE_API_KEY" \
    -d '{}'

{
  "errors": [
    {
      "message": "message"
    }
  ],
  "messages": [
    {
      "message": "Successful request"
    }
  ],
  "result": {
    "wsUrl": "https://example.com"
  },
  "success": true
}

Returns Examples

{
  "errors": [
    {
      "message": "message"
    }
  ],
  "messages": [
    {
      "message": "Successful request"
    }
  ],
  "result": {
    "wsUrl": "https://example.com"
  },
  "success": true
}