Redirect Chain Tracer

Trace the redirect steps for one public HTTP(S) URL. Returns one dataset item containing the sequence of HTTP statuses, Location headers, and time-to-response-headers. Redirects are only followed on the exact original hostname, up to the configured hop limit.

Who it's for

Web developers, site administrators, and QA engineers investigating unexpected redirects, loops, HTTPS upgrades, and redirect limits without visiting pages in a browser.

Input

{
  "url": "https://example.com/",
  "max_hops": 5
}

• url (required): exactly one public HTTP(S) URL (maximum 2048 characters).
• max_hops (optional, default 5): how many redirects the Actor can follow, from 1 to 10. The first response is always inspected, even when the limit is reached.
• No credentials, login, cookies, or nonstandard ports.

Output (default dataset)

One item per run. The following is an illustrative response for a hypothetical same-host redirect; real servers may return a different chain.

{
  "start_url": "http://example.com/old",
  "hops": [
    {
      "url": "http://example.com/old",
      "status_code": 301,
      "location": "/new",
      "response_ms": 82
    },
    {
      "url": "http://example.com/new",
      "status_code": 200,
      "location": null,
      "response_ms": 77
    }
  ],
  "final_url": "http://example.com/new",
  "next_url": null,
  "stop_reason": "complete",
  "error": null
}

next_url clarification: This field is null when the trace finishes at a non-redirect response. When a redirect is blocked or exceeds a limit, it holds the absolute proposed destination that was not fetched. final_url is the last URL for which an HTTP response was received; it is null if the first request fails.

stop_reason is one of complete, external_redirect, insecure_redirect, redirect_loop, redirect_limit, invalid_redirect, missing_location, request_error, or invalid_input. Transport failures populate error with plain language, never a traceback. HTTP 4xx/5xx statuses count as completed HTTP responses rather than exceptions.

Limits and safety

• Follows up to 10 redirects, and only if each destination keeps the original hostname (same hostname, case-insensitive; www.example.com and example.com are different). A cross-host Location is reported, not requested.
• HTTPS-to-HTTP downgrades are reported, not followed. Same-host HTTP-to-HTTPS upgrades are allowed.
• A redirect to a forbidden scheme, a URL containing credentials, or a nonstandard port is not requested.
• Only response headers are read using GET; response bodies are never downloaded. Each request has a 10-second socket timeout; DNS resolver delays are environment-dependent.
• Public IPs only. DNS is checked before connecting, and the checked addresses are used for the connection. No login, browser, JavaScript, retries, or Apify SDK.
• The Location header is supplied by the remote server and should be treated as untrusted data by downstream consumers.

Storage: Apify and local execution

This Actor uses Python's standard library only. On Apify, the platform-provided APIFY_TOKEN is used solely for reading the run's INPUT record and saving its dataset item using the Apify REST API. The token is never sent to websites or provided as a user input. Cloud storage authorization is required to publish dataset items without an Apify SDK.

For local execution, create storage/key_value_stores/default/INPUT.json using the example above, then run:

python src/main.py

The default dataset item is saved under storage/datasets/default/ as a numbered JSON file. APIFY_LOCAL_STORAGE_DIR overrides the local storage root. Local output files do not automatically appear in Apify Console.

Store classification and pricing suggestion

• Apify Store category: DEVELOPER_TOOLS.
• Suggested pricing: Pay-per-event / USD $0.003 per trace result. Exactly one dataset item is produced per run, so one result corresponds to one run. Suggested only: enable and price the default dataset item billing event in Apify Console. store_metadata.json records the category and recommendation.

Deployment

Each folder is an independent Actor with its own Dockerfile, .actor/actor.json, input_schema.json, and source. It needs no third-party Python dependencies. Verify the cloud run and billing setup in Apify Console before publication.