# List events

Retrieve a paginated, filterable list of events for the organization.

Source: https://statusdashboard.com/docs/api/event-management/events/list

`GET /app/events`

Returns events for the authenticated tenant, sorted by last updated date descending (`updatedAt`).

> **Sort order note:** Results are ordered by `updatedAt` — the timestamp of the most recent change to each event (including timeline and note updates). This means a recently-updated older event will appear above a never-touched newer one.

***

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

### Query parameters
| Parameter   | Type   | Description                                                                                                                                            |                                                                                                         |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `startDate` | string | Lower bound on `updatedAt`. ISO 8601 format (`YYYY-MM-DD` or full timestamp). Optional.                                                                |                                                                                                         |
| `endDate`   | string | Upper bound on `updatedAt`. ISO 8601 format (`YYYY-MM-DD` or full timestamp). Optional. Date-only values are treated as end-of-day (`T23:59:59.999Z`). |                                                                                                         |
| `eventType` | string | Filter by type: `"incident"`, `"maintenance"`, or `"informational"`. Optional.                                                                         |                                                                                                         |
| `publish`   | string | Filter by visibility: `"true"` (published) or `"false"` (draft). Optional.                                                                             |                                                                                                         |
| `limit`     | number | Number of events to return. Default: `10`. Min: `1`. Max: `100`.                                                                                       |                                                                                                         |
| `nextToken` | string | No                                                                                                                                                     | Next-page bookmark from the previous response — pass unchanged. See [Pagination](/docs/api#pagination). |

All parameters are optional. Omitting filter parameters returns all events.

***

## Sample request
```bash
curl "https://api.statusdashboard.com/app/events?eventType=incident&publish=true&limit=10" \
  -H "Authorization: Bearer bcf847abf5c6:def456"
```

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

```json
{
  "events": [
    {
      "id": "4f8b2e1a-3c7d-4e9f-a0b1-c2d3e4f56789",
      "eventType": "incident",
      "title": "API latency elevated",
      "status": { "label": "Monitoring", "isFinal": false },
      "publish": true,
      "updatedAt": "2026-04-25T10:30:00.000Z"
    },
    {
      "id": "9a2c4e6f-7b8d-4f1a-b3c5-d7e8f90a1b2c",
      "eventType": "informational",
      "title": "Scheduled database upgrade next weekend",
      "status": null,
      "publish": true,
      "updatedAt": "2026-05-10T14:00:00.000Z"
    }
  ],
  "nextToken": "eyJpZCI6ImV2dF8wMUhYWVoifQ==",
  "limits": {
    "attributes": 5,
    "notesPerEvent": 50,
    "timelineEntriesPerEvent": 50,
    "componentsPerEvent": 100
  }
}
```

***

## Response fields
| Field                            | Type           | Description                                                                                   |
| -------------------------------- | -------------- | --------------------------------------------------------------------------------------------- |
| `events`                         | array          | Array of event summary objects.                                                               |
| `nextToken`                      | string \| null | See [Pagination](/docs/api#pagination). `null` when there are no more pages.                  |
| `limits`                         | object         | Per-event limit caps for this organization (notes, timeline entries, components, attributes). |
| `limits.attributes`              | number         | Max custom attributes per event (public + private).                                           |
| `limits.notesPerEvent`           | number         | Max internal notes per event.                                                                 |
| `limits.timelineEntriesPerEvent` | number         | Max timeline entries per event.                                                               |
| `limits.componentsPerEvent`      | number         | Max affected components per event.                                                            |

### Event summary object
The list endpoint returns a **summary** of each event — not the full record. Use [Get event](/docs/api/event-management/events/get) to retrieve the complete event including `notifications`, description, components, timeline, and notes.

| Field                | Type           | Description                                                                             |
| -------------------- | -------------- | --------------------------------------------------------------------------------------- |
| `id`                 | string         | Unique event ID.                                                                        |
| `eventType`          | string         | `"incident"`, `"maintenance"`, or `"informational"`.                                    |
| `title`              | string         | Brief event title.                                                                      |
| `status`             | object \| null | Current workflow status. `null` for informational events.                               |
| `status.label`       | string         | Status label from the workflow phases.                                                  |
| `status.isFinal`     | boolean        | Whether this is a final (terminal) workflow phase.                                      |
| `status.isScheduled` | boolean        | Present and `true` only on maintenance events in the scheduled phase. Absent otherwise. |
| `publish`            | boolean        | Whether the event is visible on status dashboards.                                      |
| `updatedAt`          | string         | ISO 8601 UTC timestamp of the last update.                                              |

***

## Pagination
See [Pagination](/docs/api#pagination) in API Basics. Re-send the same query parameters on every page request.

***

## Error responses
| Status | When                      |
| ------ | ------------------------- |
| `400`  | Invalid query parameters. |
| `403`  | Insufficient permissions. |