List Endpoints
List the endpoints you own. Paginated, with rich filtering — search by subdomain (q), narrow to a specific domain (domain_uuid), an application (application_uuid) or status, or scope to only ephemeral (auto-created) endpoints. You see the endpoints of your active account.
Ephemeral endpoints — created automatically by ngris.connect() and the agent's HTTP/TCP commands — are listed alongside your permanent endpoints in the default response. Set ?ephemeral_only=1 to return only ephemerals.
Query parameters
page int
1-indexed page number. Default
1. Combined with page_size for offset pagination.page_size int
Items per page. Default
15, max 200. Higher values are clamped server-side.q string
Substring match on subdomain. SQL LIKE wildcards (
%, _) and backslashes are escaped server-side, so user input is safe.domain_uuid string (uuid)
Filter to endpoints anchored on the given domain. Use /domains to look up the domain's
uuid.application_uuid string (uuid)
Only the endpoints serving this application. An app can be served by several endpoints, one of them its primary (GET /v1/applications/{uuid} names it). Each matching item carries the app's
application_uuid.status string
Exact match on the stored status:
active | inactive | pending_dns | dns_failed.serving_mode string
agent = tunnel endpoints only; agentless = application endpoints only (both agentless and managed). Any other value is ignored.include_ephemeral "1" | "0"
No-op — ephemeral endpoints are now included by default. Retained for backward compatibility.
ephemeral_only "1" | "0"
Set to
1 to return only ephemerals. Useful for the "running tunnels" view.Deprecated: domain_id (integer) is still accepted until the sunset. Send domain_uuid; sending both for different objects is a 400 id_uuid_mismatch.
Response (200 OK)
items array
Endpoints on this page, newest first. Always present; an empty page is
[]. Each item has the fields of GET /v1/endpoints/{uuid} (except the dedicated-IP binding) plus the list-only fields below.total int
Total matching endpoints across all pages.
page int
The page that was returned.
page_size int
The effective page size (after clamping).
List-only item fields
status string
The live state, not the stored one:
active while it is serving (an agent endpoint with a connected agent, or an application endpoint whose application has a live deploy), inactive otherwise. pending_dns and dns_failed are reported as stored.application_type string?
The served application's type (
static, managed, fullstack, wordpress). Omitted for agent endpoints.requests_24h int
Requests to this endpoint in the last 24 hours (from the traffic logs).
0 when there were none.traffic_24h_csv string?
The same window as 24 comma-separated hourly request counts, oldest hour first; the last value is the current, still-running hour. Omitted when the endpoint had no traffic in the window.
has_auth boolean
true when visitors must sign in (the endpoint's auth settings have a mode with at least one sign-in method on).has_jwt_rule, has_webhook_rule, has_ip_rule, has_ratelimit_rule, has_other_rules boolean
Whether the endpoint's traffic policies have at least one enabled rule of type
jwt-validation, verify-webhook, restrict-ips, rate-limit, or any other type.has_custom_certificate boolean
true when a custom certificate is assigned to the endpoint.certificate_uuid, certificate_name string?
The assigned custom certificate. Omitted when there is none.
certificate_not_after datetime?
When the assigned custom certificate expires. Omitted when unset (no custom certificate).
tunnel_name string?
The name of the tunnel bound to the endpoint. Omitted when there is none.
tunnel_connected_at datetime?
When the earliest currently connected agent connected. Omitted when unset (no agent connected).
health_status string?
The latest health-check probe:
healthy (an idle function that is asleep counts as healthy) or failing. Omitted when the endpoint isn't monitored, has no probe yet, or your plan doesn't include endpoint health.Deprecated: until the sunset this response also carries the legacy integer id and *_id fields. Don't use them; read uuid and the *_uuid fields.
Errors
400 Bad Request
Pagination offset too large (
page * page_size exceeds the resource-protection cap) — reduce one or both — or a malformed domain_uuid or application_uuid.404 Not Found
domain_uuid names no domain you can use, or application_uuid no application in your active account (application not found).401 Unauthorized
Missing auth.
Request
curl "https://api.ngris.com/v1/endpoints?page=1&page_size=15&status=active" \
-H "X-API-KEY: <your_api_key>"
Request — one application's endpoints
curl "https://api.ngris.com/v1/endpoints?application_uuid=019be838-d261-7d9b-9499-71995a3a91c6" \
-H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris
client = Ngris(api_key="<your_api_key>")
# Single page:
page = client.endpoints.list(page=1, page_size=15)
for ep in page.items:
print(ep.uuid, ep.public_url)
# Or auto-paginate everything:
for ep in client.endpoints.list_all():
print(ep.uuid)
Response — 200 OK
{
"items": [
{
"uuid": "019bb1e4-e785-77d2-9966-c3cff31d0a0e",
"user_uuid": "019a52c2-ca1e-78ba-ab5c-50362cc29134",
"domain_uuid": "019bd08f-98db-71b2-8e54-f518d319f111",
"subdomain": "myapp",
"hostname": "myapp.ngris.io",
"public_url": "myapp.ngris.io",
"serving_mode": "agent",
"protocol": "unified",
"is_custom": false,
"status": "active",
"mtls_mode": "disabled",
"capture_enabled": true,
"ephemeral": false,
"dns_attempts": 0,
"tunnel_name": "myapp",
"tunnel_connected_at": "2026-04-30T08:15:02Z",
"has_auth": false,
"has_jwt_rule": false,
"has_webhook_rule": false,
"has_ip_rule": true,
"has_ratelimit_rule": false,
"has_other_rules": false,
"has_custom_certificate": false,
"health_status": "healthy",
"requests_24h": 1204,
"traffic_24h_csv": "40,38,35,31,29,30,42,55,61,70,68,64,59,57,60,66,72,69,58,51,47,44,40,18",
"created_at": "2026-04-29T12:34:56Z",
"updated_at": "2026-04-29T12:34:56Z"
}
],
"total": 4,
"page": 1,
"page_size": 15
}
Was this helpful?