Skip to content

List segments ​

Every segment on your team, newest first.

http
GET /v1/segments

Requires a Full access API key.

Query parameters ​

Cursor-paginated:

ParameterTypeDescription
limitnumberHow many to return. Default 20, min 1, max 100.
afterstringReturn segments after this id. Cannot be combined with before.
beforestringReturn segments before this id. Cannot be combined with after.

Example ​

bash
curl "https://api.sendgrail.com/v1/segments" \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY"
js
const res = await fetch('https://api.sendgrail.com/v1/segments', {
  headers: { Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}` },
});

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

Response ​

json
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "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"
    },
    {
      "object": "segment",
      "id": "0a7d3c14-9b52-4e88-8f61-2d5a6c9b1e07",
      "name": "Paying customers",
      "description": null,
      "contacts_count": 1042,
      "created_at": "2026-06-02T09:12:04+00:00"
    }
  ]
}

has_more tells you whether another page exists — there is no total, because a keyset paginator never counts the table. To walk every page, pass the last id you saw as after until has_more is false. See Pagination.

Each row carries contacts_count, so you can size every list on your team in one request without fetching a single contact.

Transactional email on your own domain.