Create a sharable link to a query result

client.workers.observability.sharedQueries.create(, ?): SharedQueryCreateResponse { id }

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

Shared queries store the results of a previously run query, allowing you to share the results with others.

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

ParametersExpand Collapse

params: SharedQueryCreateParams { account_id, queryId, timeframe, 12 more }

account_id: string

Path param: Your Cloudflare account ID.

queryId: string

Body param: Identifier for the query. When parameters are omitted, this ID is used to load a previously saved query’s parameters. When providing parameters inline, pass any identifier (e.g. an ad-hoc ID).

timeframe: Timeframe

Body param: Timeframe for the query using Unix timestamps in milliseconds. Narrower timeframes produce faster responses and more specific results.

from: number

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

to: number

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

chart?: boolean

Body param: When true, includes time-series data in the response.

chartType?: "timeseries_and_aggregate" | "timeseries" | "aggregate" | "distribution"

Body param: Controls the SQL shape and response payload for the ‘calculations’ view. Omitted or ‘timeseries_and_aggregate’: current behaviour — both the time-series and aggregate queries. ‘timeseries’: time-series only. ‘aggregate’: aggregate only. ‘distribution’: a bucketed 2D histogram (time × value buckets) returned in ‘distribution’ instead of ‘calculations’. ‘distribution’ is not compatible with ‘compare’ — combining them returns a 400.

One of the following:

"timeseries_and_aggregate"

"timeseries"

"aggregate"

"distribution"

compare?: boolean

Body param: When true, includes a comparison dataset from the previous time period of equal length.

dry?: boolean

Body param: When true, executes the query without persisting the results. Useful for validation or previewing.

granularity?: number

Body param: Number of time-series buckets. Only used when view is ‘calculations’. Omit to let the system auto-detect an appropriate granularity.

ignoreSeries?: boolean

Body param: When true, omits time-series data from the response and returns only aggregated values. Reduces response size when series are not needed.

limit?: number

Body param: Maximum number of events to return when view is ‘events’. Also controls the number of group-by rows when view is ‘calculations’.

maximum2000

offset?: string

Body param: Cursor for pagination in event, trace, invocation, and agent views. Pass the $metadata.id of the last event, the trace cursor, or AgentRun.id to fetch the next page.

offsetBy?: number

Body param: Numeric offset for paginating grouped/pattern results (top-N lists). Use together with limit. Not used by cursor-based pagination.

offsetDirection?: string

Body param: Pagination direction: ‘next’ for forward, ‘prev’ for backward.

parameters?: Parameters

Body param: Query parameters defining what data to retrieve — filters, calculations, group-bys, and ordering. In practice this should always be provided for ad-hoc queries. Only omit when executing a previously saved query by queryId. Use the keys and values endpoints to discover available fields before building filters.

calculations?: Array<UnionMember0 { operator, alias, key, keyType } | UnionMember1 { key, operator, alias, keyType } >

Aggregation calculations to compute (e.g. count, avg, p99). Each calculation produces aggregate values and optional time-series data.

One of the following:

UnionMember0 { operator, alias, key, keyType }

operator: "count" | "COUNT"

Aggregation operator to apply. Examples: count, avg, sum, min, max, median, p90, p95, p99, uniq, stddev, variance.

One of the following:

"count"

"COUNT"

alias?: string

Custom label for this calculation in the results. Useful for distinguishing multiple calculations.

key?: string

Field name to calculate over. Must exist in the data — verify with the keys endpoint. Required for every operator except count, which aggregates whole rows and may omit it.

keyType?: "string" | "number" | "boolean"

Data type of the key. Required when key is provided to ensure correct aggregation.

One of the following:

"string"

"number"

"boolean"

UnionMember1 { key, operator, alias, keyType }

key: string

Field name to calculate over. Must exist in the data — verify with the keys endpoint. Required for every operator except count, which aggregates whole rows and may omit it.

operator: "uniq" | "max" | "min" | 33 more

Aggregation operator to apply. Examples: count, avg, sum, min, max, median, p90, p95, p99, uniq, stddev, variance.

One of the following:

"uniq"

"max"

"min"

"sum"

"avg"

"median"

"p001"

"p01"

"p05"

"p10"

"p25"

"p75"

"p90"

"p95"

"p99"

"p999"

"stddev"

"variance"

"COUNT_DISTINCT"

"MAX"

"MIN"

"SUM"

"AVG"

"MEDIAN"

"P001"

"P01"

"P05"

"P10"

"P25"

"P75"

"P90"

"P95"

"P99"

"P999"

"STDDEV"

"VARIANCE"

alias?: string

Custom label for this calculation in the results. Useful for distinguishing multiple calculations.

keyType?: "string" | "number" | "boolean"

Data type of the key. Required when key is provided to ensure correct aggregation.

One of the following:

"string"

"number"

"boolean"

datasets?: Array<string>

Datasets to query. Leave empty to query all available datasets.

filterCombination?: "and" | "or" | "AND" | "OR"

Logical operator for combining top-level filters: ‘and’ (all must match) or ‘or’ (any must match). Defaults to ‘and’.

One of the following:

"and"

"or"

"AND"

"OR"

filters?: Array<UnionMember0 { filterCombination, filters, kind } | WorkersObservabilityFilterLeaf { key, operation, type, 2 more } >

Filters to narrow query results. Use the keys and values endpoints to discover available fields before building filters. Supports nested groups via kind: ‘group’. Maximum nesting depth is 4.

One of the following:

UnionMember0 { filterCombination, filters, kind }

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

One of the following:

"and"

"or"

"AND"

"OR"

filters: Array<UnionMember0 { filterCombination, filters, kind } | WorkersObservabilityFilterLeaf { key, operation, type, 2 more } >

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

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

operation: "includes" | "not_includes" | "starts_with" | 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" | "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

One of the following:

string

number

boolean

groupBys?: Array<GroupBy>

Fields to group calculation results by. Only applicable when the query view is ‘calculations’. Produces per-group aggregate values.

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

Data type of the group-by field.

One of the following:

"string"

"number"

"boolean"

value: string

Field name to group results by (e.g. $metadata.service, $metadata.statusCode).

havings?: Array<Having>

Post-aggregation filters applied to calculation results. Use to filter groups after aggregation (e.g. only groups where count > 100).

key: string

Calculation alias or operator to filter on after aggregation.

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

Numeric comparison operator: eq, neq, gt, gte, lt, lte.

One of the following:

"eq"

"neq"

"gt"

"gte"

"lt"

"lte"

value: number

Threshold value to compare the calculation result against.

limit?: number

Maximum number of group-by rows to return in calculation results. A value of 10 is a sensible default for most use cases.

maximum2000

minimum0

needle?: Needle { value, isRegex, matchCase }

Full-text search expression applied across all event fields. Matches events containing the specified text.

value: string | number | boolean

The text or pattern to search for.

maxLength1000

One of the following:

string

number

boolean

isRegex?: boolean

When true, treats the value as a regular expression (RE2 syntax).

matchCase?: boolean

When true, performs a case-sensitive search. Defaults to case-insensitive.

orderBy?: OrderBy { value, order }

Ordering for grouped calculation results. Only effective when a group-by is present.

value: string

Alias of the calculation to order results by. Must match the alias (or operator) of a calculation in the query.

order?: "asc" | "desc"

Sort direction: ‘asc’ for ascending, ‘desc’ for descending.

One of the following:

"asc"

"desc"

view?: "traces" | "events" | "calculations" | 3 more

Body param: Controls the shape of the response. ‘events’: individual log lines matching the query. ‘calculations’: aggregated metrics (count, avg, p99, etc.) with optional group-by breakdowns and time-series. ‘invocations’: events grouped by request ID. ‘traces’: distributed trace summaries. ‘agents’: agent-specific trace summaries.

One of the following:

"traces"

"events"

"calculations"

"invocations"

"requests"

"agents"

ReturnsExpand Collapse

SharedQueryCreateResponse { id }

id: string

Specify the ID of the shared query.

Create a sharable link to a query result

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiEmail: process.env['CLOUDFLARE_EMAIL'], // This is the default and can be omitted
  apiKey: process.env['CLOUDFLARE_API_KEY'], // This is the default and can be omitted
});

const sharedQuery = await client.workers.observability.sharedQueries.create({
  account_id: 'account_id',
  queryId: 'queryId',
  timeframe: { from: 0, to: 0 },
});

console.log(sharedQuery.id);

{
  "errors": [
    {
      "message": "message"
    }
  ],
  "messages": [
    {
      "message": "Successful request"
    }
  ],
  "result": {
    "id": "id"
  },
  "success": true
}

Returns Examples

{
  "errors": [
    {
      "message": "message"
    }
  ],
  "messages": [
    {
      "message": "Successful request"
    }
  ],
  "result": {
    "id": "id"
  },
  "success": true
}