Request Trace

request_tracers.traces.create() -> TraceCreateResponse

POST/accounts/{account_id}/request-tracer/trace

Traces a simulated HTTP request through Cloudflare’s edge to analyze how rules, settings, and configurations would process the request. Useful for debugging firewall rules, page rules, and other request transformations without sending actual traffic. Supports custom headers, cookies, body content, and geolocation context.

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

Accepted Permissions (at least one required)

Allow Request Tracer Read

ParametersExpand Collapse

account_id: str

Identifier.

maxLength32

method: str

HTTP Method of tracing request

url: str

URL to which perform tracing request

body: Optional[Body]

base64: Optional[str]

Base64 encoded request body

json: Optional[object]

Arbitrary json as request body

plain_text: Optional[str]

Request body as plain text

context: Optional[Context]

Additional request parameters

bot_score: Optional[int]

Bot score used for evaluating tracing request processing

geoloc: Optional[ContextGeoloc]

Geodata for tracing request

city: Optional[str]

continent: Optional[str]

is_eu_country: Optional[bool]

iso_code: Optional[str]

latitude: Optional[float]

longitude: Optional[float]

postal_code: Optional[str]

region_code: Optional[str]

subdivision_2_iso_code: Optional[str]

timezone: Optional[str]

skip_challenge: Optional[bool]

Whether to skip any challenges for tracing request (e.g.: captcha)

threat_score: Optional[int]

Threat score used for evaluating tracing request processing

cookies: Optional[Dict[str, str]]

Cookies added to tracing request

headers: Optional[Dict[str, str]]

Headers added to tracing request

protocol: Optional[str]

HTTP Protocol of tracing request

skip_response: Optional[bool]

Skip sending the request to the Origin server after all rules evaluation

ReturnsExpand Collapse

class TraceCreateResponse: …

Trace result with an origin status code

status_code: Optional[int]

HTTP Status code of zone response

trace: Optional[Trace]

Request Trace

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_email=os.environ.get("CLOUDFLARE_EMAIL"),  # This is the default and can be omitted
    api_key=os.environ.get("CLOUDFLARE_API_KEY"),  # This is the default and can be omitted
)
trace = client.request_tracers.traces.create(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
    method="PUT",
    url="https://some.zone/some_path",
    body={
        "base64": "c29tZV9yZXF1ZXN0X2JvZHk="
    },
    context={
        "geoloc": {
            "city": "London"
        },
        "skip_challenge": True,
    },
    cookies={
        "cookie_name_1": "cookie_value_1",
        "cookie_name_2": "cookie_value_2",
    },
    headers={
        "header_name_1": "header_value_1",
        "header_name_2": "header_value_2",
    },
    protocol="HTTP/1.1",
)
print(trace.status_code)

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "success": true,
  "result": {
    "status_code": 0,
    "trace": [
      {
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "description": "some rule",
        "expression": "ip.src ne 1.1.1.1",
        "kind": "zone",
        "matched": true,
        "name": "some ruleset name",
        "step_name": "rule_id01",
        "type": "rule"
      }
    ]
  }
}

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"
      }
    }
  ],
  "success": true,
  "result": {
    "status_code": 0,
    "trace": [
      {
        "action": "execute",
        "action_parameters": {
          "id": "4814384a9e5d4991b9815dcfc25d2f1f"
        },
        "description": "some rule",
        "expression": "ip.src ne 1.1.1.1",
        "kind": "zone",
        "matched": true,
        "name": "some ruleset name",
        "step_name": "rule_id01",
        "type": "rule"
      }
    ]
  }
}