Groups List Dedicated Ips

List Dedicated IP Groups

GET /v1/dedicated-ips/groups

List the active per-region dedicated-IP groups allocated to your active 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/{uuid}/release.

Response (200 OK)

JSON object with an items array of active groups:

uuid string (uuid)

The group's public id. Send it as group_uuid to attach and use it in /dedicated-ips/groups/{uuid}/release.

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-<group uuid>.<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).

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

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['uuid']} {g['geo_fqdn']} [{regions}] {g['endpoint_count']} endpoint(s)")

Response — 200 OK
{
  "items": [
    {
      "uuid": "019b153d-c31b-7b7a-afe6-b67cc62bf94c",
      "kind": "endpoint",
      "mode": "per_region",
      "status": "active",
      "geo_fqdn": "grp-019b153d-c31b-7b7a-afe6-b67cc62bf94c.geo.ngris.io",
      "endpoint_count": 1,
      "created_at": "2026-05-02T00:00:00Z",
      "members": [
        { "region_slug": "eu-fi", "ip_address": "203.0.113.5" },
        { "region_slug": "us-va", "ip_address": "198.51.100.9" }
      ]
    }
  ]
}

Was this helpful?

PreviousRelease Dedicated IP NextRelease Dedicated IP Group

On this page

List Dedicated IP Groups

Was this helpful?