---
title: "Queue a server-side trace of a saved ad destination"
method: POST
path: "/projects/{project_id}/redirect-traces"
tags: ["Redirect chains"]
---

# Queue a server-side trace of a saved ad destination

`POST /projects/{project_id}/redirect-traces`

## Request

- Base URL: `https://adslighthouse.com/api/v1`
- URL: `https://adslighthouse.com/api/v1/projects/{project_id}/redirect-traces`
- Auth: HTTP bearer

Queues a trace of one destination URL that a saved ad of the project pointed to (use the url from list_keyword_ads or the observations list; other URLs are refused). Use it to inspect the recorded destination path and any affiliate IDs in that path. Our servers follow it hop by hop with a clear user agent and no cookies, recording each status code, the redirect mechanism, the final URL and any affiliate IDs present. It runs from our servers, not the searcher's country or device, so a location- or device-dependent redirect may differ. Script redirects are read from page source without running it. Each new trace uses one of the account's daily traces (resets 00:00 UTC); repeating the call for the same URL within the same UTC hour returns the same trace and uses nothing. The trace usually finishes within a minute: read it with get_redirect_chain. Requires the write scope and explicit user authorization.

## Path parameters

- `project_id` string, required: The project: its id, its brand domain (for example nike.example) or its exact project or brand name. Unknown or ambiguous references return not_found; call list_projects then.

## Request body

- object
  - `url` string, required: The saved ad destination URL, exactly.

## Response `202`

Queue a server-side trace of a saved ad destination

- object
  - `created` boolean, required: False when a trace of this URL was already requested this hour.
  - `chain` object, required
    - `id` string, required
    - `destination_url` string, required: The saved ad destination that was traced.
    - `status` 'queued' | 'complete' | 'failed', required
    - `outcome` 'landed' | 'http_error' | 'blocked' | 'timeout' | 'too_many_hops' | 'loop' | 'network_error' | 'rate_limited' | 'invalid_destination', nullable, required
    - `final_url` string, nullable, required: The last URL requested.
    - `final_status` integer, nullable, required
    - `hops` object[], required
      - `url` string, required
      - `status` integer, nullable, required: HTTP status; null when no response arrived.
      - `content_type` string, nullable, required
      - `duration_ms` number, required
      - `redirect` object, nullable, required: How this hop sent the visit on, and where. Null on the last hop.
        - `mechanism` 'http_redirect' | 'refresh_header' | 'meta_refresh' | 'script', required: script means a literal location assignment read from page source without running it.
        - `target` string, required
      - `failure` string, nullable, required: Why the hop was not requested or did not answer: unsafe_scheme, unsafe_port, credentials_in_url, private_address, unresolvable, invalid_url, timeout, network_error or rate_limited.
    - `affiliate_signals` object[], required: Observed values, one per hop and parameter.
      - `hop` integer, required: Zero-based index of the hop whose URL carried the value.
      - `source` 'project_parameter' | 'network_pattern', required: project_parameter: your configured affiliate parameter. network_pattern: a documented link format of a public affiliate network (the attribution to that network is inferred from the host and parameter).
      - `network` string, nullable, required
      - `parameter` string, required
      - `meaning` string, nullable, required
      - `value` string, required: Exactly as observed, case preserved.
    - `observed_flags` string[], required: Facts about the visit that limit it: script_redirect_followed, script_redirect_unrecognized, non_html, body_truncated, access_denied, varies_by_device.
    - `inferences` string[], required: Interpretations to review, not findings: destination_differs, cloaking_suspected, geo_or_device_dependent.
    - `trigger` 'automatic' | 'manual' | 'api', required
    - `requested_at` string, required
    - `traced_at` string, nullable, required
    - `total_ms` integer, nullable, required
    - `web_archive` object, nullable, required: The trace's web archive (WARC 1.1, gzip per record): every answered hop's request and response with all response headers and the body up to 256 KiB. Null when none was written (older traces, no answered hop). Get a download link with get_redirect_trace_archive_link.
      - `bytes` integer, required: Size of the .warc.gz file.
      - `includes_page_capture` boolean, required: The file also holds the saved page capture's HTML as a separate resource record, which is not part of the HTTP exchange.
    - `vantage` 'server', required: Traced from Ads Lighthouse servers, not from the searcher's country or device; a location- or device-dependent redirect may differ.
  - `usage` object, required
    - `used` integer, required
    - `limit` integer, required
    - `day` string, required
  - `request_id` string

## Other responses

- `400`: Invalid parameters, cursor or body.
- `401`: Missing, invalid, expired or revoked credential.
- `403`: The credential lacks the write scope, the plan does not include the API, or the allowance is used up.
- `404`: Unknown project, keyword or run in this account.
- `409`: The idempotency key was already used for a different request.
- `429`: Rate limit reached. Retry after the Retry-After seconds.
- `503`: The requested service or file is temporarily unavailable.

---

[API](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api.md) · [All operations](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adslighthouse/apis/ads-lighthouse-api/revisions/e1a4a40b11a9?raw)