Skip to main content
Traffic Policy enables you to manage traffic to your ngrok endpoints by dynamically implementing logic based on the request before it reaches your upstream services. This guide will teach you how to configure a Cloud Endpoint with a custom Traffic Policy.
This guide walks you through using the ngrok dashboard, which is recommended for most cases. You can also use the ngrok API.

​
What you’ll need

​
Using the dashboard

  1. In the ngrok dashboard, select the Endpoints & Traffic Policy Tab.
  2. If you already have a Cloud Endpoint to use, select it and move on to the next step. Otherwise, follow these steps to create one.
    • At the top-right of the page, select New Endpoint. In the modal that appears, select Cloud Endpoint.
    • In the next step, select the Public binding. In the URL field add the reserved domain you created earlier.
    • Select Create Endpoint, and you should be taken to that endpoint’s page.
  3. After selecting or creating an endpoint, you’ll be taken to the endpoint’s page, where you can add a Traffic Policy. Add the following yaml to create a basic policy, then select Save.
Example policy
on_http_request:
  - actions:
      - type: custom-response
        config:
          status_code: 200
          body: "Hello, World!"
  1. After applying the policy, visit your reserved domain. You should see the “Hello, World!” message displayed in your browser.

​
Using the API

The best way to configure a Traffic Policy on a Cloud Endpoint is to use the dashboard.
To apply a Traffic Policy to a Cloud Endpoint using the ngrok API, you’ll need:
These instructions use the ngrok agent CLI to interact with the API. You can also use the HTTP API.

​
1. Add your API key to the Agent

Create an API key on your ngrok dashboard and then run the following in your terminal: 
ngrok config add-api-key <your-api-key>

​
2. Create your Traffic Policy file

Create a file named policy.yml with the following contents: 
on_http_request:
  - actions:
      - type: custom-response
        config:
          status_code: 200
          body: "Hello, World!"
This will be the Traffic Policy used on your Cloud Endpoint to respond to each HTTP request with a simple “Hello, World!” message.

​
3. Create your Cloud Endpoint via the API

Create your Cloud Endpoint via the API by running the following in your terminal (make sure to replace <your-reserve-domain> with your reserved domain): 
ngrok api endpoints create \
  --url https://<your-reserve-domain> \
  --traffic-policy "$(<policy.yml)"

​
4. Test it out

Once you have created your Cloud Endpoint you can now open the URL in your web browser. You should see the “Hello, World!” message displayed in your browser.

​
What’s next?

To learn more about ngrok’s Traffic Policy and its capabilities, check out the following resources: