Retrieve a segment

Fetch one segment by its id.

GET /v1/segments/{id}

Requires a Full access API key.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The segment id.

Example

curl

curl "https://api.sendgrail.com/v1/segments/$SEGMENT_ID" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"

Node.js

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

const segment = await res.json();

Response

{
  "object": "segment",
  "id": "3f1c9a52-6d0e-4a1b-9a2f-7c4e1b0d8e33",
  "name": "Trial users",
  "description": "Signed up in the last 14 days and has not paid yet",
  "contacts_count": 128,
  "created_at": "2026-07-14T19:44:32+00:00"
}

contacts_count is how many contacts are currently on the list. The contacts themselves are not inlined — a segment can hold hundreds of thousands of them, so they are a page of their own: List segment contacts.

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

{
  "message": "No segment with the id 3f1c9a52-6d0e-4a1b-9a2f-7c4e1b0d8e33.",
  "code": "not_found",
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

A Sending-access key is a different failure: it is a real key, it just isn't allowed here, so it answers 403. See Errors.