# `usgs_quake__earthquake_get_feed`

**Get USGS Earthquake Feed**

Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time window. These feeds are CDN-cached by USGS and faster and more available than the query API — use them for "what's happening now" queries. "all" includes microseisms (M\<1); "significant" is a USGS curation based on magnitude, felt reports, and PAGER impact estimates. "hour" returns 0–10 events typically; "month" can exceed 10,000 for the "all" tier, so results are returned a page at a time: count is the page size, totalCount the whole feed, and nextCursor the input for the following page. The cursor is opaque and must be passed back verbatim — unlike earthquake_search, these feeds have no upstream paging parameter and USGS regenerates them about once a minute, so a numeric offset across two calls would skip or repeat events. For historical or filtered queries, use earthquake_search instead.

- Server: [USGS Earthquakes](https://gateway.mcpharbor.dev/docs/servers/usgs_quake) (`dev.mcpharbor.gateway/usgs_quake`)
- Price per call: $0.0001 (100 micro-USD); only tools/call is charged
- Endpoint: `https://gateway.mcpharbor.dev/mcp` or `https://gateway.mcpharbor.dev/mcp/usgs_quake`
- Upstream tool: exposed by the provider; called through this gateway as `usgs_quake__earthquake_get_feed`
- Provider terms: <https://www.usgs.gov/information-policies-and-instructions/copyrights-and-credits> (verified 2026-09-19)
- Upstream API documentation: <https://earthquake.usgs.gov/fdsnws/event/1/>
- Rate limit: 600 requests per minute
- Attribution required: Not legally required (public domain), but USGS asks that proper credit be given, e.g. 'Credit: U.S. Geological Survey, Department of the Interior/USGS'. Do not imply USGS endorsement.

## Parameters

- `cursor` (string, optional): Opaque token for the next page, taken verbatim from a previous call's nextCursor. Omit for the first page. Do not construct, parse, or edit it — it encodes a position in the feed snapshot and is re...
- `limit` (integer, optional): Maximum events to return in this call. Default 100, max 1000. Applies to the first page; later pages carry the page size inside the cursor, so set it on the first call rather than changing it mid-s...
- `magnitude_tier` (string, optional): Minimum magnitude threshold for the feed. "all" includes microseisms (M\<1). "1.0" is M1.0+. "2.5" is M2.5+. "4.5" is M4.5+. "significant" is a USGS curated selection based on magnitude, felt report... One of: `all`, `1.0`, `2.5`, `4.5`, `significant`. Default: `2.5`.
- `time_window` (string, optional): Time window for the feed. "hour" typically returns 0–10 events; "month" can exceed 10,000 for the "all" tier. Prefer "hour" or "day" for real-time status checks. One of: `hour`, `day`, `week`, `month`. Default: `day`.

## Example call

Request headers and body:

```http
POST /mcp HTTP/1.1
Host: gateway.mcpharbor.dev
Authorization: Bearer <your gateway API key>
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: usgs_quake__earthquake_get_feed
```

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "example-agent",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/protocolVersion": "2026-07-28"
    },
    "arguments": {
      "cursor": "example"
    },
    "name": "usgs_quake__earthquake_get_feed"
  }
}
```

A successful response:

```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "_meta": {
      "dev.mcpharbor.gateway/call": {
        "chargedMicroUsd": 100,
        "id": "<the id of this charge>"
      }
    },
    "content": [
      {
        "text": "<whatever the upstream tool returned>",
        "type": "text"
      }
    ],
    "resultType": "complete"
  }
}
```

This call costs $0.0001 (100 micro-USD). Reading this page and listing the tool cost nothing.
The `dev.mcpharbor.gateway/call` record in the result is the receipt for that charge. Each
POST is metered separately, so sending the same call again buys another one: see
[agent.txt](https://gateway.mcpharbor.dev/agent.txt), section 7, before retrying.

## Attribution

This provider requires the attribution below wherever you use results from its tools.
Reproduce it verbatim:

> Not legally required (public domain), but USGS asks that proper credit be given, e.g. 'Credit: U.S. Geological Survey, Department of the Interior/USGS'. Do not imply USGS endorsement.

## Tool definition

Exactly as `tools/list` returns it (free):

```json
{
  "_meta": {
    "dev.mcpharbor.gateway/pricing": {
      "currency": "USD",
      "pricePerCallMicroUsd": 100
    }
  },
  "annotations": {
    "idempotentHint": true,
    "openWorldHint": true,
    "readOnlyHint": true
  },
  "description": "Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time window. These feeds are CDN-cached by USGS and faster and more available than the query API — use them for \"what's happening now\" queries. \"all\" includes microseisms (M<1); \"significant\" is a USGS curation based on magnitude, felt reports, and PAGER impact estimates. \"hour\" returns 0–10 events typically; \"month\" can exceed 10,000 for the \"all\" tier, so results are returned a page at a time: count is the page size, totalCount the whole feed, and nextCursor the input for the following page. The cursor is opaque and must be passed back verbatim — unlike earthquake_search, these feeds have no upstream paging parameter and USGS regenerates them about once a minute, so a numeric offset across two calls would skip or repeat events. For historical or filtered queries, use earthquake_search instead.",
  "inputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "properties": {
      "cursor": {
        "description": "Opaque token for the next page, taken verbatim from a previous call's nextCursor. Omit for the first page. Do not construct, parse, or edit it — it encodes a position in the feed snapshot and is rejected if malformed.",
        "type": "string"
      },
      "limit": {
        "description": "Maximum events to return in this call. Default 100, max 1000. Applies to the first page; later pages carry the page size inside the cursor, so set it on the first call rather than changing it mid-sequence.",
        "maximum": 1000,
        "minimum": 1,
        "type": "integer"
      },
      "magnitude_tier": {
        "default": "2.5",
        "description": "Minimum magnitude threshold for the feed. \"all\" includes microseisms (M<1). \"1.0\" is M1.0+. \"2.5\" is M2.5+. \"4.5\" is M4.5+. \"significant\" is a USGS curated selection based on magnitude, felt reports, and PAGER impact estimates — not purely magnitude-based.",
        "enum": [
          "all",
          "1.0",
          "2.5",
          "4.5",
          "significant"
        ],
        "type": "string"
      },
      "time_window": {
        "default": "day",
        "description": "Time window for the feed. \"hour\" typically returns 0–10 events; \"month\" can exceed 10,000 for the \"all\" tier. Prefer \"hour\" or \"day\" for real-time status checks.",
        "enum": [
          "hour",
          "day",
          "week",
          "month"
        ],
        "type": "string"
      }
    },
    "type": "object"
  },
  "name": "usgs_quake__earthquake_get_feed",
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "additionalProperties": false,
    "anyOf": [
      {
        "not": {
          "required": [
            "error"
          ]
        },
        "required": [
          "count",
          "generated_at",
          "events",
          "feed_url"
        ]
      },
      {
        "required": [
          "error"
        ]
      }
    ],
    "properties": {
      "count": {
        "description": "Number of events returned in this page, not the whole feed.",
        "type": "number"
      },
      "error": {
        "additionalProperties": {},
        "description": "Present when the call failed. Absent on success.",
        "properties": {
          "code": {
            "description": "JSON-RPC error code for this failure.",
            "maximum": 9007199254740991,
            "minimum": -9007199254740991,
            "type": "integer"
          },
          "data": {
            "additionalProperties": {},
            "properties": {
              "reason": {
                "description": "Machine-readable failure mode. Declared by this tool: `feed_unavailable`: USGS feed endpoint returns a 5xx, HTML, or is unreachable. `feed_timeout`: USGS feed endpoint did not answer before the request deadline. Other values are possible when a failure originates below the handler.",
                "examples": [
                  "feed_unavailable",
                  "feed_timeout"
                ],
                "type": "string"
              },
              "recovery": {
                "additionalProperties": {},
                "description": "Actionable next step for the caller.",
                "properties": {
                  "hint": {
                    "type": "string"
                  }
                },
                "required": [
                  "hint"
                ],
                "type": "object"
              },
              "retryable": {
                "description": "Whether retrying may succeed.",
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "message": {
            "description": "Human-readable description of what went wrong.",
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      },
      "events": {
        "description": "Earthquake events for this page, newest first.",
        "items": {
          "additionalProperties": false,
          "description": "A single earthquake event.",
          "properties": {
            "alert": {
              "anyOf": [
                {
                  "enum": [
                    "green",
                    "yellow",
                    "orange",
                    "red"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "PAGER estimated impact alert level. Null when USGS ran no PAGER assessment, and always null for EMSC, which publishes no such field."
            },
            "auth": {
              "description": "Code of the agency or network the source names as authoritative for this solution, e.g. \"NEIC\", \"BMKG\", \"NDI\" from EMSC or \"us\", \"ci\", \"ak\" from USGS. Absent when the source reports none.",
              "type": "string"
            },
            "cdi": {
              "description": "Maximum reported intensity (Community Decimal Intensity, 0–12 scale), derived from DYFI responses. Null when USGS computed no DYFI intensity, and always null for EMSC, which publishes no such field.",
              "type": [
                "number",
                "null"
              ]
            },
            "depth_km": {
              "description": "Hypocenter depth in kilometers. Shallow (<70 km), intermediate (70–300 km), or deep (>300 km). Null for historical events where depth was not measured.",
              "type": [
                "number",
                "null"
              ]
            },
            "detail_url": {
              "description": "URL to fetch the full GeoJSON detail record. Present in USGS list responses.",
              "type": "string"
            },
            "event_certainty": {
              "description": "How certain the source is of event_type: \"known\" (asserted), \"suspected\", \"unknown\", or \"unreported\". EMSC publishes this as the first character of its event-type code — a suspected explosion is not a confirmed one, and this is the only field that says so. Absent for USGS, which publishes no certainty axis, and absent for an EMSC code outside the published nomenclature.",
              "enum": [
                "known",
                "suspected",
                "unknown",
                "unreported"
              ],
              "type": "string"
            },
            "event_type": {
              "description": "What kind of event this is, in one vocabulary whichever source served it — the QuakeML type names USGS publishes (\"earthquake\", \"quarry blast\", \"explosion\", \"ice quake\"). EMSC's two-character code is decoded to the same names, so the same event carries the same value from either source; how sure the source is rides on event_certainty instead. A code outside the published nomenclature is forwarded verbatim rather than guessed at. Not every record in either catalog is a tectonic earthquake. Absent when the source publishes no classification.",
              "type": "string"
            },
            "event_url": {
              "description": "USGS event page URL. Present for USGS events only.",
              "type": "string"
            },
            "felt": {
              "description": "Number of DYFI (Did You Feel It?) responses. Null when USGS has received no reports for the event, and always null for EMSC, which publishes no DYFI field — a null is not evidence the event went unfelt.",
              "type": [
                "number",
                "null"
              ]
            },
            "id": {
              "description": "USGS or EMSC event identifier.",
              "type": "string"
            },
            "latitude": {
              "description": "Epicenter latitude in decimal degrees.",
              "type": "number"
            },
            "longitude": {
              "description": "Epicenter longitude in decimal degrees.",
              "type": "number"
            },
            "magnitude": {
              "description": "Preferred magnitude value. Null when no magnitude was computed for the event (the title renders it as \"M ?\").",
              "type": [
                "number",
                "null"
              ]
            },
            "magnitude_type": {
              "description": "Magnitude type (ml, mww, mw, mb, etc.).",
              "type": "string"
            },
            "mmi": {
              "description": "Maximum ShakeMap instrumental intensity (Modified Mercalli, 0–12 scale). Null when USGS produced no ShakeMap for the event, and always null for EMSC, which publishes no such field.",
              "type": [
                "number",
                "null"
              ]
            },
            "place": {
              "description": "Nearest named location.",
              "type": "string"
            },
            "significance": {
              "description": "USGS significance score (0–2000+). Combines magnitude, felt reports, PAGER. Null when USGS computed no score, and always null for EMSC, which publishes no such field.",
              "type": [
                "number",
                "null"
              ]
            },
            "source_catalog": {
              "description": "Upstream catalog this solution came from, e.g. \"EMSC-RTS\" (EMSC real-time seismicity, revised as analysis continues). Absent for USGS, which publishes no catalog identifier on event records.",
              "type": "string"
            },
            "status": {
              "anyOf": [
                {
                  "enum": [
                    "automatic",
                    "reviewed",
                    "deleted"
                  ],
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Human-review state: \"automatic\" (posted by automatic processing, not yet verified by a person), \"reviewed\" (examined by an analyst), or \"deleted\". Null when the source publishes no review status — EMSC does not, so treat an EMSC solution as unverified and subject to revision rather than final."
            },
            "time": {
              "description": "ISO 8601 UTC origin time.",
              "type": "string"
            },
            "title": {
              "description": "Human-readable event summary, e.g. \"M 6.0 - 13 km S of Honaunau-Napoopoo, Hawaii\".",
              "type": "string"
            },
            "tsunami": {
              "description": "USGS tsunami flag: 1 for large events in oceanic regions, 0 otherwise. It is not a warning — USGS states the flag does not indicate whether a tsunami did or will exist; check NOAA (tsunami.gov) for actual alert status. Null when the source publishes no such flag, as EMSC does not.",
              "type": [
                "number",
                "null"
              ]
            },
            "updated": {
              "description": "ISO 8601 UTC time this record was last updated.",
              "type": "string"
            }
          },
          "required": [
            "id",
            "title",
            "magnitude",
            "magnitude_type",
            "time",
            "updated",
            "place",
            "latitude",
            "longitude",
            "depth_km",
            "felt",
            "cdi",
            "mmi",
            "alert",
            "tsunami",
            "significance",
            "status"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "feed_url": {
        "description": "Source feed URL.",
        "type": "string"
      },
      "generated_at": {
        "description": "ISO 8601 UTC timestamp when this feed was generated by USGS.",
        "type": "string"
      },
      "nextCursor": {
        "description": "Opaque token to pass back as the cursor input for the next page. Present only when more events remain; absent means this was the last page.",
        "type": "string"
      },
      "notice": {
        "description": "Recovery guidance when the feed contains no events, or how to continue when a page was capped — narrowing the magnitude tier, widening the time window, paging with the cursor, or using earthquake_search for filtered queries. Absent when a single page covers the whole feed.",
        "type": "string"
      },
      "totalCount": {
        "description": "Number of events in the whole feed, across every page.",
        "type": "number"
      },
      "truncated": {
        "description": "True when the feed holds more events than this page returned. nextCursor carries the input for the following page.",
        "type": "boolean"
      }
    },
    "type": "object"
  },
  "title": "Get USGS Earthquake Feed"
}
```