List segment contacts

The contacts on a segment, newest first.

GET /v1/segments/{id}/contacts

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The segment id.

Query parameters

Cursor-paginated:

Parameter	Type	Description
limit	number	How many to return. Default 20, min 1, max 100.
after	string	Return contacts after this contact id. Cannot be combined with before.
before	string	Return contacts before this contact id. Cannot be combined with after.

The cursor is a contact id — the id of a row in data, not the segment id.

Example

curl

curl "https://api.sendgrail.com/v1/segments/$SEGMENT_ID/contacts?limit=50" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

const res = await fetch(
  `https://api.sendgrail.com/v1/segments/${id}/contacts?limit=50`,
  { headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` } },
);

const { data, has_more } = await res.json();

Response

Each row is a full contact object — the same shape you get from the contacts endpoints, properties map included, so you do not have to fetch each contact again to read its fields.

{
  "object": "list",
  "has_more": true,
  "data": [
    {
      "object": "contact",
      "id": "c1a4f7e2-5b6d-4c39-8a10-9e2f3b5d7c88",
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "subscribed": true,
      "unsubscribed_at": null,
      "bounced_at": null,
      "source": "api",
      "properties": {
        "company_name": "Acme Corp"
      },
      "created_at": "2026-07-14T19:44:32+00:00"
    }
  ]
}

To walk the whole list, pass the last contact id you saw as after until has_more is false. See Pagination.

Adding and removing members

This endpoint is read-only. Membership is managed from the contact:

POST   /v1/contacts/{id}/segments
DELETE /v1/contacts/{id}/segments/{segment}

See Contact segments.

A segment belonging to another team answers 404 — an id that isn't yours is an id that doesn't exist, as far as your key is concerned. A Sending-access key answers 403. See Errors.