# List dashboards

List all dashboards for the organization.

Source: https://statusdashboard.com/docs/api/status-dashboards/dashboards/list

`GET /app/dashboards`

Returns all dashboards belonging to the caller's organization.

Requires the `admin` or `subscriber` role. The `event` role does not use dashboard APIs. Create, update, and delete operations remain admin-only.

Each item is a **list projection** — enough for navigation, domain status, component wiring, and subscription toggles. Tab-specific settings (branding, content, SSO, custom code, and so on) are not included; use the dedicated tab GET endpoints for those fields.

***

## Request
See [API Basics](/docs/api) for required headers.

This endpoint takes no request body or query parameters.

***

## Sample request
```bash
curl https://api.statusdashboard.com/app/dashboards \
  -H "Authorization: Bearer bcf847abf5c6:def456"
```

## Sample response
**Status: `200 OK`**

```json
{
  "dashboards": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d480",
      "name": "Production Status",
      "subdomain": "acme",
      "pageTitle": "Acme Status",
      "description": "Status dashboard for all Acme services",
      "customDomain": "status.acme.com",
      "customDomainStatus": "active",
      "customDomainCreatedAt": "2026-02-01T10:00:00.000Z",
      "customDomainValidationStartedAt": "2026-02-01T10:05:00.000Z",
      "customDomainUpdatedAt": "2026-02-15T14:30:00.000Z",
      "cloudFrontTenantId": "cf-tenant-abc123",
      "cloudFrontTenantArn": "arn:aws:cloudfront::123456789012:distribution/EDFDVBD6EXAMPLE/tenant/cf-tenant-abc123",
      "components": {
        "compact": false,
        "groups": {
          "enabled": true,
          "expandByDefault": false,
          "items": [
            {
              "id": "d4e5f6a7-b8c9-0123-def0-234567890123",
              "name": "Infrastructure",
              "order": 1
            }
          ]
        },
        "components": {
          "a1b2c3d4-e5f6-7890-abcd-ef1234567891": {
            "displayOrder": 1,
            "groupId": "d4e5f6a7-b8c9-0123-def0-234567890123"
          },
          "f6a7b8c9-d0e1-2345-f012-456789012345": {
            "displayOrder": 2
          }
        }
      },
      "subscriptions": {
        "email": { "enabled": true },
        "sms": { "enabled": false }
      },
      "enabled": true,
      "createdAt": "2026-01-10T12:00:00.000Z",
      "updatedAt": "2026-04-01T08:00:00.000Z"
    }
  ]
}
```

When custom domain setup fails, `customDomainError` may be present. When no custom domain is configured, custom-domain fields are absent.

***

## Response fields
Each object in `dashboards`:

| Field                             | Type             | Description                                                                                                                                                                       |
| --------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                              | string           | Unique dashboard ID (UUID).                                                                                                                                                       |
| `tenantId`                        | string           | Organization ID.                                                                                                                                                                  |
| `name`                            | string           | Dashboard display name.                                                                                                                                                           |
| `subdomain`                       | string           | Subdomain slug.                                                                                                                                                                   |
| `pageTitle`                       | string           | Public browser tab title.                                                                                                                                                         |
| `description`                     | string \| absent | Short dashboard description.                                                                                                                                                      |
| `customDomain`                    | string \| absent | Custom hostname when configured.                                                                                                                                                  |
| `customDomainStatus`              | string \| absent | Custom domain lifecycle status (`awaiting_dns`, `validating`, `active`, `failed`, `removing`).                                                                                    |
| `customDomainError`               | string \| absent | Error message when status is `failed`.                                                                                                                                            |
| `customDomainCreatedAt`           | string \| absent | ISO 8601 UTC timestamp when the custom domain was first configured.                                                                                                               |
| `customDomainValidationStartedAt` | string \| absent | ISO 8601 UTC timestamp when CloudFront provisioning started.                                                                                                                      |
| `customDomainUpdatedAt`           | string \| absent | ISO 8601 UTC timestamp of the last custom-domain status change.                                                                                                                   |
| `cloudFrontTenantId`              | string \| absent | CloudFront distribution tenant ID (internal provisioning reference).                                                                                                              |
| `cloudFrontTenantArn`             | string \| absent | CloudFront distribution tenant ARN.                                                                                                                                               |
| `components`                      | object           | Nested component wiring — see [Get dashboard components](/docs/api/status-dashboards/dashboards/components/get).                                                                  |
| `components.compact`              | boolean          | Compact display mode for many components.                                                                                                                                         |
| `components.groups`               | object \| absent | Component group configuration.                                                                                                                                                    |
| `components.components`           | object           | Map of component UUID → `{ displayOrder, groupId? }`.                                                                                                                             |
| `subscriptions`                   | object           | Per-dashboard email, SMS, and WhatsApp subscription toggles (`email.enabled`, `sms.enabled`, `whatsapp.enabled`). Plan entitlement still applies on the public subscribe surface. |
| `enabled`                         | boolean          | Whether the dashboard is publicly accessible.                                                                                                                                     |
| `createdAt`                       | string           | ISO 8601 UTC creation timestamp.                                                                                                                                                  |
| `updatedAt`                       | string           | ISO 8601 UTC last-updated timestamp.                                                                                                                                              |

Fields **not** included in the list projection (use tab GET endpoints instead): `systemMessage`, `content`, `customCode`, `branding`, `sso`, `ipAllowlist`, `emailSender`, `whitelabel`, `support`, `widget`, and `emailDomainAllowlist`.

***

## Error responses
| Status | When                      |
| ------ | ------------------------- |
| `403`  | Insufficient permissions. |