Skip to content
Cloudflare API
Start here
API Reference
Workers
Scripts
Settings

Patch Script Settings

PATCH/accounts/{account_id}/workers/scripts/{script_name}/script-settings

Patch script-level settings when using Worker Versions. Including but not limited to Logpush and Tail Consumers.

Security
API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
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
Accepted Permissions (at least one required)
Workers Scripts Write
Path ParametersExpand Collapse
account_id: string

Identifier.

maxLength32
script_name: string

Name of the script, used in URLs and route configuration.

Body ParametersJSONExpand Collapse
logpush: optional boolean

Whether Logpush is turned on for the Worker.

observability: optional object { enabled, head_sampling_rate, logs, 2 more }

Observability settings for the Worker.

enabled: boolean

Whether observability is enabled for the Worker.

head_sampling_rate: optional number

The sampling rate for incoming requests. From 0 to 1 (1 = 100%, 0.1 = 10%). Default is 1.

logs: optional object { enabled, invocation_logs, destinations, 2 more }

Log settings for the Worker.

enabled: boolean

Whether logs are enabled for the Worker.

invocation_logs: boolean

Whether invocation logs are enabled for the Worker.

destinations: optional array of string

A list of destinations where logs will be exported to.

head_sampling_rate: optional number

The sampling rate for logs. From 0 to 1 (1 = 100%, 0.1 = 10%). Default is 1.

persist: optional boolean

Whether log persistence is enabled for the Worker.

redact_query_string: optional boolean

Whether query strings are removed from request URLs in logs and traces.

traces: optional object { destinations, enabled, head_sampling_rate, 2 more }

Trace settings for the Worker.

destinations: optional array of string

A list of destinations where traces will be exported to.

enabled: optional boolean

Whether traces are enabled for the Worker.

head_sampling_rate: optional number

The sampling rate for traces. From 0 to 1 (1 = 100%, 0.1 = 10%). Default is 1.

persist: optional boolean

Whether trace persistence is enabled for the Worker.

propagation_policy: optional "authenticated" or "accept"

Controls how inbound trace context (traceparent/tracestate) headers on incoming requests are handled. “authenticated” honors inbound trace context only when accompanied by a valid trace auth token. “accept” unconditionally accepts inbound trace context. Requires the trace propagation feature to be enabled. Returns null when the trace propagation feature is not enabled for the account.

One of the following:
"authenticated"
"accept"
tags: optional array of string

Tags associated with the Worker.

tail_consumers: optional array of ConsumerScript { service, environment, namespace }

List of Workers that will consume logs from the attached Worker.

service: string

Name of Worker that is to be the consumer.

environment: optional string

Optional environment if the Worker utilizes one.

namespace: optional string

Optional dispatch namespace the script belongs to.

ReturnsExpand Collapse
errors: array of object { code, message, documentation_url, source }
code: number
minimum1000
message: string
documentation_url: optional string
source: optional object { pointer }
pointer: optional string
messages: array of object { code, message, documentation_url, source }
code: number
minimum1000
message: string
documentation_url: optional string
source: optional object { pointer }
pointer: optional string
result: ScriptSetting { logpush, observability, tags, tail_consumers }
logpush: optional boolean

Whether Logpush is turned on for the Worker.

observability: optional object { enabled, head_sampling_rate, logs, 2 more }

Observability settings for the Worker.

enabled: boolean

Whether observability is enabled for the Worker.

head_sampling_rate: optional number

The sampling rate for incoming requests. From 0 to 1 (1 = 100%, 0.1 = 10%). Default is 1.

logs: optional object { enabled, invocation_logs, destinations, 2 more }

Log settings for the Worker.

enabled: boolean

Whether logs are enabled for the Worker.

invocation_logs: boolean

Whether invocation logs are enabled for the Worker.

destinations: optional array of string

A list of destinations where logs will be exported to.

head_sampling_rate: optional number

The sampling rate for logs. From 0 to 1 (1 = 100%, 0.1 = 10%). Default is 1.

persist: optional boolean

Whether log persistence is enabled for the Worker.

redact_query_string: optional boolean

Whether query strings are removed from request URLs in logs and traces.

traces: optional object { destinations, enabled, head_sampling_rate, 2 more }

Trace settings for the Worker.

destinations: optional array of string

A list of destinations where traces will be exported to.

enabled: optional boolean

Whether traces are enabled for the Worker.

head_sampling_rate: optional number

The sampling rate for traces. From 0 to 1 (1 = 100%, 0.1 = 10%). Default is 1.

persist: optional boolean

Whether trace persistence is enabled for the Worker.

propagation_policy: optional "authenticated" or "accept"

Controls how inbound trace context (traceparent/tracestate) headers on incoming requests are handled. “authenticated” honors inbound trace context only when accompanied by a valid trace auth token. “accept” unconditionally accepts inbound trace context. Requires the trace propagation feature to be enabled. Returns null when the trace propagation feature is not enabled for the account.

One of the following:
"authenticated"
"accept"
tags: optional array of string

Tags associated with the Worker.

tail_consumers: optional array of ConsumerScript { service, environment, namespace }

List of Workers that will consume logs from the attached Worker.

service: string

Name of Worker that is to be the consumer.

environment: optional string

Optional environment if the Worker utilizes one.

namespace: optional string

Optional dispatch namespace the script belongs to.

success: true

Whether the API call was successful.

Patch Script Settings

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/scripts/$SCRIPT_NAME/script-settings \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    -d '{
          "tags": [
            "my-team",
            "my-public-api"
          ]
        }'
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "logpush": false,
    "observability": {
      "enabled": true,
      "head_sampling_rate": 0.1,
      "logs": {
        "enabled": true,
        "invocation_logs": true,
        "destinations": [
          "cloudflare"
        ],
        "head_sampling_rate": 0.1,
        "persist": true
      },
      "redact_query_string": false,
      "traces": {
        "destinations": [
          "cloudflare"
        ],
        "enabled": true,
        "head_sampling_rate": 0.1,
        "persist": true,
        "propagation_policy": "authenticated"
      }
    },
    "tags": [
      "my-team",
      "my-public-api"
    ],
    "tail_consumers": [
      {
        "service": "my-log-consumer",
        "environment": "production",
        "namespace": "my-namespace"
      }
    ]
  },
  "success": true
}
Returns Examples
{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": {
    "logpush": false,
    "observability": {
      "enabled": true,
      "head_sampling_rate": 0.1,
      "logs": {
        "enabled": true,
        "invocation_logs": true,
        "destinations": [
          "cloudflare"
        ],
        "head_sampling_rate": 0.1,
        "persist": true
      },
      "redact_query_string": false,
      "traces": {
        "destinations": [
          "cloudflare"
        ],
        "enabled": true,
        "head_sampling_rate": 0.1,
        "persist": true,
        "propagation_policy": "authenticated"
      }
    },
    "tags": [
      "my-team",
      "my-public-api"
    ],
    "tail_consumers": [
      {
        "service": "my-log-consumer",
        "environment": "production",
        "namespace": "my-namespace"
      }
    ]
  },
  "success": true
}