Skip to main content
The Redirect Traffic Policy Action enables users to send HTTP 3xx responses by transforming the incoming URL using a regular expression and optional CEL interpolation. It can modify any part of the URL such as scheme, host, port, path, or query, and returns a redirect via the Location header. This action is different from the URL Rewrite Action, which changes the request internally while keeping the client’s URL unchanged. Redirects, by contrast, instruct the client to issue a new request to the new URL.

​
Configuration Reference

The Traffic Policy configuration reference for this action.

​
Supported Phases

on_http_request

​
Type

redirect

​
Configuration Fields

​
from
string
Supports CEL
A regular expression pattern used to match a part of the URL.
​
to
string
Required
Supports CEL
A regular expression pattern used to replace the matched part of the URL.
​
status_code
integer
default:302
A 3xx status code used for redirecting.
​
headers
object
Supports CEL
Map of key-value headers to be added to the response. Maximum 10 headers can be specified.

​
Behavior

The Redirect Action modifies the request URL and returns an HTTP redirect (3xx) response. It performs the following transformation in sequence:
  1. Evaluate any CEL interpolation
  2. Apply the regular expression match (from)
  3. Replace the matched text or URL with the to value
  4. Send the redirect response
If the rewritten URL is identical to the original, ngrok skips the redirect.

​
CEL interpolation

CEL expressions in ${...} are evaluated before the redirect rule is applied. Interpolations can reference request or connection data. For example: 
to: https://example.com?city=${conn.geo.city}
If the request originates from San Francisco, the final redirect target is: 
https://example.com?city=San%20Francisco

​
Matching

The from field is a regular expression evaluated against the entire URL (scheme, host, port, path, query, and fragment). Matching is not anchored by default; a substring match anywhere in the URL triggers the redirect.

​
Example

The following example redirects any request that contains /api/v1/ to /api/v2/. The redirect is applied to the entire URL, not just the path. 
from: /api/v1/
to: /api/v2/
Given the above, https://example.com/foobar/api/v1/users would be redirected to https://example.com/foobar/api/v2/users.

​
Anchoring / Path Prefix

Anchoring with ^/api/v1/ will not match paths that include the full scheme. To match only the path, use one of the following methods: 
# Anchor the full URL, capture authority, and rewrite the path segment.
from: ^((?:https?)://[^/]+)/api/v1/(.*)$
to: $1/api/v2/$2

​
Replacement behavior

The to value replaces what was matched by from. The replacement is relative to the from match. When from is omitted, the redirect action replaces the entire URL. Capture groups (such as $1, $2) can be used to insert matched text into the replacement. When from matches a substring, only that segment changes: 
from: /v1/
to: /v2/
Given the above, https://example.com/api/v1/users would be redirected to https://example.com/api/v2/users.

​
Relative vs. absolute replacements

The to value is applied relative to the from match. When from matches part of the URL, only that segment is replaced. When from is omitted, ngrok treats the entire URL as matched and replaces it absolutely. Relative example 
from: /old
to: https://new.example.com/blog
Given the above, https://example.com/old/foo would become https://example.com/https://new.example.com/blog/foo. Absolute example When a partial match exists, the replacement is relative; when no from match is defined, it is absolute: 
to: https://new.example.com/blog
Given the above, any request to https://example.com would be redirected to https://new.example.com/blog. Redirecting to another host To redirect cleanly to a new host, match the entire URL: 
from: ^https?://[^/]+/old/(.*)$
to: https://new.example.com/new/$1
Given the above, https://example.com/old/foo would be redirected to https://new.example.com/new/foo.
If the rewritten URL equals the original, ngrok skips the redirect.

​
Redirect response

After replacement, the redirect action sends an HTTP redirect with the computed Location header. The default status code is 302 Found.
CodeDescriptionBehavior
301Moved PermanentlyClients may cache the redirect.
302Found (default)Temporary redirect; some clients change the request method to GET.
303See OtherForces the next request to use GET.
307Temporary RedirectPreserves the original request method and body.
308Permanent RedirectPreserves the original request method and body.
You can also include up to 10 custom headers in the redirect response. Example 
from: ^(https?://[^/]+)/products(.*)$
to: $1/store/products$2
status_code: 301
headers:
  x-redirected: true
Result 
HTTP/1.1 301 Moved Permanently
location: https://example.ngrok.app/store/products
x-redirected: true
Once the redirect is sent, the action ends the current phase and no further actions are executed.

​
Examples

​
Redirect using Paths

The following Traffic Policy configuration demonstrates how to use the redirect action to redirect incoming requests from /products to /store/products.

​
Example Traffic Policy Document

on_http_request:
  - actions:
      - type: redirect
        config:
          from: ^(https?://[^/]+)/products(.*)$
          to: $1/store/products$2
This configuration will redirect any request from /products to /store/products with the default 302 Found status code.

​
Example request

$ curl -i https://example.ngrok.app/products

HTTP/1.1 302 Found
location: https://example.ngrok.app/store/products
In this example, a request to /products will be redirected to /store/products with a 302 Found status code, and the Location header will indicate the new URL.

​
Redirect using Regular Expressions

The following Traffic Policy configuration demonstrates how to use the redirect action to redirects requests from an old API endpoint to a new one.

​
Example Traffic Policy Document

on_http_request:
  - expressions:
      - req.url.path.startsWith('/api/')
    actions:
      - type: redirect
        config:
          from: /api/v1/users?id=([0-9]+)
          to: /api/v2/users/$1/
          status_code: 301
          headers:
            x-redirected: 'true'
In this configuration we match requests from /api/v1/users?id=([0-9]+) and redirect them to /api/v2/users/$1/ with a 301 status code. Additionally, a custom header x-redirected: true is added to the response.

​
Example Request

$ curl -i https://example.ngrok.app/api/v1/users?id=123

HTTP/1.1 301 Moved Permanently
location: https://example.ngrok.app/api/v2/users/123/
x-redirected: true
The request will be redirected to the new URL /api/v2/users/123/, with a 301 Moved Permanently status and a custom header.

​
Redirect with CEL Interpolation

The following Traffic Policy configuration demonstrates how to use the redirect action to redirect users while using CEL Interpolation.

​
Example Traffic Policy Document

on_http_request:
  - expressions:
      - req.url.path in ['/api/v2/geo', '/api/v2/geo/']
    actions:
      - type: redirect
        config:
          to: /api/v2/geo?city=${conn.geo.city}
This configuration will redirect any request from /api/v2/geo or /api/v2/geo/ to /api/v2/geo?city=${conn.geo.city} using CEL Interpolation to insert the city from the connection’s geolocation data.

​
Example Request

$ curl -i https://example.ngrok.app/api/v2/geo

HTTP/1.1 302 Found
location: https://example.ngrok.app/api/v2/geo?city=San%20Francisco
In this example, a request to https://example.ngrok.app/api/v2/geo will be redirected to https://example.ngrok.app/api/v2/geo?city=San Francisco, with the 302 Found status code and the Location header indicating the new URL that includes the city from the connection’s geolocation data.

​
Action Result Variables

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.
​
actions.ngrok.redirect.matches
array of strings
A list of elements that were matched during redirection. These represent the request components (for example, path or query parameters) that triggered the action and resulted in the redirect.
​
actions.ngrok.redirect.url
string
The URL to which the traffic was redirected. This is the destination URL returned as part of the redirect response after the action was executed.
​
actions.ngrok.redirect.error.code
string
A machine-readable code describing an error that occurred during the action’s execution.
​
actions.ngrok.redirect.error.message
string
A human-readable message providing details about an error that occurred during the action’s execution.