> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ngrok Agent API

> The ngrok agent exposes an HTTP API for collecting metrics and managing endpoints.

## Overview

The ngrok agent exposes an HTTP API that enables you to:

* Collect status and metrics information
* Collect and replay captured requests
* Start and stop endpoints dynamically

<Tip>
  If you need to programmatically control the ngrok agent, consider using one of the [Agent SDKs](/agent-sdks/) instead of the API.
</Tip>

## Base URL and authentication

|                |                             |
| -------------- | --------------------------- |
| Base URL       | `http://127.0.0.1:4040/api` |
| Authentication | **None**                    |

The ngrok agent API is exposed as part of ngrok's local web inspection interface.
Because it's served on a local interface, the API has no authentication.
The Base URL will change if you override `web_addr` in your configuration file.

### Access the root API resource of a running ngrok Agent

```sh theme={null}
curl http://localhost:4040/api/
```

## Supported content types

Request parameters must be encoded to the API using `application/json`.
Ensure that your client sets the request's `Content-Type` header appropriately.
All responses returned by the API are `application/json`.

## Versioning and API stability

The ngrok agent API guarantees that breaking changes to the API will never be made unless the caller explicitly opts in to a newer version.
The mechanism by which a caller opts into a new version of the API will be determined in the future when it becomes necessary.
Examples of non-breaking changes to the API that will not be opt-in include:

* The addition of new resources
* The addition of new methods to existing resources
* The addition of new fields on existing resource representations
* Bug fixes that change the API to match documented behavior

## List tunnels

<Warning>
  This API is deprecated. Use the [list endpoints API](#list-endpoints) instead.
</Warning>

Returns a list of running tunnels with status and metrics information.

### Request

`GET/api/tunnels`

### Parameters

|           |                                                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `tunnels` | List of all running tunnels. See the [Tunnel detail](#tunnel-detail) resource for docs on the parameters of each tunnel object. |

### Example response

```
{
    "tunnels": [
        {
            "name": "command_line",
            "uri": "/api/tunnels/command_line",
            "public_url": "https://d95211d2.ngrok.app",
            "proto": "https",
            "config": {
                "addr": "localhost:80",
                "inspect": true
            },
            "metrics": {
                "conns": {
                    "count": 0,
                    "gauge": 0,
                    "rate1": 0,
                    "rate5": 0,
                    "rate15": 0,
                    "p50": 0,
                    "p90": 0,
                    "p95": 0,
                    "p99": 0
                },
                "http": {
                    "count": 0,
                    "rate1": 0,
                    "rate5": 0,
                    "rate15": 0,
                    "p50": 0,
                    "p90": 0,
                    "p95": 0,
                    "p99": 0
                }
            }
        }
    ],
    "uri": "/api/tunnels"
}
```

## Start tunnel

Dynamically starts a new tunnel on the ngrok agent.
The request body parameters are the same as those you would use to define the tunnel in the configuration file.

### Request

`POST/api/tunnels`

### Parameters

Parameter names and behaviors are identical to those those defined in the configuration file.
Use the [tunnel definitions](/agent/config/v2/#tunnel-configurations) section as a reference for configuration parameters and their behaviors.

### Example request body

```
{
    "addr": "22",
    "proto": "tcp",
    "name": "ssh"
}
```

### Response

`201 Created` status code with a response body describing the started tunnel.

See the [Tunnel detail](#tunnel-detail) resource for docs on the parameters of the response object.

### Example response

```
{
    "name": "",
    "uri": "/api/tunnels/",
    "public_url": "tcp://0.tcp.ngrok.io:53476",
    "proto": "tcp",
    "config": {
        "addr": "localhost:22",
        "inspect": false
    },
    "metrics": {
        "conns": {
            "count": 0,
            "gauge": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        },
        "http": {
            "count": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        }
    }
}
```

## Tunnel detail

Get status and metrics about the named running tunnel.

### Request

`GET/api/tunnels/:name`

### Example response

```
{
    "name": "command_line",
    "uri": "/api/tunnels/command_line",
    "public_url": "https://ac294125.ngrok.app",
    "proto": "https",
    "config": {
        "addr": "localhost:80",
        "inspect": true
    },
    "metrics": {
        "conns": {
            "count": 0,
            "gauge": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        },
        "http": {
            "count": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        }
    }
}
```

## Stop tunnel

Stop a running tunnel.

### Request

`DELETE/api/tunnels/:name`

### Response

`204 No Content` status code with an empty body.

## List endpoints

Returns a list of running endpoints with status and metrics information.

### Request

`GET/api/endpoints`

### Response

`200 OK` status code with a JSON response containing an array of endpoint objects.

### Example response

```
{
  "endpoints": [
    {
      "name": "command_line",
      "uri": "/api/endpoints/command_line",
      "url": "https://871e40f2d4c2.ngrok.paid.lan",
      "upstream": {
        "url": "http://localhost:8000",
        "protocol": "https"
      },
      "inspect": true,
      "traffic_policy": "on_http_request:\n - actions:\n - type: custom-response\n config:\n status_code: 200\n body: Hello, World!\n",
      "pooling_enabled": true
    }
  ]
}
```

## Endpoint detail

Get status and metrics about the named running endpoint.

### Request

`GET/api/endpoints/:name`

### Response

`200 OK` status code with endpoint JSON for success.

`404 Not Found` if the provided name doesn't correspond to an endpoint.

### Example response

```
{
  "name": "command_line",
  "uri": "/api/endpoints/command_line",
  "url": "https://871e40f2d4c2.ngrok.paid.lan",
  "upstream": {
    "url": "http://localhost:8000",
    "protocol": "https"
  },
  "inspect": true,
  "traffic_policy": "on_http_request:\n - actions:\n - type: custom-response\n config:\n status_code: 200\n body: Hello, World!\n",
  "pooling_enabled": true,
  "metrics": {
    "conns": {
      "count": 0,
      "gauge": 0,
      "rate1": 0,
      "rate5": 0,
      "rate15": 0,
      "p50": 0,
      "p90": 0,
      "p95": 0,
      "p99": 0
    },
    "http": {
      "count": 0,
      "rate1": 0,
      "rate5": 0,
      "rate15": 0,
      "p50": 0,
      "p90": 0,
      "p95": 0,
      "p99": 0
    }
  }
}
```

## Create endpoint

Dynamically creates a new endpoint on the ngrok agent.

### Request

`POST/api/endpoints`

### Response

`201 Created` on success.

`400 Bad Request` for malformed payloads.

### Example request body

```
{
  "name": "my_awesome_tunnel",
  "url": "https://iamawesome.ngrok.paid.lan",
  "upstream": {
    "url": "8001"
  },
  "pooling_enabled": true
}
```

## Update endpoint

Updates an existing endpoint or creates a new one if it doesn't exist.

### Request

`PUT/api/endpoints/:name`

### Response

`200 OK` if an existing endpoint is updated.

`201 Created` if an endpoint is created.

`400 Bad Request` for malformed payloads.

### Example request body

```
{
  "name": "command_line",
  "uri": "/api/endpoints/command_line",
  "url": "https://871e40f2d4c2.ngrok.paid.lan",
  "upstream": {
    "url": "http://localhost:8000",
    "protocol": "https"
  },
  "inspect": true,
  "traffic_policy": "on_http_request:\n - actions:\n - type: custom-response\n config:\n status_code: 200\n body: Hello, World!\n",
  "pooling_enabled": true
}
```

## Delete endpoint

Stop a running endpoint.

### Request

`DELETE/api/endpoints/:name`

### Response

`204 No Content` for successful delete.

`404 Not Found` if trying to delete a nonexistent endpoint.

## List captured requests

Returns a list of all HTTP requests captured for inspection.
This will only return requests that are still in memory—ngrok evicts captured requests when their memory usage exceeds `inspect_db_size`.

### Request

`GET/api/requests/http`

### Query parameters

|               |                                                 |
| ------------- | ----------------------------------------------- |
| `limit`       | Maximum number of requests to return.           |
| `tunnel_name` | Filter requests only for the given tunnel name. |

### Example request

```sh theme={null}
curl http://localhost:4040/api/requests/http?limit=50
```

### Response

|            |                                                                                                                                  |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `requests` | List of captured requests. See the [Captured Request Detail](#captured-request-detail) resource for docs on the request objects. |

### Example response

```
{
    "uri": "/api/requests/http",
    "requests": [
        {
            "uri": "/api/requests/http/548fb5c700000002",
            "id": "548fb5c700000002",
            "tunnel_name": "command_line (http)",
            "remote_addr": "192.168.100.25",
            "start": "2014-12-15T20:32:07-08:00",
            "duration": 3893202,
            "request": {
                "method": "GET",
                "proto": "HTTP/1.1",
                "headers": {
                    "Accept": [
                        "*/*"
                    ],
                    "Accept-Encoding": [
                        "gzip, deflate, sdch"
                    ],
                    "Accept-Language": [
                        "en-US,en;q=0.8"
                    ],
                    "Connection": [
                        "keep-alive"
                    ],
                    "User-Agent": [
                        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36"
                    ],
                    "X-Original-Host": [
                        "c159663f.ngrok.app"
                    ]
                },
                "uri": "/favicon.ico",
                "raw": "<BASE64 ENCODED BYTES>"
            },
            "response": {
                "status": "502 Bad Gateway",
                "status_code": 502,
                "proto": "HTTP/1.1",
                "headers": {
                    "Content-Length": [
                        "1716"
                    ]
                },
                "raw": "<BASE64 ENCODED BYTES>"
            }
        }
    ]
}
```

## Replay captured request

Replays a request against the local endpoint of a tunnel.

### Request

`POST/api/requests/http`

### Parameters

|               |                                                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | ID of request to replay.                                                                                                          |
| `tunnel_name` | Name of the tunnel to play the request against. If unspecified, the request is played against the same tunnel it was recorded on. |

### Example request

```sh theme={null}
curl -H "Content-Type: application/json" -d '{"id": "548fb5c700000002"}' http://localhost:4040/api/requests/http
```

### Response

`204 No Content` status code with an empty body.

## Delete captured requests

Deletes all captured requests.

### Request

`DELETE/api/requests/http`

### Response

`204 No Content` status code with no response body.

## Captured request detail

Returns metadata and raw bytes of a captured request.
The raw data is base64-encoded in the JSON response.
The `response` value may be `null` if the local server hasn't responded to a request yet.

### Request

`GET/api/requests/http/:request_id`

### Example response

```
{
    "uri": "/api/requests/http/548fb5c700000002",
    "id": "548fb5c700000002",
    "tunnel_name": "command_line (http)",
    "remote_addr": "192.168.100.25",
    "start": "2014-12-15T20:32:07-08:00",
    "duration": 3893202,
    "request": {
        "method": "GET",
        "proto": "HTTP/1.1",
        "headers": {
            "Accept": [
                "*/*"
            ],
            "Accept-Encoding": [
                "gzip, deflate, sdch"
            ],
            "Accept-Language": [
                "en-US,en;q=0.8"
            ],
            "Connection": [
                "keep-alive"
            ],
            "User-Agent": [
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36"
            ],
            "X-Original-Host": [
                "c159663f.ngrok.app"
            ]
        },
        "uri": "/favicon.ico",
        "raw": "<BASE64 ENCODED BYTES>"
    },
    "response": {
        "status": "502 Bad Gateway",
        "status_code": 502,
        "proto": "HTTP/1.1",
        "headers": {
            "Content-Length": [
                "1716"
            ]
        },
        "raw": "<BASE64 ENCODED BYTES>"
    }
}
```

## Agent status

Get status and metrics about the running agent.

### Request

`GET /api/status`

### Example request

```sh theme={null}
curl http://localhost:4040/api/status
```

### Response

`200 OK` status code with a JSON response describing the status of the agent.

### Example response

```
{
    "status": "online",
    "agent_version": "3.9.0",
    "session": {
        "legs": [
            {
                "region": "au",
                "latency": "87ms"
            }
        ]
    },
    "uri": "/api/status"
}
```