# List contacts in a segment

`GET /v1/segments/{id}/contacts`

Requires an API key with the `contacts:read` scope. [About keys and scopes](/docs/api/authentication)

Evaluates a saved segment and returns the matching contacts. Because segments are evaluated on read, results can change between pages if contacts are changing underneath. Results are cursor-paginated: pass `meta.pagination.nextCursor` back as `cursor` until it comes back `null`. The cursor is opaque — do not construct or parse one. `meta.count` counts the matching contacts up to 10000: beyond that it reports the cap and `meta.countExact` is `false`; both are counted on the first page only (null with a `cursor`).

## Path parameters

- `id` (string, required, uuid)

## Query parameters

- `limit` (integer, optional, min > 0, max 100, default `20`)
- `cursor` (string, optional, 1–2048 characters)

## Returns

Returns `200 OK` with a list of `Contact` objects in `data`, and the next page's cursor in `meta` (see [pagination](/docs/api/pagination)). Otherwise returns an error; [Errors](/docs/api/errors) lists every code and which to retry.

- `id` (string, required, uuid)
- `externalId` (string | null, required) — Your own id for the contact, if set.
- `email` (string | null, required, email)
- `firstName` (string | null, required)
- `lastName` (string | null, required)
- `phone` (string | null, required) — Phone number in E.164 format.
- `timezone` (string | null, required) — IANA timezone, e.g. `Europe/London`.
- `country` (string | null, required) — ISO 3166-1 alpha-2 code: as written, or inferred from the phone, else the timezone.
- `dates` (object, required) — Named calendar dates, e.g. `birthday`, as `YYYY-MM-DD` or `--MM-DD`.
- `attributes` (object, required) — Custom attributes, keyed by attribute name.
- `emailConsent` (boolean, required) — Whether the contact has consented to email.
- `pushConsent` (boolean, required) — Whether the contact has consented to push.
- `createdAt` (string, required, date-time)
- `updatedAt` (string, required, date-time)

## Example

```bash
curl https://api.kirora.io/v1/segments/018f2a4e-6b1c-7d3e-9f40-37386ae05a6b/contacts \
  -H "Authorization: Bearer $KIRORA_API_KEY"
```

Response `200`:

```json
{
  "data": [
    {
      "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
      "externalId": "user_8812",
      "email": "amaka@juniperkitchen.com",
      "firstName": "Amaka",
      "lastName": "Eze",
      "phone": "+447700900123",
      "timezone": "Europe/London",
      "country": "GB",
      "dates": {},
      "attributes": {},
      "emailConsent": true,
      "pushConsent": true,
      "createdAt": "2030-03-14T09:30:00Z",
      "updatedAt": "2030-03-14T09:30:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "limit": 1,
      "nextCursor": "nextCursor_example"
    },
    "count": 0,
    "countExact": true
  }
}
```