# Traces

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

### Parameters

- `params TraceNewParams`

  - `AccountID param.Field[string]`

    Path param: Identifier.

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

    Body param

    - `Base64 string`

      Base64 encoded request body

    - `Json unknown`

      Arbitrary json as request body

    - `PlainText string`

      Request body as plain text

  - `Context param.Field[TraceNewParamsContext]`

    Body param: Additional request parameters

    - `BotScore int64`

      Bot score used for evaluating tracing request processing

    - `Geoloc TraceNewParamsContextGeoloc`

      Geodata for tracing request

      - `City string`

      - `Continent string`

      - `IsEuCountry bool`

      - `ISOCode string`

      - `Latitude float64`

      - `Longitude float64`

      - `PostalCode string`

      - `RegionCode string`

      - `Subdivision2ISOCode string`

      - `Timezone string`

    - `SkipChallenge bool`

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

    - `ThreatScore int64`

      Threat score used for evaluating tracing request processing

  - `Cookies param.Field[map[string, string]]`

    Body param: Cookies added to tracing request

  - `Headers param.Field[map[string, string]]`

    Body param: Headers added to tracing request

  - `Protocol param.Field[string]`

    Body param: HTTP Protocol of tracing request

  - `SkipResponse param.Field[bool]`

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

### Returns

- `type TraceNewResponse struct{…}`

  Trace result with an origin status code

  - `StatusCode int64`

    HTTP Status code of zone response

  - `Trace Trace`

### Example

```go
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)
}
```

#### Response

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

## Domain Types

### Trace

- `type Trace []TraceItem`

### Trace Item

- `type TraceItem struct{…}`

  List of steps acting on request/response

  - `Action string`

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

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

    Whether tracing step affected tracing request/response

  - `Name string`

    If step type is ruleset, then name of this ruleset

  - `StepName string`

    Tracing step identifying name

  - `Trace Trace`

  - `Type string`

    Tracing step type