Request Trace

client.requestTracers.traces.create(, ?): TraceCreateResponse { status_code, trace }

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

params: TraceCreateParams { account_id, method, url, 6 more }

account_id: string

Path param: Identifier.

maxLength32

method: string

Body param: HTTP Method of tracing request

url: string

Body param: URL to which perform tracing request

body?: Body

Body param

base64?: string

Base64 encoded request body

json?: unknown

Arbitrary json as request body

plain_text?: string

Request body as plain text

context?: Context

Body param: Additional request parameters

bot_score?: number

Bot score used for evaluating tracing request processing

geoloc?: Geoloc { city, continent, is_eu_country, 7 more }

Geodata for tracing request

city?: string

continent?: string

is_eu_country?: boolean

iso_code?: string

latitude?: number

longitude?: number

postal_code?: string

region_code?: string

subdivision_2_iso_code?: string

timezone?: string

skip_challenge?: boolean

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

threat_score?: number

Threat score used for evaluating tracing request processing

cookies?: Record<string, string>

Body param: Cookies added to tracing request

headers?: Record<string, string>

Body param: Headers added to tracing request

protocol?: string

Body param: HTTP Protocol of tracing request

skip_response?: boolean

Body param: Skip sending the request to the Origin server after all rules evaluation

ReturnsExpand Collapse

TraceCreateResponse { status_code, trace }

Trace result with an origin status code

status_code?: number

HTTP Status code of zone response

trace?: Trace { }

TraceItem { action, action_parameters, description, 7 more }

List of steps acting on request/response

action?: string

If step type is rule, then action performed by this rule

action_parameters?: unknown

If step type is rule, then action parameters of this rule as JSON

description?: string

If step type is rule or ruleset, the description of this entity

expression?: string

If step type is rule, then expression used to match for this rule

kind?: string

If step type is ruleset, then kind of this ruleset

matched?: boolean

Whether tracing step affected tracing request/response

name?: string

If step type is ruleset, then name of this ruleset

step_name?: string

Tracing step identifying name

trace?: Trace { }

type?: string

Tracing step type

Request Trace

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 trace = await client.requestTracers.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',
});

console.log(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"
      }
    ]
  }
}