> For the complete documentation index, see [llms.txt](https://api-v2-docs.disasteraware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-v2-docs.disasteraware.com/hazards/requesting-historical-hazards.md).

# Requesting Historical Hazards

The historical archive holds every hazard the platform has tracked, in the same V2 record shape as active hazards, and can be queried by type, time, geography, name, and quantitative thresholds. To query it, use the route defined here:

{% openapi src="/files/wYQaKpPZEdPb68ZWOF6w" path="/historical-hazards-query" method="get" %}
[openapi.yaml](https://3664004773-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbwQ2AvqpbIy1hD3QFTQG%2Fuploads%2Fgit-blob-2e1a036a6f2b8e6525a79c7089f3afec78a9419e%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% hint style="info" %}
See [Authorizing Requests](/authentication/authorizing-requests.md#get-accesstoken-and-refreshtoken) page to get your accessToken.
{% endhint %}

{% hint style="warning" %}
**This endpoint requires a specific role for historical hazard access on your credentials.** It is not enabled by default. If your token works against other endpoints but this one returns `403`, contact your sales contact or <support@disasteraware.com> to have the role added.
{% endhint %}

The previous `/historical_hazards` endpoint (V1 record shape) is deprecated and no longer documented here; see the V1 API documentation if you must remain on it. Its companion `/hazards_count` and alert-geography endpoints are likewise retired: use `count_only=true` for counts, and read `alertGeometry` directly from the V2 record, which carries geometry inline.

## Coverage

The archive is a periodic build, not a live mirror. Records run from 1999 to the date of the most recent build — as of 2026-09-11, hazards created up to 2026-08-06. Hazards newer than the latest build are not in the archive yet; they are available from [`/active-hazards-query`](/hazards/requesting-active-hazards.md) while active and from [`/hazards/{uuid}`](/hazards/requesting-a-hazard.md) at any time. A `count` of `0` for a recent hazard usually means it post-dates the build rather than that it does not exist.

## Response Format

{% hint style="warning" %}
**The response is a redirect, not inline JSON.** A successful query returns **HTTP 302** with a `Location` header pointing at a pre-signed S3 URL. The object at that URL is **gzipped NDJSON**. Your client must follow the redirect and decompress the body. The pre-signed URL is valid for 300 seconds.
{% endhint %}

The decompressed body has one JSON object per line. **The first line is metadata**, and every following line is one hazard record:

```
{"count": 2, "limit": 2, "next_cursor": "WzE3ODUwNTU1MjEsICIwZGM1MGJlZi1lYzM5LTQ1NTQtOTNlNC1mOTc3ZDM3NDFiMzYiXQ=="}
{"uuid": "c554507b-c769-43ab-8c67-07c116d4aa8c", "type": "EARTHQUAKE", ...}
{"uuid": "0dc50bef-ec39-4554-93e4-f977d3741b36", "type": "EARTHQUAKE", ...}
```

| Metadata field   | Meaning                                                                             |
| ---------------- | ----------------------------------------------------------------------------------- |
| **count**        | Number of records in this page.                                                     |
| **limit**        | The page size that was applied.                                                     |
| **next\_cursor** | Opaque cursor for the next page, or `null` on the last page. See [Paging](#paging). |

The curl pattern that handles all of this is:

```bash
curl -sL -H "Authorization: Bearer $TOKEN" \
  'https://api-v2.disasteraware.com/historical-hazards-query?type=EARTHQUAKE&year_gte=2020&country_code=US' \
  | gunzip
```

`-L` follows the redirect; `gunzip` decompresses the body. The only request that does **not** redirect is `count_only=true`, which returns a direct `200 {"count": n}`.

## Record Formats

The `format` parameter selects what each record line contains.

| `format`           | Contents                                                                                                                                                                                                                                                                                                                             | Use it for                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| **full** (default) | The complete V2 hazard record — the same camelCase shape as [`/hazards/{uuid}`](/hazards/requesting-a-hazard.md) and the [hazard sample pages](/hazards/hazard-samples/earthquake-sample.md), with `alertGeometry` inline, plus `legacy_hazard_id`, `location`, and any enhancement blocks. See [The full record](#the-full-record). | Retrieving complete hazards for display, mapping, or archival.                  |
| **list**           | A flat, snake\_case analytical projection: identity, timestamps, admin codes, nearest place, magnitude, enhancement block names, `legacy_hazard_id`, and the quantitative columns listed below.                                                                                                                                      | Filtering and bulk analysis. Rows are small, so large result sets page quickly. |
| **id\_only**       | `{"uuid": "..."}` per line.                                                                                                                                                                                                                                                                                                          | Building an id list to fetch individually.                                      |

The `list` projection carries these quantitative columns, null where they do not apply to the hazard type: `magnitude` and `magnitude_kind`, `mmi_max`, `area_km2`, `casualties`, `damage_usd`, `ef_rating`, `path_length_km`, `hail_max_in`, `wind_gust_mph`, `saffir_cat`, `max_wind_kt`, `min_pressure_mb`, `wind_kt_at_landfall`, `landfalls`, `landfall_admin0s`, `landfall_admin1s`, `basin`, and `exposed_population`. Location comes as `admin0_iso2`, `admin1_code`, `admin2`, and — for events at sea — `nearest_admin0_iso2`, `nearest_admin1_code`, `nearest_place`, and `nearest_distance_km`.

## Paging

Results are capped per request by `limit`: the default is **100** and the hard maximum is **1000**. Values above 1000 are clamped to 1000. For larger sets, walk the cursor:

1. Make the query. Read `next_cursor` from the metadata line.
2. Repeat the **same query** with `cursor=<next_cursor>` appended.
3. Stop when `next_cursor` is `null`.

The cursor is opaque base64 and must be passed back unchanged. Results are stable-ordered — the sort key with `uuid` as a tiebreak — so pages do not overlap or skip records while you walk them. Paging works identically for all three formats.

## Performance

{% hint style="warning" %}
**Always include a selective filter** — at minimum `type`, or a `year_gte`/time bound. The archive holds several hundred thousand records, and a broad scan (for example `min_ef=3&state_code=OK` with no `type`) can exceed the API gateway's request timeout, returning `{"message": "Endpoint request timed out"}` rather than results. Adding `type=TORNADO` to that same query returns in well under a second.
{% endhint %}

`count_only=true` is inexpensive even without filters and is the right way to size a result set before fetching it.

## Query Parameters

All parameters are optional and combine with AND. Comma-separated lists mean "any of". Timestamps accept **epoch seconds or ISO-8601** (for example `2024-01-01T00:00:00Z`).

### Identifiers

| Parameter              | Description                                                                                        |
| ---------------------- | -------------------------------------------------------------------------------------------------- |
| **uuid**               | Point lookup by V2 hazard `uuid`.                                                                  |
| **legacy\_hazard\_id** | Look up by the numeric V1 `hazard_ID`. A legacy construct, supported for migration. Prefer `uuid`. |

### Type and class

| Parameter    | Description                                                                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **type**     | Hazard type, e.g. `TORNADO,HAIL`. Comma-separated list. See [Requesting Hazard Types](/hazards/requesting-active-hazards/requesting-hazard-types.md). |
| **category** | Hazard category. Comma-separated list. See [Requesting Hazard Categories](/hazards/requesting-active-hazards/requesting-hazard-categories.md).        |
| **severity** | Hazard severity. See [Requesting Hazard Severities](/hazards/requesting-active-hazards/requesting-hazard-severities.md).                              |

### Time

| Parameter                                   | Description                                                                                                      |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **started\_at\_gte** / **started\_at\_lte** | Event start at or after / at or before.                                                                          |
| **ended\_at\_gte** / **ended\_at\_lte**     | Event end at or after / at or before.                                                                            |
| **created\_at\_gte** / **created\_at\_lte** | Record creation at or after / at or before.                                                                      |
| **updated\_at\_gte** / **updated\_at\_lte** | Record update at or after / at or before.                                                                        |
| **since**                                   | Alias for `updated_at_gte`. Store the highest `updated_at` you have seen and pass it back for incremental pulls. |
| **year\_gte** / **year\_lte**               | Event year bounds.                                                                                               |
| **month\_in**                               | Event month is one of these values, 1–12. Comma-separated list, e.g. `4,5`.                                      |

### Geography

| Parameter                          | Description                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------- |
| **bbox**                           | Bounding box as `minLon,minLat,maxLon,maxLat` (WGS84).                              |
| **near**                           | Point-radius filter as `lat,lon,radius_km`. The radius must be **2000 km or less**. |
| **country\_code**                  | ISO 3166-1 alpha-2 code of the event location, e.g. `US`.                           |
| **country\_code\_3**               | ISO 3166-1 alpha-3 code, e.g. `USA`.                                                |
| **state\_code** / **admin1\_code** | Admin-1 code, e.g. `US-OK`. Synonyms.                                               |
| **admin2**                         | Admin-2 name (county, district, municipality).                                      |

Country and admin codes describe **where the event happened**, derived from its coordinates. Events at sea have no `admin*` values; use `near` or `bbox` for those, or read the `nearest_*` columns.

### Name

| Parameter                                       | Description                                                    |
| ----------------------------------------------- | -------------------------------------------------------------- |
| **name\_contains** / **hazard\_name\_contains** | Case-insensitive substring match on the hazard name. Synonyms. |

### Enhancement

| Parameter            | Description                                                                                                                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **has\_enhancement** | Only records carrying these enhancement blocks. Comma-separated list of block names: `earthquake`, `cyclone`, `flood`, `tornado`, `hail`, `wind`, `scs`, `exposure`. See [Enhancement blocks](#enhancement-blocks). |

### Quantitative thresholds

Each of these is a `min_` / `max_` pair, e.g. `min_magnitude=6.0` or `max_casualties=10`. A record whose value is null for the column is excluded.

| Column                                                                                                                                                                                                           | Applies to                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| **magnitude**, **mmi**, **mmi\_max**, **shakemap\_mag**                                                                                                                                                          | Earthquake                        |
| **saffir\_cat**, **max\_wind\_kt** (as `min_max_wind_kt` / `max_max_wind_kt`), **wind\_kt**, **wind\_kt\_at\_landfall**, **min\_pressure\_mb** (as `min_min_pressure_mb` / `max_min_pressure_mb`), **landfalls** | Cyclone                           |
| **wind\_gust\_mph**, **hail\_in**, **hail\_max\_in**, **path\_length\_km**                                                                                                                                       | Severe convective storms, tornado |
| **area\_km2**, **casualties**, **damage\_usd**, **exposed\_population**, **exposed\_econ\_usd**, **nearest\_distance\_km**                                                                                       | Any                               |

Two shorthands are also accepted: **min\_ef** for tornadoes, which accepts `3` or `EF3`; and **min\_category** for cyclones, equivalent to `min_saffir_cat`.

### Type-specific and provenance

| Parameter                                    | Description                                                                                                                                     |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **basin**                                    | Cyclone basin: `NA` (North Atlantic), `EP` (East Pacific), `WP` (West Pacific), `NI` (North Indian), `SI` (South Indian), `SP` (South Pacific). |
| **landfall\_country** / **landfall\_admin1** | Cyclones that made landfall in the given country / admin-1.                                                                                     |
| **ef\_rating**                               | Exact tornado EF rating, e.g. `EF5`.                                                                                                            |
| **magnitude\_source**                        | Provenance of the magnitude value.                                                                                                              |

### Output control

| Parameter       | Description                                                                                                                                                                                                                                                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **format**      | `full` (default), `list`, or `id_only`. See [Record Formats](#record-formats).                                                                                                                                                                                                                                                                                         |
| **limit**       | Page size. Default 100, maximum 1000.                                                                                                                                                                                                                                                                                                                                  |
| **cursor**      | `next_cursor` from the previous page.                                                                                                                                                                                                                                                                                                                                  |
| **count\_only** | `true` returns `200 {"count": n}` directly, with no redirect.                                                                                                                                                                                                                                                                                                          |
| **sort**        | `created_at_desc` (default), `created_at_asc`, `updated_at_desc`, `started_at_desc`, `started_at_asc`.                                                                                                                                                                                                                                                                 |
| **order\_by**   | Order by a numeric column, as `column` or `column desc`. Columns: `area_km2`, `casualties`, `damage_usd`, `exposed_econ_usd`, `exposed_population`, `hail_max_in`, `landfalls`, `magnitude`, `max_wind_kt`, `min_pressure_mb`, `mmi_max`, `nearest_distance_km`, `path_length_km`, `saffir_cat`, `shakemap_mag`, `started_at`, `wind_gust_mph`, `wind_kt_at_landfall`. |

When ordering by a column, records with a null value for that column sort first under `desc`. Pair `order_by` with the matching `min_` filter (for example `min_casualties=1`) to exclude them.

## Errors

**400 — validation.** Any bad parameter, value, or cursor returns a body that says what was wrong and lists every parameter the endpoint accepts. The `allowed_parameters` list is generated from the same table the API validates against, so it is always current:

```json
{
  "error": "Query validation failed",
  "details": ["near must be lat,lon,radius_km (radius <= 2000)"],
  "allowed_parameters": ["admin1_code", "admin2", "basin", "bbox", "category", "count_only", "..."]
}
```

A malformed cursor returns `{"error": "bad cursor"}`. Unknown values for `type`, `has_enhancement`, or `month_in` are not errors; they simply match nothing.

**403** — the token is invalid or expired, or the credentials lack the role required for historical hazard access.

## The full record

With `format=full` (the default), and from [`/hazards/{uuid}`](/hazards/requesting-a-hazard.md), each record is the complete V2 hazard shape documented in [Requesting Active Hazards](/hazards/requesting-active-hazards.md#response-fields), with three additions that only historical records carry.

**`legacy_hazard_id`** — the hazard's V1 numeric `hazard_ID`. Use it to map existing V1 integrations onto V2 uuids.

**`location`** — a reverse-geocoded administrative block. Events on land carry the admin hierarchy; events at sea carry the nearest place instead:

```json
{ "admin0": "United States of America", "admin0_iso2": "US", "admin0_iso3": "USA", "admin1": "Missouri", "admin1_code": "US-MO", "admin2": "Ste. Genevieve", "admin2_code": "29186", "continent": "North America", "subregion": "Northern America", "location_type": "land", "source": "arcgis_reverse_geocoder" }
```

```json
{ "location_type": "ocean", "nearest_country_code": "TO", "nearest_admin1": "'Eua", "nearest_place": "`Ohonua", "source": "arcgis_reverse_geocoder" }
```

### Enhancement blocks

Historical records may carry post-event analysis blocks that active records never have. The `list` format names them in `enhancement_blocks`; `has_enhancement` filters on them; and the `full` format includes them as top-level objects.

| `has_enhancement` value | Blocks on the full record             | Source and contents                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **earthquake**          | `earthquakeAssessment`                | USGS ShakeMap summary: `usgs_event_id`, `magnitude`, `depth_km`, `max_mmi`, `max_pga_g`, `max_pga_pctg`, `pga_contour_count`, `pga_contours`, `shakemap_version`.                                                                                                                                                                                                                              |
| **cyclone**             | `cycloneAssessment`, `cycloneDetails` | NOAA IBTrACS best-track archive. The assessment summarises the storm (`storm_name`, `season`, `basin`, `max_category`, `max_wind_kts`, `min_pressure_mb`, `duration_hours`, `hours_at_hurricane_force`, `hours_at_major_hurricane`, `landfalls`, `track_length_km`, `track_points_count`); the details block carries the full observed `track`.                                                |
| **flood**               | `floodAssessment`, `floodDetails`     | NWS flood post-event analysis. The assessment carries `flood_class`, `triggering_event`, `max_gauge_category`, `max_above_flood_stage_ft`, `depth_method`, and counts of `gauges`, `road_closures`, `storm_reports`, and `survey_points`; the details block carries the underlying `alert` and `alert_polygon`, `gauges`, `depth`, `impacts`, `road_closures`, `storm_reports`, and `sources`. |
| **tornado**             | `tornadoAssessment`, `tornadoDetails` | NWS post-event analysis: Damage Assessment Toolkit paths and points, Storm Prediction Center reports, and Local Storm Reports. The assessment carries `max_ef_rating`, `total_fatalities`, `total_injuries`, and per-source counts; the details block carries the underlying `dat_paths`, `dat_points`, `local_storm_reports`, and `spc_reports`.                                              |
| **hail**                | `hailAssessment`, `hailDetails`       | Hail reports and MESH radar swaths: `best_estimate_in`, `max_measured_in`, `max_reported_in`, `mesh_max_swath_in`, `size_description`, with `hail_reports`, `mesh_swaths`, and `svr_warnings` in the details.                                                                                                                                                                                  |
| **wind**                | `windAssessment`, `windDetails`       | Wind damage and gust reports, with `wind_reports` in the details.                                                                                                                                                                                                                                                                                                                              |
| **scs**                 | `scsClassification`                   | Severe convective storm classification across the tornado, hail, and wind sub-perils: `is_scs`, `sub_perils_present`, `max_ef_rating`, `max_hail_size_in`, and the source of each.                                                                                                                                                                                                             |
| **exposure**            | `exposureAssessment`                  | The standard population and infrastructure exposure block, as on active hazards.                                                                                                                                                                                                                                                                                                               |

A tornado record from a surveyed outbreak typically carries `tornado`, `hail`, `wind`, and `scs` together. Field-level detail for the earthquake, cyclone, and tornado blocks is on the enhanced historical sample pages ([earthquake](/hazards/hazard-samples/enhanced-historical-earthquake-sample.md), [cyclone](/hazards/hazard-samples/enhanced-historical-cyclone-sample.md), [tornado](/hazards/hazard-samples/enhanced-historical-tornado-sample.md)); note that those pages show the blocks inside the legacy V1 wrapper, whereas this endpoint returns them on the V2 record.

Historical full records also have `source` set to `null` and `features` set to `null` in the general case; `alertGeometry`, `exposureAreas`, and `exposureAssessment` are populated as on active hazards.

## Worked Examples

Every example below was run against the production API — the parameter-syntax examples on 2026-09-18, the rest on 2026-09-11. Counts will have grown since. `$TOKEN` is the access token from `/authorize`; the pattern is always:

```bash
curl -sL -H "Authorization: Bearer $TOKEN" 'https://api-v2.disasteraware.com/historical-hazards-query?...' | gunzip
```

### Combining parameters

Two rules cover the whole query syntax:

* **Different parameters are combined with AND.** `?type=TORNADO&state_code=OK` returns tornadoes that are also in Oklahoma.
* **Multiple values within one parameter are comma-separated and combined with OR.** `?type=TORNADO,HAIL` returns tornadoes and hail events.

Anything containing a space must be URL-encoded — `order_by=casualties%20desc`, `+` also works — and the URL should be single-quoted in `curl` so the shell does not interpret the `&` characters. A misspelled parameter returns `400` with the full list of accepted parameters (see [Errors](#errors)).

Two hazard types at once, narrowed by severity:

```
?type=TORNADO,HAIL&severity=WARNING&count_only=true
```

```json
{"count": 101337}
```

Add a time bound and a seasonal window to cut that down — April and May of 2024 onward:

```
?type=TORNADO,HAIL&severity=WARNING&year_gte=2024&month_in=4,5&count_only=true
```

```json
{"count": 12262}
```

Every additional parameter narrows the result, so build a query up one filter at a time with `count_only=true` before fetching the records themselves (see [Sizing a query before fetching it](#sizing-a-query-before-fetching-it)).

### Bounding box

`bbox` takes four comma-separated numbers in the order `minLon,minLat,maxLon,maxLat`. Note that longitude comes first, which is the GeoJSON convention and the reverse of the `near` parameter's `lat,lon,radius_km`.

```
?type=WILDFIRE&bbox=-125,32,-114,42&year_gte=2023&limit=2&format=list
```

```
{"count": 2, "limit": 2, "next_cursor": "WzE3ODU4MzU2ODUsICJjOGYxODkyOC02YjM0LTRhY2QtODI4Ny1mNjg4N2ZiZTE2OTIiXQ=="}
{"uuid": "439f4a96-0b5e-4ffa-ba63-b1be646c8c0e", "type": "WILDFIRE", "severity": "ADVISORY", "name_en": "Wildfire - ANDERSON, California, United States", "latitude": 39.78707, "longitude": -123.24822, "admin1_code": "US-CA", "admin2": "Mendocino", "area_km2": 1191.9804052226245, ...}
{"uuid": "c8f18928-6b34-4acd-8287-f6887fbe1692", "type": "WILDFIRE", "severity": "WARNING", "name_en": "Wildfire - Mexicali, Baja California, Mexico", "latitude": 32.54095, "longitude": -115.1077, "admin1_code": "MX-BCN", "admin2": null, ...}
```

415 records matched in total. The box is tested against each record's own `latitude`/`longitude`, and it does not respect national borders — the second record is in Mexico, inside the box. Add `country_code=US` to restrict it.

### Threshold plus time bound

```
?type=EARTHQUAKE&min_magnitude=7.0&year_gte=2015&count_only=true
```

```json
{"count": 179}
```

Every quantitative column has a `min_` / `max_` pair that can be combined the same way; `?type=EARTHQUAKE&min_magnitude=7.0&max_magnitude=7.9` brackets a band.

### Sizing a query before fetching it

```
?type=EARTHQUAKE&year_gte=2020&country_code=US&count_only=true
```

```json
{"count": 490}
```

This returns `200` directly, with no redirect.

### Basic filter

```
?type=EARTHQUAKE&year_gte=2020&country_code=US&limit=2&format=list
```

```
{"count": 2, "limit": 2, "next_cursor": "WzE3ODUwNTU1MjEsICIwZGM1MGJlZi1lYzM5LTQ1NTQtOTNlNC1mOTc3ZDM3NDFiMzYiXQ=="}
{"uuid": "c554507b-c769-43ab-8c67-07c116d4aa8c", "type": "EARTHQUAKE", "severity": "ADVISORY", "category": "EVENT", "name_en": "Earthquake - 5.0 - 51 km E of Denali National Park, Alaska", "latitude": 63.611, "longitude": -150.673, "created_at": 1785272838, "started_at": 1785271764, "ended_at": 1785358164, "no_scheduled_end": false, "admin0_iso2": "US", "admin1_code": "US-AK", "admin2": "Denali", "nearest_admin0_iso2": null, "nearest_admin1_code": null, "nearest_place": null, "nearest_distance_km": null, "magnitude": 5.0, "magnitude_kind": "mw", "enhancement_blocks": ["earthquake", "exposure"], "legacy_hazard_id": 471892, "hail_max_in": null, "wind_gust_mph": null, "saffir_cat": null, "max_wind_kt": null, "min_pressure_mb": null, "basin": null, "landfalls": null, "landfall_admin0s": null, "landfall_admin1s": null, "wind_kt_at_landfall": null, "mmi_max": 5.23, "ef_rating": null, "casualties": null, "damage_usd": null, "area_km2": 98101.71167124063, "path_length_km": null, "exposed_population": 0.0}
{"uuid": "0dc50bef-ec39-4554-93e4-f977d3741b36", "type": "EARTHQUAKE", "severity": "WATCH", ...}
```

### Spatial: tornadoes within 100 km of Denver

```
?near=39.74,-104.99,100&type=TORNADO&count_only=true
```

```json
{"count": 617}
```

### Threshold: Category 4+ North Atlantic hurricanes

```
?type=CYCLONE&min_saffir_cat=4&basin=NA&limit=2&format=list
```

```
{"count": 2, "limit": 2, "next_cursor": "..."}
{"uuid": "1e4d762a-c03e-4ea5-bbed-8001827b1045", "type": "CYCLONE", "name_en": "Major Hurricane - MELISSA", "nearest_admin0_iso2": "JM", ...}
{"uuid": "67da3838-25f6-4713-bd80-6e3e4fdc0e1b", "type": "CYCLONE", "name_en": "Major Hurricane - HUMBERTO", "nearest_admin0_iso2": "AI", ...}
```

Sixty-six records matched in total.

### Ordering: strongest Oklahoma tornadoes by casualties

```
?type=TORNADO&min_ef=3&state_code=OK&order_by=casualties%20desc&limit=3&format=list
```

```
{"count": 3, "limit": 3, "next_cursor": "..."}
{"name_en": "Tornado - Norman, OK WFO Region, US", "ef_rating": "EF3", "casualties": 16.0, ...}
{"name_en": "Tornado — Comanche [OK]", "ef_rating": "EF3", "casualties": 12.0, ...}
{"name_en": "Tornado — Bryan [OK]", "ef_rating": "EF3", "casualties": 12.0, ...}
```

Note the `type=TORNADO` filter. Without it, this query scans the whole archive and times out at the gateway. The space in `order_by` must be URL-encoded as `%20` (or `+`).

### Walking the cursor

Page 1:

```
?type=EARTHQUAKE&year_gte=2020&country_code=US&limit=2&format=list
```

```
{"count": 2, "limit": 2, "next_cursor": "WzE3ODUwNTU1MjEsICIwZGM1MGJlZi1lYzM5LTQ1NTQtOTNlNC1mOTc3ZDM3NDFiMzYiXQ=="}
{"uuid": "c554507b-c769-43ab-8c67-07c116d4aa8c", "created_at": 1785272838, ...}
{"uuid": "0dc50bef-ec39-4554-93e4-f977d3741b36", "created_at": 1785055521, ...}
```

Page 2 — the same query with `cursor` appended:

```
?type=EARTHQUAKE&year_gte=2020&country_code=US&limit=2&format=list&cursor=WzE3ODUwNTU1MjEsICIwZGM1MGJlZi1lYzM5LTQ1NTQtOTNlNC1mOTc3ZDM3NDFiMzYiXQ==
```

```
{"count": 2, "limit": 2, "next_cursor": "WzE3ODQ4NTU2NjUsICJjNTNjOTQxYS0zOWFmLTQ0NDMtYjU4NC1hYzc2ZWQ4NTA2ZTAiXQ=="}
{"uuid": "dd242b92-0731-4c4b-80aa-b612bb1c106a", "created_at": 1785014061, ...}
{"uuid": "c53c941a-39af-4443-b584-ac76ed8506e0", "created_at": 1784855665, ...}
```

Continue until `next_cursor` is `null`. Note that `created_at` descends across the page boundary with no gap or overlap.

### Migration: looking up a V1 hazard by its numeric id

```
?legacy_hazard_id=471892&format=full
```

Returns the V2 record for the hazard that was `hazard_ID` 471892 in the V1 API — the Denali earthquake above. The record's own `legacy_hazard_id` field carries the same value, so a one-time pass over your stored V1 ids gives you the uuid for each.

A `count` of `0` means that V1 id is not in the historical archive — most often because the hazard was created after the archive's most recent build (see [Coverage](#coverage)). For those, [`/hazards/{id}`](/hazards/requesting-a-hazard.md) with the numeric id still returns the V1-shaped record.