---
title: "Traced redirect chains of a project"
method: GET
path: "/projects/{project_id}/redirect-traces"
tags: ["Redirect chains"]
---

# Traced redirect chains of a project

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

Lists the project's redirect traces requested in the window, newest first, with the same fields as get_redirect_chain. Use outcome and affiliate-ID filters to find chains for follow-up review. Engine, device, system, country and location filters apply to the saved check of the ad that asked for the trace. with_affiliate_ids keeps chains where an affiliate ID was observed. A trace is one visit from our servers; any inference is a prompt to review, not proof of who placed an ad or broke a rule. Defaults to the last 30 days in the person's time zone.

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

## Query parameters

- `range` '7d' | '14d' | '30d' | '12m' | 'custom': Window ending today: 7d, 14d, 30d (default) or 12m. Use custom with from and to for fixed dates.
- `from` string: First local day, YYYY-MM-DD (custom range).
- `to` string: Last local day, YYYY-MM-DD, included in full (custom range).
- `time_zone` string: IANA time zone for day boundaries, such as America/New_York. Defaults to the time zone of the person the credential acts for.
- `engine` union: Search engine, or a list of engines combined with OR.
  - 'google' | 'bing'
  - string[]
- `device` union: Device, or a list combined with OR.
  - 'desktop' | 'mobile'
  - string[]
- `os` union: Operating system. unspecified matches checks that did not pin one. Must fit the chosen device.
  - 'windows' | 'macos' | 'android' | 'ios' | 'unspecified'
  - string[]
- `country` union: ISO 3166-1 alpha-2 country code such as US, or a list.
  - string
  - string[]
- `location` union: Saved location key: code:<location code>, name:<label> or country:<ISO code>. get_project_details lists the keys that have data.
  - string
  - string[]
- `outcome` 'landed' | 'http_error' | 'blocked' | 'timeout' | 'too_many_hops' | 'loop' | 'network_error' | 'rate_limited' | 'invalid_destination'
- `with_affiliate_ids` union
  - boolean
  - 'true' | 'false'
- `limit` integer: Items per page, 1 to 200.
- `cursor` string: The next_cursor value from the previous page. Omit it for the first page.

## Response `200`

Traced redirect chains of a project

- object
  - `data` 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.
  - `next_cursor` string, nullable, required
  - `total_rows` integer, required
  - `window` object, required
    - `from` string, required: First local day included, YYYY-MM-DD.
    - `to` string, required: Last local day included, YYYY-MM-DD.
    - `time_zone` string, required
    - `start` string, required: Inclusive start instant, ISO 8601.
    - `end` string, required: Exclusive end instant, ISO 8601.
  - `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)