List Dedicated IP Groups

GET /v1/dedicated-ips/groups

List the active per-region dedicated-IP groups allocated to the calling user's account. A group bundles one dedicated IP per region and is geo-routed: visitors resolve to the nearest regional IP via a single GeoDNS hostname. Endpoints attach to the group (not to an individual IP) and are published as a CNAME to the group's geo FQDN.

This complements GET /v1/dedicated-ips, which lists individual single-mode assignments. An endpoint may use a single IP or a group, but never both at once.

Account scope: groups are an account-level resource — they are visible to the members of your active account per your role's permissions. A legacy token without an active account has no groups and receives an empty list.

Provision a group via POST /v1/dedicated-ips/requests with selection_mode: "per_region"; the operator auto-assigns one IP per requested region on approval. Attach it to an endpoint with POST /v1/endpoints/{uuid}/dedicated-ip-group and release the whole group with POST /v1/dedicated-ips/groups/{id}/release.

Response (200 OK)

JSON object with an items array of active groups:

id int64
Numeric group ID. Used in the release and attach endpoints.
kind string
Group kind. Currently always endpoint (a group fronting one or more endpoints).
mode string
Routing mode. Always per_region for groups (geolocation GeoDNS).
status string
Group status. This list only returns active groups.
geo_fqdn string
The GeoDNS hostname (grp-<id>.<geo-zone>) that attached endpoints CNAME at. Empty if GeoDNS is not configured on the server.
endpoint_count int
Number of endpoints currently attached to this group.
created_at datetime
When the group was created. RFC 3339 UTC.
members array
The group's member IPs, one per region. Each member has region_slug (string) and ip_address (string).

Errors

401 Unauthorized
Missing auth.
403 Forbidden
Your role lacks the ips:read permission in the active account.
Request
curl "https://api.ngris.com/v1/dedicated-ips/groups" \ -H "X-API-KEY: <your_api_key>"
Python
from ngris import Ngris client = Ngris(api_key="<your_api_key>") for g in client._get_raw("/dedicated-ips/groups")["items"]: regions = ", ".join(m["region_slug"] for m in g["members"]) print(f"group #{g['id']} {g['geo_fqdn']} [{regions}] {g['endpoint_count']} endpoint(s)")
Response — 200 OK
{ "items": [ { "id": 4, "kind": "endpoint", "mode": "per_region", "status": "active", "geo_fqdn": "grp-4.geo.ngris.io", "endpoint_count": 1, "created_at": "2026-05-02T00:00:00Z", "members": [ { "region_slug": "eu-north-1", "ip_address": "203.0.113.5" }, { "region_slug": "us-east-1", "ip_address": "198.51.100.9" } ] } ] }
Homepage Docs Dashboard Docs API Docs nvelox Dashboard
Iris