# Traces

## Request Trace

`request_tracers.traces.create(TraceCreateParams**kwargs)  -> 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.

### Parameters

- `account_id: str`

  Identifier.

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

### Returns

- `class TraceCreateResponse: …`

  Trace result with an origin status code

  - `status_code: Optional[int]`

    HTTP Status code of zone response

  - `trace: Optional[Trace]`

### Example

```python
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)
```

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

- `List[TraceItem]`

### Trace Item

- `class TraceItem: …`

  List of steps acting on request/response

  - `action: Optional[str]`

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

  - `action_parameters: Optional[object]`

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

  - `description: Optional[str]`

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

  - `expression: Optional[str]`

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

  - `kind: Optional[str]`

    If step type is ruleset, then kind of this ruleset

  - `matched: Optional[bool]`

    Whether tracing step affected tracing request/response

  - `name: Optional[str]`

    If step type is ruleset, then name of this ruleset

  - `step_name: Optional[str]`

    Tracing step identifying name

  - `trace: Optional[Trace]`

  - `type: Optional[str]`

    Tracing step type

### Trace Create Response

- `class TraceCreateResponse: …`

  Trace result with an origin status code

  - `status_code: Optional[int]`

    HTTP Status code of zone response

  - `trace: Optional[Trace]`