# List audiences

`GET /audiences`

Returns the active audiences (contact segments and lists) of one shop
(`shop_id`) or all your shops, sorted by creation date descending, with
their current contact count.

Requires the `audiences:read` scope.

**Returns** a `data` array of up to `limit` audiences and a
`pagination` object. Fetch the next page by passing
`pagination.next_cursor` back as `cursor`, until `has_more` is
`false`. `data` is empty when nothing matches the filters.

`contact_count` is the size at the last recomputation, whose time is
given by `last_computed_at`.

## Example request

```bash
curl "https://api.dokaa.app/v1/audiences" \
  -H "Authorization: Bearer dk_live_..."
```

## Query parameters

- `shop_id` (string) – Restrict to a single shop (omit to query all your shops)
- `type` (string) (one of: segment, list) – Filter by audience type
- `cursor` (string) – Opaque cursor from the previous response's `pagination.next_cursor`
- `limit` (integer) (default: 25; min: 1; max: 100) – Number of items per page

## Responses

### 200 – Paginated list of audiences

```json
{
  "data": [
    {
      "id": "66f6a7b8c9d0e1f2a3b4c5d6",
      "shop_id": "64f1a2b3c4d5e6f7a8b9c0d1",
      "name": "Clients fidèles",
      "type": "segment",
      "contact_count": 480,
      "last_computed_at": "2026-08-06T03:00:00Z",
      "created_at": "2026-02-10T10:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}
```

### 401 – Missing, invalid, or revoked API key

### 403 – The API key does not grant access to this resource

### 422 – Invalid request parameters

Errors are `application/problem+json` (RFC 9457) with `type`, `title`, `status` and `detail` fields.