---
title: "List incidents"
method: GET
path: "/v1/data/incidents"
tags: ["Incidents"]
---

# List incidents

`GET /v1/data/incidents`

## Request

- Base URL: `https://api.mapulus.com`
- URL: `https://api.mapulus.com/v1/data/incidents`
- Auth: HTTP bearer

List and filter real-time incidents.

Supports hierarchical filtering: `type` (incident category), `event_type` (specific
event category), `event_subtype` (granular subtype), plus status, state, severity,
source, boundary intersection, radius search, and time range.

Both `type` and `status` accept comma-separated values for multi-value filtering
(e.g. `?status=active,upcoming` or `?type=traffic,fire`).

**Ordering**: Radius queries default to closest-first (`sort=distance`) and include
`distance_km` in each result. Use `sort=newest` to revert to newest-first ordering.
Non-spatial queries always order by newest first.

Time range filters: `since`/`until` filter on `started_at`, `ends_after`/`ends_before`
filter on `expected_end_at` (useful for finding planned outages within a window).

Each incident includes structured location fields: `locality` (suburb/area name),
`road_name` (affected road), and `location_detail` (free-text location description).

Set `detail=true` to include full geometry, description, and raw source data per
incident (same fields as the single-incident detail endpoint).

## Query parameters

- `type` string, nullable: Filter by incident type (traffic, fire, power, weather). Comma-separated for multiple.
- `event_type` string, nullable: Filter by event type (e.g. roadworks, crash, flood, fire_vegetation).
- `event_subtype` string, nullable: Filter by event subtype (e.g. flash_flood, planned_roadworks, multi_vehicle).
- `status` string: Filter by status (active, upcoming, resolved, expired). Comma-separated for multiple.
- `state` string, nullable: Filter by state (QLD, NSW, etc.).
- `severity` string, nullable: Filter by severity (minor, moderate, major, extreme).
- `source` string, nullable: Filter by source_id.
- `boundary_id` string, nullable: Incidents intersecting this boundary (e.g. `lga:17200`).
- `lat` number, nullable: Latitude for radius search.
- `lng` number, nullable: Longitude for radius search.
- `radius_km` number, nullable: Search radius in km (requires lat, lng).
- `since` string, nullable: Incidents started after this ISO datetime.
- `until` string, nullable: Incidents started before this ISO datetime.
- `ends_after` string, nullable: Incidents with expected_end_at after this ISO datetime.
- `ends_before` string, nullable: Incidents with expected_end_at before this ISO datetime.
- `detail` boolean: Include full detail per incident (geometry, description, source data).
- `sort` string, nullable: Sort order: 'distance' (closest first) or 'newest' (most recent first). Default: 'distance' for radius queries, 'newest' otherwise.
- `limit` integer: Page size.
- `offset` integer: Pagination offset.

## Response `200`

Paginated list of incidents. Use detail=true for full geometry and source data.

- ResponseEnvelopeUnionListIncidentSummaryListIncidentDetail
  - `data` union, required: Response payload.
    - IncidentSummary[]
      - `incident_id` string, required
      - `source_id` string, required
      - `incident_type` string, required
      - `event_type` string, nullable
      - `event_subtype` string, nullable
      - `severity` string, nullable
      - `status` string, required
      - `title` string, required
      - `state` string, required
      - `locality` string, nullable: Suburb or locality name.
      - `road_name` string, nullable: Affected road name.
      - `location_detail` string, nullable: Free-text location description.
      - `centroid` object, nullable: GeoJSON point (centroid).
      - `started_at` string, date-time, required
      - `expected_end_at` string, date-time, nullable
      - `resolved_at` string, date-time, nullable
      - `distance_km` number, nullable: Distance in km from the query point.
    - IncidentDetail[]
      - `incident_id` string, required
      - `source_id` string, required
      - `source_incident_id` string, required
      - `incident_type` string, required
      - `event_type` string, nullable
      - `event_subtype` string, nullable
      - `severity` string, nullable
      - `status` string, required
      - `title` string, required
      - `description` string, nullable
      - `state` string, required
      - `locality` string, nullable: Suburb or locality name.
      - `road_name` string, nullable: Affected road name.
      - `location_detail` string, nullable: Free-text location description.
      - `geometry` object, nullable: GeoJSON geometry object.
      - `centroid` object, nullable: GeoJSON point (centroid).
      - `data` object: Source-specific properties.
      - `started_at` string, date-time, required
      - `expected_end_at` string, date-time, nullable
      - `resolved_at` string, date-time, nullable
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
      - `distance_km` number, nullable: Distance in km from the query point.
  - `meta` ResponseMeta: Response metadata.
    - `request_id` string, nullable
    - `pagination` PaginationMeta: Pagination metadata for list responses.
      - `total` integer, required: Total number of matching records.
      - `limit` integer, required: Maximum records returned per page.
      - `offset` integer, required: Number of records skipped.
      - `has_more` boolean, required: Whether more records exist beyond this page.
    - `demographics` DemographicsMeta: Demographics-specific metadata returned with census data endpoints.
      - `topics_included` string[], required: Topics included in the response.
      - `topics_available` string[]: Additional topics available but not requested.
    - `sources` object, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/mapulus/apis/mapulus-api.md) · [All operations](https://skmtc.dev/mapulus/apis/mapulus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mapulus/apis/mapulus-api/revisions/b99766fa053f?raw)