API Reference

Rules Trace

Traces

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Request Trace

client.RequestTracers.Traces.New(ctx, params) (*TraceNewResponse, error)

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 TraceNewParams

AccountID param.Field[string]

Path param: Identifier.

maxLength32

Method param.Field[string]

Body param: HTTP Method of tracing request

URL param.Field[string]

Body param: URL to which perform tracing request

Body param.Field[TraceNewParamsBody]Optional

Body param

Base64 stringOptional

Base64 encoded request body

Json unknownOptional

Arbitrary json as request body

PlainText stringOptional

Request body as plain text

Context param.Field[TraceNewParamsContext]Optional

Body param: Additional request parameters

BotScore int64Optional

Bot score used for evaluating tracing request processing

Geoloc TraceNewParamsContextGeolocOptional

Geodata for tracing request

City stringOptional

Continent stringOptional

IsEuCountry boolOptional

ISOCode stringOptional

Latitude float64Optional

Longitude float64Optional

PostalCode stringOptional

RegionCode stringOptional

Subdivision2ISOCode stringOptional

Timezone stringOptional

SkipChallenge boolOptional

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

ThreatScore int64Optional

Threat score used for evaluating tracing request processing

Cookies param.Field[map[string, string]]Optional

Body param: Cookies added to tracing request

Headers param.Field[map[string, string]]Optional

Body param: Headers added to tracing request

Protocol param.Field[string]Optional

Body param: HTTP Protocol of tracing request

SkipResponse param.Field[bool]Optional

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

ReturnsExpand Collapse

type TraceNewResponse struct{…}

Trace result with an origin status code

StatusCode int64Optional

HTTP Status code of zone response

Trace TraceOptional

Request Trace

Go

HTTP

TypeScript

Python

Go

Terraform

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/option"
  "github.com/cloudflare/cloudflare-go/request_tracers"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIKey("144c9defac04969c7bfad8efaa8ea194"),
    option.WithAPIEmail("user@example.com"),
  )
  trace, err := client.RequestTracers.Traces.New(context.TODO(), request_tracers.TraceNewParams{
    AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    Method: cloudflare.F("PUT"),
    URL: cloudflare.F("https://some.zone/some_path"),
    Body: cloudflare.F(request_tracers.TraceNewParamsBody{
      Base64: cloudflare.F("c29tZV9yZXF1ZXN0X2JvZHk="),
    }),
    Context: cloudflare.F(request_tracers.TraceNewParamsContext{
      Geoloc: cloudflare.F(request_tracers.TraceNewParamsContextGeoloc{
        City: cloudflare.F("London"),
      }),
      SkipChallenge: cloudflare.F(true),
    }),
    Cookies: cloudflare.F(map[string]string{
    "cookie_name_1": "cookie_value_1",
    "cookie_name_2": "cookie_value_2",
    }),
    Headers: cloudflare.F(map[string]string{
    "header_name_1": "header_value_1",
    "header_name_2": "header_value_2",
    }),
    Protocol: cloudflare.F("HTTP/1.1"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", trace.StatusCode)
}

200 example

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

200 example

{
  "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"
      }
    ]
  }
}