# Rules Trace # Traces ## Request Trace `client.requestTracers.traces.create(TraceCreateParamsparams, RequestOptionsoptions?): 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 - `params: TraceCreateParams` - `account_id: string` Path param: Identifier. - `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` 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` Body param: Cookies added to tracing request - `headers?: Record` 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 ### Returns - `TraceCreateResponse` Trace result with an origin status code - `status_code?: number` HTTP Status code of zone response - `trace?: Trace` - `TraceItem` 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 ### Example ```typescript 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); ``` #### 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 - `Trace = Array` - `TraceItem` 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 ### Trace Item - `TraceItem` 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 ### Trace Create Response - `TraceCreateResponse` Trace result with an origin status code - `status_code?: number` HTTP Status code of zone response - `trace?: Trace` - `TraceItem` 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