# USGS Earthquakes

> Read the USGS Earthquake Catalog: every earthquake the USGS and its contributing networks have recorded, from this minute back through the last century. Watch the real-time feeds on a schedule, search the catalog by time, magnitude, depth, region or PAGER alert level, geo-fence a site and see how far away each event was and in which direction, count a window before you fetch it, pull the largest event of the week, or summarise a period for a digest. No API key, no sign-up and no quota.

App · Weather & Space · 11 actions. Web page: https://docs.lodol.com/docs/integrations/usgs-earthquakes

## Actions

### Check service status

Check whether the USGS earthquake catalog is answering, and how quickly. This is the one action that reports a problem as a value instead of failing the step, so a workflow can decide what to do about it - skip a digest, wait, or say the data is stale rather than dying halfway through. Being throttled is reported separately from being down.

**Inputs**: None.

**Outputs**

- `api_version` (text)
- `message` (text)
- `online` (true/false)
- `rate_limited` (true/false)
- `reachable` (true/false)
- `response_time_ms` (number)
- `status_code` (number)

**Example output**

```json
{
  "api_version": "1.14.1",
  "message": "The USGS earthquake catalog is up, running API 2.7.0.",
  "online": true,
  "rate_limited": false,
  "reachable": true,
  "response_time_ms": 143.7,
  "status_code": 200
}
```

### Count earthquakes

Count the earthquakes a search would match, without fetching any of them. One small answer however big the number, which makes it the cheap way for a schedule to ask 'was there anything?' before doing the expensive part - and the way to check a search is inside the 20,000 events one response can carry, since the catalog rejects a bigger one rather than trimming it.

**Inputs**

- Start time (`start_time`, date and time): Only events at or after this moment. Leave it and 'Days back' empty to use this action's own default window. Times are UTC unless the value says otherwise.
- End time (`end_time`, date and time): Only events at or before this moment. Leave it empty to search up to now, which is what a scheduled run almost always wants: the catalog decides what 'now' is, so an event that arrives while the step runs is still included.
- Days back (`days_back`, number): Look this many days back instead of naming a start date - what a workflow that runs every morning needs, since 'the last 7 days' cannot be written as a fixed date. Counted back from now, or from 'End time' if you set one. Give this or 'Start time', not both. From 1 to 3650.
- Minimum magnitude (`min_magnitude`, number): Only events at or above this magnitude. This is the filter that decides how much noise a workflow sees: the catalog records tens of thousands of events a month, almost all of them too small to feel. 2.5 is roughly where people start noticing, 4.5 is the global reporting threshold, and 6 is where damage becomes likely.
- Maximum magnitude (`max_magnitude`, number): Only events at or below this magnitude.
- Minimum depth (km) (`min_depth_km`, number): Only events at or below this depth, in kilometres. The catalog allows -100 to 1000; a negative depth is an event above sea level, which is normal in mountainous regions. From -100.0 to 1000.0.
- Maximum depth (km) (`max_depth_km`, number): Only events at or above this depth, in kilometres. Shallow events shake the surface far harder than deep ones of the same magnitude, so a filter of 70 km or less is a rough stand-in for 'the ones people felt'. From -100.0 to 1000.0.
- Latitude (`latitude`, number): The centre of a circle to search, in degrees from -90 to 90. Needs a longitude and a radius with it: given only part of a circle the catalog ignores the whole thing and returns events from everywhere, so a partial one is refused here instead. From -90 to 90.
- Longitude (`longitude`, number): The centre of a circle to search, in degrees from -180 to 180. Needs a latitude and a radius with it. From -180 to 180.
- Radius (km) (`radius_km`, number): How far around the centre to look, in kilometres, up to 20,001.6 - which is half the Earth's circumference, and so the whole planet. From 0 to 20001.6.
- South edge (latitude) (`min_latitude`, number): The southern edge of a rectangle to search, -90 to 90. The four edges are independent: set only the two you care about to search a band of latitude or longitude. From -90 to 90.
- North edge (latitude) (`max_latitude`, number): The northern edge of a rectangle to search, -90 to 90. From -90 to 90.
- West edge (longitude) (`min_longitude`, number): The western edge of a rectangle to search. Normally -180 to 180, but the catalog lets a box cross the date line by going outside that: 170 to 190 is a real search over the western Pacific. From -360 to 360.
- East edge (longitude) (`max_longitude`, number): The eastern edge of a rectangle to search, -360 to 360. From -360 to 360.
- Event type (`event_type`, text): Only events of this type. The catalog is not only earthquakes: it also records quarry blasts, explosions, mine collapses, sonic booms and ice quakes, and a search that names no type returns all of them. Choose 'earthquake' to leave the rest out.
- Minimum PAGER alert level (`min_alert_level`, text): Only events with a PAGER alert of at least this level, weakest first: green, yellow, orange, red. Worth knowing that this is really a 'has been assessed' filter - the USGS runs a PAGER loss assessment only on the events big enough to warrant one, so most events carry no alert at all and setting this to green still leaves out the great majority of them. One of: `green`, `yellow`, `orange`, `red`.
- Minimum felt reports (`min_felt_reports`, number): Only events with at least this many 'Did You Feel It?' responses from the public. Like the alert level, this only ever matches events somebody reported, which is a small share of them - but it is the best single filter for 'an event people noticed' regardless of how big it measured. At least 1.
- Minimum significance (`min_significance`, number): Only events at or above this significance score. The catalog computes it from magnitude, felt reports and estimated impact together, so it ranks a moderate earthquake under a city above a large one in the deep ocean. Roughly: 600 and above is what makes the news, 1000 is a major disaster. At least 0.
- Review status (`review_status`, text): Whether to include events a seismologist has not checked yet. Automatic solutions appear within minutes and are sometimes revised or withdrawn; reviewed ones are slower and settled. Defaults to all of them. One of: `all`, `automatic`, `reviewed`. Default: `all`.
- Catalog (`catalog`, text): Only events from this catalog. Leave empty - the default - to get the most preferred information about each event from whichever catalog holds it, which is what almost every workflow wants.
- Contributor (`contributor`, text): Only events contributed by this network - 'ak' for Alaska, 'ci' for southern California, 'us' for the USGS national operation. Each event names its own in 'network'.
- Has product (`product_type`, text): Only events that have this kind of product attached - a 'shakemap' for modelled shaking, 'dyfi' for public reports, 'losspager' for a casualty and loss estimate, 'moment-tensor' for the fault solution. A product is only generated when an event warrants it, so this doubles as a filter for the events the USGS itself treated as significant.

**Outputs**

- `count` (number)
- `end_time` (text)
- `exceeds_max_returnable` (true/false)
- `latitude` (number)
- `longitude` (number)
- `max_returnable` (number)
- `min_magnitude` (number)
- `radius_km` (number)
- `start_time` (text)

**Example output**

```json
{
  "count": 431,
  "end_time": null,
  "exceeds_max_returnable": false,
  "latitude": null,
  "longitude": null,
  "max_returnable": 20000,
  "min_magnitude": 4.5,
  "radius_km": null,
  "start_time": "2026-07-29T00:00:00Z"
}
```

### Find earthquakes near a place

Find the earthquakes within a radius of a point - a site, an office, a customer's address - nearest first, each with how far away it was in kilometres and miles and which direction it lay. That distance is the thing a radius search leaves out: the catalog returns the events inside the circle but never says how far away any of them was, so it is worked out here. Defaults to a 100 km radius over the last 30 days.

**Inputs**

- Latitude (`latitude`, number, required): The centre of the search, in degrees from -90 to 90. From -90 to 90.
- Longitude (`longitude`, number, required): The centre of the search, in degrees from -180 to 180. From -180 to 180.
- Radius (km) (`radius_km`, number): How far around the point to look, in kilometres. Defaults to 100. From 0 to 20001.6.
- Start time (`start_time`, date and time): Only events at or after this moment. Leave it and 'Days back' empty to use this action's own default window. Times are UTC unless the value says otherwise.
- End time (`end_time`, date and time): Only events at or before this moment. Leave it empty to search up to now, which is what a scheduled run almost always wants: the catalog decides what 'now' is, so an event that arrives while the step runs is still included.
- Days back (`days_back`, number): Look this many days back instead of naming a start date - what a workflow that runs every morning needs, since 'the last 7 days' cannot be written as a fixed date. Counted back from now, or from 'End time' if you set one. Give this or 'Start time', not both. From 1 to 3650.
- Minimum magnitude (`min_magnitude`, number): Only events at or above this magnitude. This is the filter that decides how much noise a workflow sees: the catalog records tens of thousands of events a month, almost all of them too small to feel. 2.5 is roughly where people start noticing, 4.5 is the global reporting threshold, and 6 is where damage becomes likely.
- Maximum depth (km) (`max_depth_km`, number): Only events at or above this depth, in kilometres. Shallow events shake the surface far harder than deep ones of the same magnitude, so a filter of 70 km or less is a rough stand-in for 'the ones people felt'. From -100.0 to 1000.0.
- Event type (`event_type`, text): Only events of this type. The catalog is not only earthquakes: it also records quarry blasts, explosions, mine collapses, sonic booms and ice quakes, and a search that names no type returns all of them. Choose 'earthquake' to leave the rest out.
- Order by (`order_by`, text): How to order the events. Defaults to nearest first, which is what this action computes and the catalog cannot do itself. One of: `distance` (Nearest first), `time` (Newest first), `time-asc` (Oldest first), `magnitude` (Largest first), `magnitude-asc` (Smallest first). Default: `distance`.
- Number of events (`limit`, number): How many events to return, from 1 to 1,000. Defaults to 20. A much larger block is read and ordered before this trims it, and 'complete' says whether that block held every match - so 'the nearest' is never quietly the nearest of a subset. From 1 to 1000.

**Outputs**

- `complete` (true/false)
- `earthquake_count` (number)
- `earthquakes` (list)
- `end_time` (text)
- `latitude` (number)
- `limit` (number)
- `longitude` (number)
- `min_magnitude` (number)
- `nearest_km` (number)
- `order_by` (text)
- `radius_km` (number)
- `scanned_count` (number)
- `start_time` (text)

**Example output**

```json
{
  "complete": true,
  "earthquake_count": 1,
  "earthquakes": [
    {
      "alert": null,
      "azimuthal_gap": 68.0,
      "cdi": 2.7,
      "code": "75009182",
      "depth_km": 2.1,
      "detail_url": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=nc75009182&format=geojson",
      "direction": "NNW",
      "distance_km": 121.28,
      "distance_miles": 75.36,
      "event_type": "earthquake",
      "felt_reports": 3,
      "id": "nc75009182",
      "ids": [
        "nc75009182"
      ],
      "latitude": 38.8218,
      "longitude": -122.8092,
      "magnitude": 3.2,
      "magnitude_type": "md",
      "min_station_distance_deg": 0.014,
      "mmi": null,
      "network": "nc",
      "place": "7 km NW of The Geysers, CA",
      "product_types": [
        "dyfi",
        "origin",
        "phase-data"
      ],
      "region": "CA",
      "rms": 0.03,
      "significance": 158,
      "sources": [
        "nc"
      ],
      "station_count": 24,
      "status": "automatic",
      "time": "2026-08-28T02:41:09Z",
      "time_epoch_ms": 1787884869000,
      "title": "M 3.2 - 7 km NW of The Geysers, CA",
      "tsunami": false,
      "updated": "2026-08-28T02:55:31Z",
      "updated_epoch_ms": 1787885731000,
      "url": "https://earthquake.usgs.gov/earthquakes/eventpage/nc75009182"
    }
  ],
  "end_time": null,
  "latitude": 37.7749,
  "limit": 20,
  "longitude": -122.4194,
  "min_magnitude": null,
  "nearest_km": 121.28,
  "order_by": "distance",
  "radius_km": 250.0,
  "scanned_count": 1,
  "start_time": "2026-07-29T00:00:00Z"
}
```

### Get an earthquake by ID

Look one earthquake up by its USGS event id, for re-reading an event an earlier step found or a colleague linked to. A full event-page link is accepted in place of the bare id. Asking for a single event makes the catalog return every origin and magnitude solution it holds rather than only the preferred one, so this is also the fuller record.

**Inputs**

- Event ID (`event_id`, text, required): The event's id, or the full USGS event-page link to it. Usually this comes from an earlier step rather than being typed: every action here returns the id of each event it hands back, and Get recent earthquakes or Search earthquakes is the normal way to get one. An id is a short code the reporting network assigns, such as 'nc75123456'.

**Outputs**

- `earthquake` (object)
- `event_id` (text)

**Example output**

```json
{
  "earthquake": {
    "alert": "green",
    "azimuthal_gap": 34.0,
    "cdi": 4.6,
    "code": "7000p4kq",
    "depth_km": 28.5,
    "detail_url": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us7000p4kq&format=geojson",
    "event_type": "earthquake",
    "felt_reports": 41,
    "id": "us7000p4kq",
    "ids": [
      "us7000p4kq",
      "at00sxk2p1"
    ],
    "latitude": 54.4712,
    "longitude": -160.7268,
    "magnitude": 6.1,
    "magnitude_type": "mww",
    "min_station_distance_deg": 0.918,
    "mmi": 5.2,
    "network": "us",
    "place": "95 km SSW of Sand Point, Alaska",
    "product_types": [
      "dyfi",
      "losspager",
      "origin",
      "phase-data",
      "shakemap"
    ],
    "region": "Alaska",
    "rms": 0.87,
    "significance": 572,
    "sources": [
      "us",
      "at"
    ],
    "station_count": 132,
    "status": "reviewed",
    "time": "2026-08-27T09:14:52Z",
    "time_epoch_ms": 1787822092000,
    "title": "M 6.1 - 95 km SSW of Sand Point, Alaska",
    "tsunami": true,
    "updated": "2026-08-27T11:02:10Z",
    "updated_epoch_ms": 1787828530000,
    "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000p4kq"
  },
  "event_id": "us7000p4kq"
}
```

### Get recent earthquakes

Get the earthquakes from the last hour, day, week or month from the USGS real-time feeds - the route the USGS asks automated applications to use for recent activity, because the feeds are pre-rendered and cached rather than searched on demand. Use this for anything on a schedule. Optionally keep only the events above a magnitude, or within a radius of a place, both of which are applied to the feed here at no extra cost.

**Inputs**

- Feed (`magnitude_tier`, text): Which feed to read. The USGS publishes one per magnitude floor: 'significant' is the handful it has judged newsworthy, then 4.5+, 2.5+, 1.0+, and 'all', which is every event it recorded and can run to tens of thousands in a month. Defaults to 2.5, roughly where people start feeling them. One of: `significant` (Significant events only), `4.5` (Magnitude 4.5+), `2.5` (Magnitude 2.5+), `1.0` (Magnitude 1.0+), `all` (All recorded events). Default: `2.5`.
- Period (`period`, text): How far back the feed covers. Match it to how often the workflow runs, with room to spare: an hourly schedule reading the past-day feed never misses an event because one run was late. One of: `hour` (Past hour), `day` (Past day), `week` (Past 7 days), `month` (Past 30 days). Default: `day`.
- Minimum magnitude (`min_magnitude`, number): Keep only events at or above this magnitude. Applied to the feed after it arrives, so it can be any value rather than one of the feed's own floors - read the 2.5+ feed and filter to 3.7 if that is your threshold.
- Latitude (`latitude`, number): The centre of a circle to search, in degrees from -90 to 90. Needs a longitude and a radius with it: given only part of a circle the catalog ignores the whole thing and returns events from everywhere, so a partial one is refused here instead. From -90 to 90.
- Longitude (`longitude`, number): The centre of a circle to search, in degrees from -180 to 180. Needs a latitude and a radius with it. From -180 to 180.
- Radius (km) (`radius_km`, number): Keep only events within this many kilometres of the latitude and longitude. Every event kept comes back with its distance and compass direction from that point. Applied here rather than by the service, so a geo-fenced watch still costs one cached request. At least 0.
- Order by (`order_by`, text): How to order the events. Defaults to newest first. The feeds carry no ordering of their own, so this is applied here. One of: `time` (Newest first), `time-asc` (Oldest first), `magnitude` (Largest first), `magnitude-asc` (Smallest first). Default: `time`.
- Number of events (`limit`, number): How many events to return, after the filters and the ordering. Defaults to 50. 'total_in_feed' always reports what the feed held before any of it, so a short result is never a mystery. From 1 to 20000.

**Outputs**

- `earthquake_count` (number)
- `earthquakes` (list)
- `feed` (object)
- `latitude` (number)
- `longitude` (number)
- `magnitude_tier` (text)
- `min_magnitude` (number)
- `order_by` (text)
- `period` (text)
- `radius_km` (number)
- `total_in_feed` (number)

**Example output**

```json
{
  "earthquake_count": 2,
  "earthquakes": [
    {
      "alert": null,
      "azimuthal_gap": 68.0,
      "cdi": 2.7,
      "code": "75009182",
      "depth_km": 2.1,
      "detail_url": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=nc75009182&format=geojson",
      "event_type": "earthquake",
      "felt_reports": 3,
      "id": "nc75009182",
      "ids": [
        "nc75009182"
      ],
      "latitude": 38.8218,
      "longitude": -122.8092,
      "magnitude": 3.2,
      "magnitude_type": "md",
      "min_station_distance_deg": 0.014,
      "mmi": null,
      "network": "nc",
      "place": "7 km NW of The Geysers, CA",
      "product_types": [
        "dyfi",
        "origin",
        "phase-data"
      ],
      "region": "CA",
      "rms": 0.03,
      "significance": 158,
      "sources": [
        "nc"
      ],
      "station_count": 24,
      "status": "automatic",
      "time": "2026-08-28T02:41:09Z",
      "time_epoch_ms": 1787884869000,
      "title": "M 3.2 - 7 km NW of The Geysers, CA",
      "tsunami": false,
      "updated": "2026-08-28T02:55:31Z",
      "updated_epoch_ms": 1787885731000,
      "url": "https://earthquake.usgs.gov/earthquakes/eventpage/nc75009182"
    },
    {
      "alert": "green",
      "azimuthal_gap": 34.0,
      "cdi": 4.6,
      "code": "7000p4kq",
      "depth_km": 28.5,
      "detail_url": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us7000p4kq&format=geojson",
      "event_type": "earthquake",
      "felt_reports": 41,
      "id": "us7000p4kq",
      "ids": [
        "us7000p4kq",
        "at00sxk2p1"
      ],
      "latitude": 54.4712,
      "longitude": -160.7268,
      "magnitude": 6.1,
      "magnitude_type": "mww",
      "min_station_distance_deg": 0.918,
      "mmi": 5.2,
      "network": "us",
      "place": "95 km SSW of Sand Point, Alaska",
      "product_types": [
        "dyfi",
        "losspager",
        "origin",
        "phase-data",
        "shakemap"
      ],
      "region": "Alaska",
      "rms": 0.87,
      "significance": 572,
      "sources": [
        "us",
        "at"
      ],
      "station_count": 132,
      "status": "reviewed",
      "time": "2026-08-27T09:14:52Z",
      "time_epoch_ms": 1787822092000,
      "title": "M 6.1 - 95 km SSW of Sand Point, Alaska",
      "tsunami": true,
      "updated": "2026-08-27T11:02:10Z",
      "updated_epoch_ms": 1787828530000,
      "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000p4kq"
    }
  ],
  "feed": {
    "api_version": "2.7.0",
    "generated": "2026-08-28T03:10:00Z",
    "title": "USGS Magnitude 2.5+ Earthquakes, Past Day",
    "url": "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.geojson"
  },
  "latitude": null,
  "longitude": null,
  "magnitude_tier": "2.5",
  "min_magnitude": null,
  "order_by": "time",
  "period": "day",
  "radius_km": null,
  "total_in_feed": 2
}
```

### Get the largest earthquake

Find the single biggest earthquake in a window, optionally within a region - the one line a weekly digest or a morning briefing wants. A quiet window is reported as 'found: false' with a message rather than as a failure, so a scheduled post can say 'nothing above M4 this week' instead of the step dying on the weeks when that is the news. Defaults to the last 7 days.

**Inputs**

- Start time (`start_time`, date and time): Only events at or after this moment. Leave it and 'Days back' empty to use this action's own default window. Times are UTC unless the value says otherwise.
- End time (`end_time`, date and time): Only events at or before this moment. Leave it empty to search up to now, which is what a scheduled run almost always wants: the catalog decides what 'now' is, so an event that arrives while the step runs is still included.
- Days back (`days_back`, number): Look this many days back instead of naming a start date - what a workflow that runs every morning needs, since 'the last 7 days' cannot be written as a fixed date. Counted back from now, or from 'End time' if you set one. Give this or 'Start time', not both. From 1 to 3650.
- Minimum magnitude (`min_magnitude`, number): Only events at or above this magnitude. This is the filter that decides how much noise a workflow sees: the catalog records tens of thousands of events a month, almost all of them too small to feel. 2.5 is roughly where people start noticing, 4.5 is the global reporting threshold, and 6 is where damage becomes likely.
- Latitude (`latitude`, number): The centre of a circle to search, in degrees from -90 to 90. Needs a longitude and a radius with it: given only part of a circle the catalog ignores the whole thing and returns events from everywhere, so a partial one is refused here instead. From -90 to 90.
- Longitude (`longitude`, number): The centre of a circle to search, in degrees from -180 to 180. Needs a latitude and a radius with it. From -180 to 180.
- Radius (km) (`radius_km`, number): How far around the centre to look, in kilometres, up to 20,001.6 - which is half the Earth's circumference, and so the whole planet. From 0 to 20001.6.
- South edge (latitude) (`min_latitude`, number): The southern edge of a rectangle to search, -90 to 90. The four edges are independent: set only the two you care about to search a band of latitude or longitude. From -90 to 90.
- North edge (latitude) (`max_latitude`, number): The northern edge of a rectangle to search, -90 to 90. From -90 to 90.
- West edge (longitude) (`min_longitude`, number): The western edge of a rectangle to search. Normally -180 to 180, but the catalog lets a box cross the date line by going outside that: 170 to 190 is a real search over the western Pacific. From -360 to 360.
- East edge (longitude) (`max_longitude`, number): The eastern edge of a rectangle to search, -360 to 360. From -360 to 360.
- Event type (`event_type`, text): Only events of this type. The catalog is not only earthquakes: it also records quarry blasts, explosions, mine collapses, sonic booms and ice quakes, and a search that names no type returns all of them. Choose 'earthquake' to leave the rest out.

**Outputs**

- `earthquake` (object)
- `end_time` (text)
- `found` (true/false)
- `latitude` (number)
- `longitude` (number)
- `message` (text)
- `min_magnitude` (number)
- `radius_km` (number)
- `start_time` (text)

**Example output**

```json
{
  "earthquake": {
    "alert": "green",
    "azimuthal_gap": 34.0,
    "cdi": 4.6,
    "code": "7000p4kq",
    "depth_km": 28.5,
    "detail_url": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us7000p4kq&format=geojson",
    "event_type": "earthquake",
    "felt_reports": 41,
    "id": "us7000p4kq",
    "ids": [
      "us7000p4kq",
      "at00sxk2p1"
    ],
    "latitude": 54.4712,
    "longitude": -160.7268,
    "magnitude": 6.1,
    "magnitude_type": "mww",
    "min_station_distance_deg": 0.918,
    "mmi": 5.2,
    "network": "us",
    "place": "95 km SSW of Sand Point, Alaska",
    "product_types": [
      "dyfi",
      "losspager",
      "origin",
      "phase-data",
      "shakemap"
    ],
    "region": "Alaska",
    "rms": 0.87,
    "significance": 572,
    "sources": [
      "us",
      "at"
    ],
    "station_count": 132,
    "status": "reviewed",
    "time": "2026-08-27T09:14:52Z",
    "time_epoch_ms": 1787822092000,
    "title": "M 6.1 - 95 km SSW of Sand Point, Alaska",
    "tsunami": true,
    "updated": "2026-08-27T11:02:10Z",
    "updated_epoch_ms": 1787828530000,
    "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000p4kq"
  },
  "end_time": null,
  "found": true,
  "latitude": null,
  "longitude": null,
  "message": "Largest: M 6.1 - 95 km SSW of Sand Point, Alaska at 2026-08-27T09:14:52Z",
  "min_magnitude": null,
  "radius_km": null,
  "start_time": "2026-08-21T00:00:00Z"
}
```

### List catalogs

List the catalogs a search can be limited to. A catalog is one authoritative collection of events - the ANSS Comprehensive Catalog, a regional network's own, a specific study. Naming none, which is the default everywhere here, gets the most preferred information about each event from whichever catalog holds it.

**Inputs**: None.

**Outputs**

- `catalog_count` (number)
- `catalogs` (list)

**Example output**

```json
{
  "catalog_count": 8,
  "catalogs": [
    "ak",
    "ci",
    "nc",
    "nn",
    "pr",
    "us",
    "uu",
    "uw"
  ]
}
```

### List contributors

List the seismic networks that contribute events - 'ak' for Alaska, 'ci' for southern California, 'us' for the USGS national operation. Every event names its own in 'network', so this is the list to choose from when filtering a search by one, or to resolve a code an event came back with.

**Inputs**: None.

**Outputs**

- `contributor_count` (number)
- `contributors` (list)

**Example output**

```json
{
  "contributor_count": 8,
  "contributors": [
    "ak",
    "at",
    "ci",
    "nc",
    "nn",
    "pr",
    "us",
    "uu"
  ]
}
```

### List event and product types

List the event types, magnitude types and product types the catalog uses, in one call. Worth running once while building: the catalog is not only earthquakes - it records quarry blasts, explosions, mine collapses, sonic booms and ice quakes too, and a search that names no event type returns all of them.

**Inputs**: None.

**Outputs**

- `event_type_count` (number)
- `event_types` (list)
- `magnitude_types` (list)
- `product_types` (list)

**Example output**

```json
{
  "event_type_count": 5,
  "event_types": [
    "earthquake",
    "explosion",
    "ice quake",
    "mining explosion",
    "quarry blast"
  ],
  "magnitude_types": [
    "mb",
    "md",
    "ml",
    "ms",
    "mw",
    "mwb",
    "mww"
  ],
  "product_types": [
    "dyfi",
    "focal-mechanism",
    "losspager",
    "moment-tensor",
    "origin",
    "shakemap"
  ]
}
```

### Search earthquakes

Search the full USGS catalog - every earthquake back to 1900 and beyond - by time, magnitude, depth, place, alert level, felt reports and more. This is the action for a specific question about a window or a region; for watching for new activity on a schedule, use Get recent earthquakes, which the USGS asks automated applications to use instead. With nothing filled in it returns the last 30 days, and the window it actually used is always reported back.

**Inputs**

- Start time (`start_time`, date and time): Only events at or after this moment. Leave it and 'Days back' empty to use this action's own default window. Times are UTC unless the value says otherwise.
- End time (`end_time`, date and time): Only events at or before this moment. Leave it empty to search up to now, which is what a scheduled run almost always wants: the catalog decides what 'now' is, so an event that arrives while the step runs is still included.
- Days back (`days_back`, number): Look this many days back instead of naming a start date - what a workflow that runs every morning needs, since 'the last 7 days' cannot be written as a fixed date. Counted back from now, or from 'End time' if you set one. Give this or 'Start time', not both. From 1 to 3650.
- Minimum magnitude (`min_magnitude`, number): Only events at or above this magnitude. This is the filter that decides how much noise a workflow sees: the catalog records tens of thousands of events a month, almost all of them too small to feel. 2.5 is roughly where people start noticing, 4.5 is the global reporting threshold, and 6 is where damage becomes likely.
- Maximum magnitude (`max_magnitude`, number): Only events at or below this magnitude.
- Minimum depth (km) (`min_depth_km`, number): Only events at or below this depth, in kilometres. The catalog allows -100 to 1000; a negative depth is an event above sea level, which is normal in mountainous regions. From -100.0 to 1000.0.
- Maximum depth (km) (`max_depth_km`, number): Only events at or above this depth, in kilometres. Shallow events shake the surface far harder than deep ones of the same magnitude, so a filter of 70 km or less is a rough stand-in for 'the ones people felt'. From -100.0 to 1000.0.
- Latitude (`latitude`, number): The centre of a circle to search, in degrees from -90 to 90. Needs a longitude and a radius with it: given only part of a circle the catalog ignores the whole thing and returns events from everywhere, so a partial one is refused here instead. From -90 to 90.
- Longitude (`longitude`, number): The centre of a circle to search, in degrees from -180 to 180. Needs a latitude and a radius with it. From -180 to 180.
- Radius (km) (`radius_km`, number): How far around the centre to look, in kilometres, up to 20,001.6 - which is half the Earth's circumference, and so the whole planet. From 0 to 20001.6.
- South edge (latitude) (`min_latitude`, number): The southern edge of a rectangle to search, -90 to 90. The four edges are independent: set only the two you care about to search a band of latitude or longitude. From -90 to 90.
- North edge (latitude) (`max_latitude`, number): The northern edge of a rectangle to search, -90 to 90. From -90 to 90.
- West edge (longitude) (`min_longitude`, number): The western edge of a rectangle to search. Normally -180 to 180, but the catalog lets a box cross the date line by going outside that: 170 to 190 is a real search over the western Pacific. From -360 to 360.
- East edge (longitude) (`max_longitude`, number): The eastern edge of a rectangle to search, -360 to 360. From -360 to 360.
- Event type (`event_type`, text): Only events of this type. The catalog is not only earthquakes: it also records quarry blasts, explosions, mine collapses, sonic booms and ice quakes, and a search that names no type returns all of them. Choose 'earthquake' to leave the rest out.
- Minimum PAGER alert level (`min_alert_level`, text): Only events with a PAGER alert of at least this level, weakest first: green, yellow, orange, red. Worth knowing that this is really a 'has been assessed' filter - the USGS runs a PAGER loss assessment only on the events big enough to warrant one, so most events carry no alert at all and setting this to green still leaves out the great majority of them. One of: `green`, `yellow`, `orange`, `red`.
- Minimum felt reports (`min_felt_reports`, number): Only events with at least this many 'Did You Feel It?' responses from the public. Like the alert level, this only ever matches events somebody reported, which is a small share of them - but it is the best single filter for 'an event people noticed' regardless of how big it measured. At least 1.
- Minimum significance (`min_significance`, number): Only events at or above this significance score. The catalog computes it from magnitude, felt reports and estimated impact together, so it ranks a moderate earthquake under a city above a large one in the deep ocean. Roughly: 600 and above is what makes the news, 1000 is a major disaster. At least 0.
- Review status (`review_status`, text): Whether to include events a seismologist has not checked yet. Automatic solutions appear within minutes and are sometimes revised or withdrawn; reviewed ones are slower and settled. Defaults to all of them. One of: `all`, `automatic`, `reviewed`. Default: `all`.
- Catalog (`catalog`, text): Only events from this catalog. Leave empty - the default - to get the most preferred information about each event from whichever catalog holds it, which is what almost every workflow wants.
- Contributor (`contributor`, text): Only events contributed by this network - 'ak' for Alaska, 'ci' for southern California, 'us' for the USGS national operation. Each event names its own in 'network'.
- Has product (`product_type`, text): Only events that have this kind of product attached - a 'shakemap' for modelled shaking, 'dyfi' for public reports, 'losspager' for a casualty and loss estimate, 'moment-tensor' for the fault solution. A product is only generated when an event warrants it, so this doubles as a filter for the events the USGS itself treated as significant.
- Updated after (`updated_after`, date and time): Only events whose record changed after this moment, whenever the earthquake itself happened. This is how a workflow keeps a copy in step: a solution revised days later shows up here even though its time has not moved.
- Order by (`order_by`, text): How the catalog should order the results. One of: `time` (Newest first), `time-asc` (Oldest first), `magnitude` (Largest first), `magnitude-asc` (Smallest first). Default: `time`.
- Number of events (`limit`, number): How many events to return, from 1 to 20,000. Defaults to 50. The catalog rejects a search whose result would run past 20,000 rather than trimming it, so run Count earthquakes first if a window might be that busy. From 1 to 20000.
- Start at event number (`offset`, number): Skip to this position in the results, counting from 1, to page through a search bigger than one call. Pair it with the same ordering every time, or two pages can overlap. At least 1.

**Outputs**

- `earthquake_count` (number)
- `earthquakes` (list)
- `end_time` (text)
- `latitude` (number)
- `limit` (number)
- `longitude` (number)
- `min_magnitude` (number)
- `more_available` (true/false)
- `offset` (number)
- `order_by` (text)
- `radius_km` (number)
- `start_time` (text)

**Example output**

```json
{
  "earthquake_count": 1,
  "earthquakes": [
    {
      "alert": "green",
      "azimuthal_gap": 34.0,
      "cdi": 4.6,
      "code": "7000p4kq",
      "depth_km": 28.5,
      "detail_url": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us7000p4kq&format=geojson",
      "event_type": "earthquake",
      "felt_reports": 41,
      "id": "us7000p4kq",
      "ids": [
        "us7000p4kq",
        "at00sxk2p1"
      ],
      "latitude": 54.4712,
      "longitude": -160.7268,
      "magnitude": 6.1,
      "magnitude_type": "mww",
      "min_station_distance_deg": 0.918,
      "mmi": 5.2,
      "network": "us",
      "place": "95 km SSW of Sand Point, Alaska",
      "product_types": [
        "dyfi",
        "losspager",
        "origin",
        "phase-data",
        "shakemap"
      ],
      "region": "Alaska",
      "rms": 0.87,
      "significance": 572,
      "sources": [
        "us",
        "at"
      ],
      "station_count": 132,
      "status": "reviewed",
      "time": "2026-08-27T09:14:52Z",
      "time_epoch_ms": 1787822092000,
      "title": "M 6.1 - 95 km SSW of Sand Point, Alaska",
      "tsunami": true,
      "updated": "2026-08-27T11:02:10Z",
      "updated_epoch_ms": 1787828530000,
      "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000p4kq"
    }
  ],
  "end_time": null,
  "latitude": null,
  "limit": 50,
  "longitude": null,
  "min_magnitude": 4.5,
  "more_available": false,
  "offset": 1,
  "order_by": "time",
  "radius_km": null,
  "start_time": "2026-07-29T00:00:00Z"
}
```

### Summarize earthquake activity

Summarise a window's seismic activity for a digest: how many events, how they split across the magnitude bands, the largest and the most significant, how many people felt, how many carried a tsunami flag, and the regions with the most activity. The total is exact however busy the window; the rest is computed over the events read, and 'complete' says whether those are the same set. Defaults to the last 7 days.

**Inputs**

- Start time (`start_time`, date and time): Only events at or after this moment. Leave it and 'Days back' empty to use this action's own default window. Times are UTC unless the value says otherwise.
- End time (`end_time`, date and time): Only events at or before this moment. Leave it empty to search up to now, which is what a scheduled run almost always wants: the catalog decides what 'now' is, so an event that arrives while the step runs is still included.
- Days back (`days_back`, number): Look this many days back instead of naming a start date - what a workflow that runs every morning needs, since 'the last 7 days' cannot be written as a fixed date. Counted back from now, or from 'End time' if you set one. Give this or 'Start time', not both. From 1 to 3650.
- Minimum magnitude (`min_magnitude`, number): Only events at or above this magnitude. This is the filter that decides how much noise a workflow sees: the catalog records tens of thousands of events a month, almost all of them too small to feel. 2.5 is roughly where people start noticing, 4.5 is the global reporting threshold, and 6 is where damage becomes likely.
- Latitude (`latitude`, number): The centre of a circle to search, in degrees from -90 to 90. Needs a longitude and a radius with it: given only part of a circle the catalog ignores the whole thing and returns events from everywhere, so a partial one is refused here instead. From -90 to 90.
- Longitude (`longitude`, number): The centre of a circle to search, in degrees from -180 to 180. Needs a latitude and a radius with it. From -180 to 180.
- Radius (km) (`radius_km`, number): How far around the centre to look, in kilometres, up to 20,001.6 - which is half the Earth's circumference, and so the whole planet. From 0 to 20001.6.
- South edge (latitude) (`min_latitude`, number): The southern edge of a rectangle to search, -90 to 90. The four edges are independent: set only the two you care about to search a band of latitude or longitude. From -90 to 90.
- North edge (latitude) (`max_latitude`, number): The northern edge of a rectangle to search, -90 to 90. From -90 to 90.
- West edge (longitude) (`min_longitude`, number): The western edge of a rectangle to search. Normally -180 to 180, but the catalog lets a box cross the date line by going outside that: 170 to 190 is a real search over the western Pacific. From -360 to 360.
- East edge (longitude) (`max_longitude`, number): The eastern edge of a rectangle to search, -360 to 360. From -360 to 360.
- Event type (`event_type`, text): Only events of this type. The catalog is not only earthquakes: it also records quarry blasts, explosions, mine collapses, sonic booms and ice quakes, and a search that names no type returns all of them. Choose 'earthquake' to leave the rest out.
- Events to analyze (`sample_limit`, number): How many events to read for the figures, from 1 to 20,000. Defaults to 1,000, which covers a normal week above magnitude 2.5 several times over. Raise it for a wider window or a lower magnitude floor; the total is counted separately and stays exact either way. From 1 to 20000.

**Outputs**

- `alert_counts` (object)
- `analyzed_count` (number)
- `average_magnitude` (number)
- `complete` (true/false)
- `deepest_km` (number)
- `end_time` (text)
- `felt_count` (number)
- `largest` (object)
- `latitude` (number)
- `longitude` (number)
- `magnitude_bands` (object)
- `max_magnitude` (number)
- `min_magnitude` (number)
- `min_magnitude_seen` (number)
- `most_significant` (object)
- `radius_km` (number)
- `shallowest_km` (number)
- `start_time` (text)
- `top_regions` (list)
- `total` (number)
- `tsunami_count` (number)

**Example output**

```json
{
  "alert_counts": {
    "green": 1,
    "none": 1,
    "orange": 0,
    "red": 0,
    "yellow": 0
  },
  "analyzed_count": 2,
  "average_magnitude": 4.65,
  "complete": true,
  "deepest_km": 28.5,
  "end_time": null,
  "felt_count": 2,
  "largest": {
    "alert": "green",
    "azimuthal_gap": 34.0,
    "cdi": 4.6,
    "code": "7000p4kq",
    "depth_km": 28.5,
    "detail_url": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us7000p4kq&format=geojson",
    "event_type": "earthquake",
    "felt_reports": 41,
    "id": "us7000p4kq",
    "ids": [
      "us7000p4kq",
      "at00sxk2p1"
    ],
    "latitude": 54.4712,
    "longitude": -160.7268,
    "magnitude": 6.1,
    "magnitude_type": "mww",
    "min_station_distance_deg": 0.918,
    "mmi": 5.2,
    "network": "us",
    "place": "95 km SSW of Sand Point, Alaska",
    "product_types": [
      "dyfi",
      "losspager",
      "origin",
      "phase-data",
      "shakemap"
    ],
    "region": "Alaska",
    "rms": 0.87,
    "significance": 572,
    "sources": [
      "us",
      "at"
    ],
    "station_count": 132,
    "status": "reviewed",
    "time": "2026-08-27T09:14:52Z",
    "time_epoch_ms": 1787822092000,
    "title": "M 6.1 - 95 km SSW of Sand Point, Alaska",
    "tsunami": true,
    "updated": "2026-08-27T11:02:10Z",
    "updated_epoch_ms": 1787828530000,
    "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000p4kq"
  },
  "latitude": null,
  "longitude": null,
  "magnitude_bands": {
    "m2_to_3": 0,
    "m3_to_4": 1,
    "m4_to_5": 0,
    "m5_to_6": 0,
    "m6_to_7": 1,
    "m7_plus": 0,
    "under_2": 0,
    "unknown": 0
  },
  "max_magnitude": 6.1,
  "min_magnitude": 2.5,
  "min_magnitude_seen": 3.2,
  "most_significant": {
    "alert": "green",
    "azimuthal_gap": 34.0,
    "cdi": 4.6,
    "code": "7000p4kq",
    "depth_km": 28.5,
    "detail_url": "https://earthquake.usgs.gov/fdsnws/event/1/query?eventid=us7000p4kq&format=geojson",
    "event_type": "earthquake",
    "felt_reports": 41,
    "id": "us7000p4kq",
    "ids": [
      "us7000p4kq",
      "at00sxk2p1"
    ],
    "latitude": 54.4712,
    "longitude": -160.7268,
    "magnitude": 6.1,
    "magnitude_type": "mww",
    "min_station_distance_deg": 0.918,
    "mmi": 5.2,
    "network": "us",
    "place": "95 km SSW of Sand Point, Alaska",
    "product_types": [
      "dyfi",
      "losspager",
      "origin",
      "phase-data",
      "shakemap"
    ],
    "region": "Alaska",
    "rms": 0.87,
    "significance": 572,
    "sources": [
      "us",
      "at"
    ],
    "station_count": 132,
    "status": "reviewed",
    "time": "2026-08-27T09:14:52Z",
    "time_epoch_ms": 1787822092000,
    "title": "M 6.1 - 95 km SSW of Sand Point, Alaska",
    "tsunami": true,
    "updated": "2026-08-27T11:02:10Z",
    "updated_epoch_ms": 1787828530000,
    "url": "https://earthquake.usgs.gov/earthquakes/eventpage/us7000p4kq"
  },
  "radius_km": null,
  "shallowest_km": 2.1,
  "start_time": "2026-08-21T00:00:00Z",
  "top_regions": [
    {
      "count": 1,
      "region": "Alaska"
    },
    {
      "count": 1,
      "region": "CA"
    }
  ],
  "total": 2,
  "tsunami_count": 1
}
```