> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publica.la/llms.txt
> Use this file to discover all available pages before exploring further.

# List Aggregates

Retrieve a paginated list of all sub-tenants (aggregates) under your aggregator store.

---

## Endpoint

```
GET /api/v3/aggregates
```

---

## Query Parameters

| Parameter  | Type    | Default | Description                                     |
| ---------- | ------- | ------- | ----------------------------------------------- |
| `per_page` | integer | 100     | Items per page (1-100)                          |
| `cursor`   | string  | -       | Cursor token from `links.next` or `links.prev`  |
| `include`  | string  | -       | Comma-separated list of extra fields: `api_key` |

---

## Response

### Success Response (200 OK)

```json
{
  "data": [
    {
      "id": 42,
      "slug": "my-bookstore",
      "name": "My Bookstore",
      "final_domain": "mybookstore.publica.la",
      "lang": "en",
      "timezone": "America/New_York",
      "support_email": "support@mybookstore.com",
      "primary_color": "#336699",
      "secondary_color": "#FF6600",
      "reader_accent_color": "#0066CC",
      "reader_flashcards_enabled": true,
      "logo_url": "https://assets.publica.la/my-bookstore/logo/logo.png",
      "icon_url": "https://assets.publica.la/my-bookstore/icons/icon.png",
      "disable_selling": false,
      "landing_enabled": true,
      "storefront_redirect": {
        "enabled": false,
        "url": null
      },
      "external_auth": {
        "enabled": true,
        "issuer": "my-platform",
        "redirect_url": "https://my-platform.com/auth-error",
        "login_url": null,
        "logout_url": null,
        "home_url": null,
        "account_url": null
      },
      "created_at": "2026-03-24T15:30:00+00:00"
    },
    {
      "id": 43,
      "slug": "another-store",
      "name": "Another Store",
      "final_domain": "another-store.publica.la",
      "lang": "es",
      "timezone": "America/Mexico_City",
      "support_email": "soporte@another-store.com",
      "primary_color": "#1A237E",
      "secondary_color": "#FF6F00",
      "reader_accent_color": null,
      "reader_flashcards_enabled": false,
      "logo_url": null,
      "icon_url": null,
      "disable_selling": true,
      "landing_enabled": false,
      "storefront_redirect": {
        "enabled": true,
        "url": "https://discovery.example.com"
      },
      "external_auth": {
        "enabled": false,
        "issuer": null,
        "redirect_url": null,
        "login_url": null,
        "logout_url": null,
        "home_url": null,
        "account_url": null
      },
      "created_at": "2026-03-20T10:00:00+00:00"
    }
  ],
  "links": {
    "next": "https://yourstore.publica.la/api/v3/aggregates?cursor=eyJjcmVhdGVkX2F0...",
    "prev": null
  },
  "meta": {
    "has_more": true
  }
}
```

---

## Examples

### Basic List

```bash
curl -X GET "https://yourstore.publica.la/api/v3/aggregates" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

### With API Keys

```bash
curl -X GET "https://yourstore.publica.la/api/v3/aggregates?include=api_key" \
  -H "X-User-Token: your-api-token" \
  -H "Accept: application/json"
```

### Pagination Flow

```bash
# First page
curl -X GET "https://yourstore.publica.la/api/v3/aggregates?per_page=50" \
  -H "X-User-Token: your-api-token"

# Response includes:
# "links": { "next": "...?cursor=eyJjcmVhdGVkX2F0..." }

# Next page
curl -X GET "https://yourstore.publica.la/api/v3/aggregates?per_page=50&cursor=eyJjcmVhdGVkX2F0..." \
  -H "X-User-Token: your-api-token"
```

---

## Ordering

Results are ordered by creation date descending (newest first), with ID descending as a tie-breaker for deterministic pagination.

---

## Isolation

The list only returns aggregates owned by your store. You cannot see aggregates owned by other aggregators.

---

## Error Handling

### Validation Errors (422)

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "per_page": ["The per page must be between 1 and 100."]
  }
}
```

### Authentication Errors (401)

```json
{
  "message": "Unauthenticated."
}
```

### Authorization Errors (403)

```json
{
  "message": "Tenant does not have aggregation capabilities."
}
```

---

## See Also

- [Get Aggregate](./aggregates-v3-get.md) - Retrieve a specific aggregate
- [Create Aggregate](./aggregates-v3-create.md) - Provision a new aggregate
- [Overview](./aggregates-v3-overview.md) - API overview