## Create a sharable link to a query result

`client.workers.observability.sharedQueries.create(SharedQueryCreateParamsparams, RequestOptionsoptions?): SharedQueryCreateResponse`

**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.

### Parameters

- `params: SharedQueryCreateParams`

  - `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.

    - `"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'.

  - `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 | UnionMember1>`

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

      - `UnionMember0`

        - `operator: "count" | "COUNT"`

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

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

          - `"string"`

          - `"number"`

          - `"boolean"`

      - `UnionMember1`

        - `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.

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

          - `"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'.

      - `"and"`

      - `"or"`

      - `"AND"`

      - `"OR"`

    - `filters?: Array<UnionMember0 | WorkersObservabilityFilterLeaf>`

      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.

      - `UnionMember0`

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

          - `"and"`

          - `"or"`

          - `"AND"`

          - `"OR"`

        - `filters: Array<UnionMember0 | WorkersObservabilityFilterLeaf>`

          - `UnionMember0`

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

              - `"and"`

              - `"or"`

              - `"AND"`

              - `"OR"`

            - `filters: Array<unknown>`

            - `kind: "group"`

              - `"group"`

          - `WorkersObservabilityFilterLeaf`

            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.

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

              - `"string"`

              - `"number"`

              - `"boolean"`

            - `kind?: "filter"`

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

              - `"filter"`

            - `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).

              - `string`

              - `number`

              - `boolean`

        - `kind: "group"`

          - `"group"`

      - `WorkersObservabilityFilterLeaf`

        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.

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

          - `"string"`

          - `"number"`

          - `"boolean"`

        - `kind?: "filter"`

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

          - `"filter"`

        - `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).

          - `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.

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

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

    - `needle?: Needle`

      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.

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

      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.

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

    - `"traces"`

    - `"events"`

    - `"calculations"`

    - `"invocations"`

    - `"requests"`

    - `"agents"`

### Returns

- `SharedQueryCreateResponse`

  - `id: string`

    Specify the ID of the shared query.

### Example

```typescript
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);
```

#### Response

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