List Endpoints
List the endpoints you own. Paginated, with rich filtering — search by subdomain (q), narrow to a specific domain (domain_id) or status, include or exclude ephemeral (auto-created) endpoints. Admin callers can additionally filter by user_id to inspect another user's endpoints; non-admins always see only their own.
Ephemeral endpoints are hidden from the default response — they're created automatically by ngris.connect() and the agent's HTTP/TCP commands and would otherwise drown out the user's permanent endpoints in the dashboard. Set ?include_ephemeral=1 to include them or ?ephemeral_only=1 to see 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
20, max 100. 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_id int64
Filter to endpoints anchored on the given domain. Use /domains to look up IDs.
status string
active | provisioning | error | disabled. Exact match.include_ephemeral "1" | "0"
Set to
1 to include ephemeral endpoints in the result. Default omits them.ephemeral_only "1" | "0"
Set to
1 to return only ephemerals. Useful for the "running tunnels" view.user_id int64
Admin-only. Filter to a specific user's endpoints. Ignored if the caller isn't admin.
Response (200 OK)
items array
Endpoints on this page. Each is the same shape as GET /v1/endpoints/{id}.
total int
Total matching endpoints across all pages.
page int
Current page (echo).
page_size int
Page size (echo).
Errors
400 Bad Request
Pagination offset too large (
page * page_size exceeds the resource-protection cap). Reduce one or both.401 Unauthorized
Missing auth.
Request
curl "https://api.ngris.com/v1/endpoints?page=1&page_size=20&status=active" \
-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=20)
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": [
{
"id": 184,
"uuid": "9f1a3c00-5b7f-4f12-8c46-2c7dab5f1234",
"user_id": 1024,
"subdomain": "myapp",
"hostname": "myapp.ngris.io",
"public_url": "myapp.ngris.io",
"protocol": "unified",
"is_custom": false,
"domain_id": null,
"status": "active",
"ephemeral": false,
"mtls_mode": "disabled",
"created_at": "2026-04-29T12:34:56Z",
"updated_at": "2026-04-29T12:34:56Z"
}
],
"total": 4,
"page": 1,
"page_size": 20
}