{
  "openapi": "3.0.1",
  "info": {
    "title": "USGS NWIS Streamflow & Gage Height Monitor API by Site/State",
    "description": "USGS NWIS streamflow API: pull real-time river discharge (cfs) and gage height (ft) by site number or state. Flattens nested USGS WaterML-JSON into clean rows with change deltas and flood-stage threshold alerts. Keyless USGS Water Services data for irrigation, utilities, flood risk & hydrology.",
    "version": "1.1",
    "x-build-id": "QNzqlBfPNuXNbKixZ"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/malonestar~usgs-nwis-streamflow-monitor/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-malonestar-usgs-nwis-streamflow-monitor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/malonestar~usgs-nwis-streamflow-monitor/runs": {
      "post": {
        "operationId": "runs-sync-malonestar-usgs-nwis-streamflow-monitor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/malonestar~usgs-nwis-streamflow-monitor/run-sync": {
      "post": {
        "operationId": "run-sync-malonestar-usgs-nwis-streamflow-monitor",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "sites": {
            "title": "USGS site numbers",
            "type": "array",
            "description": "List of USGS site (station) numbers to pull, e.g. [\"01646500\"] (Potomac River at Little Falls). Provide this OR a State code. Site numbers are the 8-15 digit USGS station IDs; the agency prefix is added automatically. Every site you list gets a row - one USGS did not answer for is returned with data_status \"not_returned\" rather than silently omitted, so silence is never mistaken for an all-clear.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "stateCd": {
            "title": "State code (alternative to sites)",
            "type": "string",
            "description": "USPS two-letter state code (e.g. \"VA\") to pull every gaging site in that state for the chosen parameter. Used only when no site numbers are supplied. A statewide pull can return hundreds of sites - Colorado discharge returns 615. An unrecognised code is rejected rather than silently widened to a national query.",
            "default": ""
          },
          "parameterCd": {
            "title": "Parameter code",
            "type": "string",
            "description": "USGS parameter code. 00060 = discharge / streamflow (cubic feet per second); 00065 = gage height (feet). Comma-separate to request several, e.g. \"00060,00065\".",
            "default": "00060"
          },
          "service": {
            "title": "Service (instantaneous or daily)",
            "enum": [
              "iv",
              "dv"
            ],
            "type": "string",
            "description": "Which USGS data set to read: \"iv\" for near real-time continuous (instantaneous) values, or \"dv\" for daily values. Instantaneous reads the latest-continuous collection; daily reads latest-daily and returns the daily MEAN (statistic 00003).",
            "default": "iv"
          },
          "period": {
            "title": "Look-back period (ISO 8601 duration)",
            "type": "string",
            "description": "Optional ISO-8601 duration to widen the window so a prior reading is available for the change delta, e.g. \"PT2H\" (2 hours), \"PT30M\" or \"P1D\" (1 day). Maximum 30 days. Leave blank to fetch only the latest reading per site. An unparseable value is REJECTED, not ignored - silently dropping it would return a single reading with no delta while appearing to honour the request.",
            "default": ""
          },
          "thresholdValue": {
            "title": "Global threshold value",
            "type": "string",
            "description": "Optional flood-stage / alert threshold applied to every site, in the parameter's own unit (cubic feet per second for 00060, feet for 00065). Sets above_threshold and amount_over_threshold when the latest reading meets or exceeds it. A reading that is stale, future-dated or flagged untrustworthy by USGS gets above_threshold NULL with an explanation, never false.",
            "default": ""
          },
          "siteThresholds": {
            "title": "Per-site thresholds",
            "type": "object",
            "description": "Optional per-site thresholds as a JSON object mapping site number to threshold value, e.g. {\"01646500\": 30000}. Overrides the global threshold for those sites.",
            "default": {}
          },
          "onlyAlerts": {
            "title": "Only return sites over threshold",
            "type": "boolean",
            "description": "When true, only sites whose latest reading is at or above their threshold are returned. Requires a global or per-site threshold. Sites you asked about that USGS did not answer for are still returned even in this mode - that is precisely where silence must not read as an all-clear.",
            "default": false
          },
          "siteStatus": {
            "title": "Site status filter",
            "enum": [
              "all",
              "active",
              "inactive"
            ],
            "type": "string",
            "description": "Which gages to include. \"all\" (default) returns everything, including gages that stopped reporting years ago - a Colorado discharge pull returns 615 sites of which 268 last reported over a year ago, the oldest in 1987. \"active\" and \"inactive\" are DERIVED, because the USGS OGC API publishes no operator-status flag: active means USGS has not flagged the gage DISCONTINUED and it has reported within your staleness threshold. A gage whose status cannot be judged is returned only by \"all\".",
            "default": "all"
          },
          "staleHours": {
            "title": "Stale reading threshold (hours)",
            "minimum": 1,
            "type": "integer",
            "description": "A reading older than this many hours is flagged is_stale=true, data_status=\"stale\", and its threshold verdict is withheld (above_threshold becomes null, not false). Default 72h: a healthy continuous gage reports every 15-60 minutes and a daily gage once a day. Rows are still returned - use \"Maximum reading age\" to drop them entirely.",
            "default": 72
          },
          "maxReadingAgeHours": {
            "title": "Maximum reading age (hours) - drop older",
            "minimum": 1,
            "type": "integer",
            "description": "Optional hard filter: drop any site whose latest reading is older than this many hours. Leave empty to return every site regardless of age (default). Set to e.g. 24 for a genuine real-time flood watch."
          },
          "reportMissingSites": {
            "title": "Report requested sites USGS did not return",
            "type": "boolean",
            "description": "When you supply explicit site numbers, emit a row for each one USGS returned nothing for, with data_status \"not_returned\". Keeps silence from being read as an all-clear, and is what makes the result set provably complete for a site-scoped run. Ignored for statewide pulls.",
            "default": true
          },
          "includeNoDataSites": {
            "title": "Include sites with no usable reading",
            "type": "boolean",
            "description": "Include sites whose latest reading is missing. The USGS OGC API publishes these as a JSON null (the retired legacy feed used the -999999 sentinel); each carries a qualifier explaining why - zero flow, dry, ice, equipment malfunction, discontinued, rating under development, or out of season. Off by default.",
            "default": false
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}