[00/Katzilla · Docs]live

The Katzilla API.

One REST API wrapping every major US government dataset plus the web via Scrape. One key. One citation contract. SDKs for TypeScript, Python, LangChain, Anthropic Claude, MCP, and the Agent2Agent protocol.

217+ actions27 agents283,057 validated datasets+133,670 searchable (raw file)// live · fetched from api.katzilla.dev

[01/Quickstart]

5 minutes from zero to first call.

Create an account, grab an API key, and hit an action. Every endpoint works the same way — pick an agent, pick an action, send params.

1 · install the SDK

npm i @katzilla/sdk
# or: pip install katzilla

2 · initialize with your key

import { Katzilla } from "@katzilla/sdk";
const kz = new Katzilla({ apiKey: "kz_live_..." });

3 · run an action

const quakes = await kz.query("hazards", "usgs-earthquakes", {
  minMagnitude: 5,
  limit: 10,
});

console.log(quakes.data);     // structured payload
console.log(quakes.quality);  // freshness, uptime, confidence
console.log(quakes.citation); // source_url, license, data_hash

That's the whole model. Every one of the 300+ actions follows the same query(agent, action, params) pattern.

[02/Authentication]

API keys, JWT, or social login.

Two supported authentication shapes, both issued from the same developer account.

API Key

// recommended for server-to-server

›Create from the dashboard → Keys.
›Ship as X-API-Key header.
›Scoped to your plan's rate + request limits.

curl -H "X-API-Key: kz_live_..."

JWT (bearer)

// recommended for user-facing apps

›Get via POST /auth/login or OAuth exchange.
›7-day expiry · refresh via re-login.
›sub claim maps to developer UUID.

curl -H "Authorization: Bearer eyJhbGc..."

Social login: GitHub and Google OAuth flows are live. Both issue the same JWT and populate your developer record on first sign-in.

[03/Request + response]

One envelope. Every action.

Actions are invoked at POST /agents/:handle/actions/:actionId. The body is the action's input params (validated by its Zod schema) plus any token-optimization flags. Response always carries data, quality, citation, and meta.

request · POST /agents/hazards/actions/usgs-earthquakes

{
  "minMagnitude": 5,
  "limit": 10,
  "_fields": ["time", "mag", "place"],
  "_format": "compact"
}

response

{
  "success": true,
  "data": { /* structured result */ },
  "text": null,
  "meta": {
    "agent": "hazards",
    "action": "usgs-earthquakes",
    "authMethod": "api-key",
    "creditsCharged": 0,
    "cacheStatus": "hit",
    "durationMs": 142
  },
  "quality": {
    "freshness_seconds": 47,
    "source_uptime_7d": 0.98,
    "confidence": "high",
    "certainty_score": 0.923
  },
  "citation": {
    "source_name": "U.S. Geological Survey",
    "source_url": "https://earthquake.usgs.gov/fdsnws/event/1/",
    "retrieved_at": "2026-04-17T12:34:56Z",
    "data_hash": "sha256:a1f3...",
    "license": "Public Domain",
    "update_frequency": "real-time"
  }
}

[04/Token optimization]

Trim responses for agents.

LLMs burn tokens on redundant fields. These params go in the same request body as action params; they're extracted before Zod validation.

paramtypeeffect

_fieldsstring[]Return only the named fields. Cuts payload size dramatically on large responses.

_format"full" | "compact"compact strips nulls. full keeps original shape.

_limitnumberCap array results (overrides per-action defaults).

_pagenumberPagination when the action supports it.

_normalizebooleanNormalize field names across sources (e.g. zip_code vs zipcode).

_units"metric" | "imperial"Unit conversion where applicable.

_summarybooleanReturn aggregate stats instead of raw rows.

_mocktrueReturn cached sample data. No upstream hit. Free on every plan.

[05/Citation contract]

Every response. Every endpoint. Every product.

Data, Scrape, Watch, and Ask all return the same citation block. One integration gives you auditable AI across the stack.

source_nameU.S. SEC EDGAR
source_urlhttps://sec.gov/cgi-bin/...
retrieved_at2026-04-17T12:34:56Z
data_hashsha256:a1f3... (verifiable)
licensePublic Domain
update_frequency"real-time" | "hourly" | "daily" | ...
original_format"JSON" | "CSV" | "XML" | "HTML" | ...
request_urlfull URL actually fetched upstream
citation_texthuman-readable citation string
citation_footnote[1] USGS, Apr 2026 style

data_hash is the sha256 of the response payload at fetch time. Re-fetch the source yourself and compare — if hashes match, you saw what we saw, byte-for-byte.

[06/SDKs]

Ship in your language.

typescript

import { Katzilla } from "@katzilla/sdk";
const kz = new Katzilla({ apiKey: process.env.KZ_KEY! });

const quakes = await kz.query("hazards", "usgs-earthquakes", {
  minMagnitude: 5, limit: 10,
});

// Chained form
const bills = await kz.agent("government").action("congress-bills", {
  query: "climate", limit: 5,
});

// Mock mode — no upstream hit, free
const sample = await kz.query("hazards", "usgs-earthquakes", {}, { _mock: true });

python

from katzilla import Katzilla

kz = Katzilla(api_key=os.environ["KZ_KEY"])

result = kz.query("health", "fda-recalls", {"search": "peanut", "limit": 10})

print(result.data)      # structured payload
print(result.quality)   # freshness, uptime, confidence
print(result.citation)  # source URL, license, data_hash

# Token optimization
bills = kz.query("government", "congress-bills", {"query": "healthcare"},
    fields=["billNumber", "title", "latestAction"],
    limit=20, format="compact")

langchain

from katzilla.langchain import get_katzilla_tools

# Expose only the categories you need to the LLM
tools = get_katzilla_tools(
    api_key=os.environ["KZ_KEY"],
    include=["hazards__", "economic__", "government__"],
)

agent = create_openai_functions_agent(llm, tools, prompt)

anthropic claude

from anthropic import Anthropic
from katzilla import Katzilla
from katzilla.anthropic_tools import as_anthropic_tools, handle_tool_calls

kz = Katzilla(api_key=os.environ["KZ_KEY"])
tools = as_anthropic_tools(kz)

msg = client.messages.create(
    model="claude-opus-4-7",
    tools=tools,
    messages=[{"role": "user", "content": "What's the latest on SEC AI disclosure?"}],
)
# handle_tool_calls runs tool_use blocks via Katzilla, returns new messages
msg = handle_tool_calls(client, kz, msg)

mcp (model context protocol)

# Katzilla ships an MCP server
npx @katzilla/mcp

# Or configure Claude Desktop / Cursor to connect directly:
{
  "mcpServers": {
    "katzilla": {
      "command": "npx",
      "args": ["-y", "@katzilla/mcp"],
      "env": { "KATZILLA_API_KEY": "kz_live_..." }
    }
  }
}

[07/Agent catalog]

27 agents · fetched live.

Each agent groups related actions under one handle. Slug is what you pass as the first argument to kz.query().

hazards

Hazards & Disasters Agent

7 actions+

Query real-time earthquake, weather alert, wildfire, flood, volcano, hurricane, and disaster data from USGS, NWS, NASA FIRMS, GDACS, FEMA, Smithsonian GVP, and NOAA NHC.

›usgs-earthquakes— USGS Earthquakes
›nws-alerts— NWS Weather Alerts
›nasa-wildfires— NASA FIRMS Wildfires
›usgs-water— USGS Water Services
›fema-disasters— FEMA Disaster Declarations
›hurricane-tracking— NWS Hurricane & Tropical Storm Alerts
›fema-nfip-claims— FEMA Flood Insurance Claims

economic

Economic & Financial Data Agent

17 actions+

Access economic and financial data from FRED, BLS, Treasury, World Bank, WTO, ECB, IMF, UN Comtrade, BEA, OECD, and Eurostat. Retrieve GDP, CPI, unemployment, inflation, trade, debt, and exchange rate data for the US, EU, and worldwide.

›fred-series— FRED Series Observations
›fred-search— FRED Series Search
›bls-series— BLS Time Series
›treasury-debt— US Treasury Debt
›exchange-rates— Currency Exchange Rates
›world-bank— World Bank Indicators
›wto-trade— WTO Trade Data
›ecb-rates— ECB Exchange Rates
›imf-commodities— IMF World Economic Outlook
›comtrade— UN Comtrade
›bea-gdp— BEA GDP
›oecd-indicators— OECD Indicators
›eurostat-gdp— Eurostat GDP & National Accounts
›eurostat-unemployment— Eurostat Unemployment Rate
›eurostat-inflation— Eurostat HICP Inflation
›boc-rates— Bank of Canada Rates
›treasury-fiscal-data— Treasury FiscalData

demographics

Demographics & Population Agent

5 actions+

Population, census, and country data from the U.S. Census Bureau, Eurostat, Data USA, REST Countries, and Nager.Date. Demographics, public holidays, and country profiles.

›census-acs— Census ACS 5-Year
›eurostat— Eurostat Statistics
›rest-countries— REST Countries
›nager-date— Public Holidays
›census-economic-indicators— Census Economic Indicators

education

Education Data Agent

5 actions+

Education data from the US Department of Education, National Park Service, Hipolabs, College Scorecard, and UK Department for Education. School directories, university search, admissions, tuition, demographics, and UK school performance.

›nps-education— NPS Lesson Plans
›hipolabs-universities— World Universities Search
›college-scorecard— College Scorecard
›ed-demographics— Education Demographics
›uk-education— UK Education Statistics

consumer

Consumer Protection Agent

6 actions+

Consumer protection data from CPSC, FTC, and CFPB. Product recalls, safety violations, Do Not Call complaints, merger notices, and consumer financial complaints.

›cpsc-recalls— CPSC Product Recalls
›ftc-dnc— FTC Do Not Call Complaints
›ftc-mergers— FTC HSR Early Termination Notices
›cfpb-complaints— CFPB Consumer Complaints
›cpsc-violations— CPSC Violations & Investigations
›cfpb-hmda— CFPB Mortgage Data (HMDA)

housing

Housing & Travel Agent

5 actions+

Housing and travel data from HUD, GSA, and HM Land Registry. Fair Market Rent rates, federal per diem rates, and UK house price transactions.

›hud-fmr— HUD Fair Market Rents
›gsa-per-diem— GSA Per Diem Rates
›hud-income-limits— HUD Income Limits
›hud-chas— HUD CHAS Affordability Data
›uk-land-registry— UK Land Registry House Prices

culture

Culture & Reference Agent

8 actions+

Query libraries, museums, and public archives — Library of Congress, Smithsonian, Art Institute of Chicago, Met Museum, Project Gutenberg, Open Library, MediaWiki, and openAFRICA.

›loc-search— Library of Congress Search
›mediawiki— Wikipedia Summary
›aic-artworks— Art Institute of Chicago Artworks
›open-library— Open Library Book Search
›openafrica— openAFRICA Dataset Search
›met-museum— Metropolitan Museum of Art
›gutendex— Project Gutenberg Books
›smithsonian— Smithsonian Open Access

government

Government & Public Data Agent

38 actions+

Access government open data portals, legislative records, public procurement, election filings, and regulatory documents from the US, Brazil, UK, EU, and 15+ countries including France, Germany, Italy, Netherlands, and more.

›usaspending— USAspending Agencies
›sec-edgar— SEC EDGAR Filings Search
›congress-bills— U.S. Congress Bills
›govinfo— GovInfo Collections
›govinfo-search— GovInfo Search
›govinfo-package— GovInfo Package Summary
›govinfo-granule— GovInfo Granule Summary
›govinfo-content— GovInfo Document Content
›fec-candidates— FEC Candidates
›datagov— Data.gov Dataset Search
›federal-register— Federal Register Documents
›data-ireland— Ireland Open Data
›datos-spain— Spain Open Data
›podatki-slovenia— Slovenia Open Data
›data-queensland— Queensland Open Data
›data-istanbul— Istanbul Open Data
›data-gdansk— Gdansk Open Data
›data-lviv— Lviv Open Data
›receita-ws— ReceitaWS CNPJ Lookup
›camara-brazil— Brazilian Chamber of Deputies
// + 18 more

crime

Crime & Law Enforcement Agent

6 actions+

Access FBI most wanted lists, crime statistics (UCR), federal court opinions, and the RECAP Archive of federal dockets (PACER mirror via Free Law Project).

security

Security & Sanctions Agent

5 actions+

Access cybersecurity vulnerability databases (CISA KEV, NVD), internet outage monitoring (IODA), BGP routing data (RIPE RIS), and sanctions lists (OFAC, EU).

›cisa-kev— CISA Known Exploited Vulnerabilities
›nvd— NVD CVE Search
›ioda— IODA Internet Outages
›ripe-ris— RIPE RIS Peers
›rsf-index— World Governance Indicators (WGI)

military

Military & Defense Agent

3 actions+

Access SIPRI military expenditure data, arms transfer records, and top arms-producing companies information.

›sipri-expenditure— SIPRI Military Expenditure
›sipri-transfers— SIPRI Military Expenditure by Country
›sipri-companies— SIPRI Top Military Spenders

immigration

Immigration & Migration Agent

1 actions+

Access immigration and migration data from Eurostat migration datasets.

›eurostat-migration— Eurostat Migration Statistics

science

Science & Research Agent

15 actions+

Search scholarly literature, biodiversity databases, taxonomy, NASA media, Nobel prizes, astronomical catalogs, and linguistic tools across OpenAlex, Crossref, arXiv, Semantic Scholar, PubMed, and more.

›openalex— OpenAlex Works Search
›crossref— Crossref Works Search
›arxiv— arXiv Preprint Search
›semantic-scholar— Semantic Scholar Paper Search
›pubmed— PubMed Search
›share-osf— SHARE / OSF Search
›idigbio— iDigBio Specimen Search
›inspire-hep— INSPIRE-HEP Literature Search
›isro— ISRO Spacecrafts
›nasa-images— NASA Image & Video Library
›nobel-prize— Nobel Prize Data
›sunrise-sunset— Sunrise & Sunset Times
›datamuse— Datamuse Word Search
›nsf-awards— NSF Research Awards
›osti-research— DOE OSTI Research Publications

environment

Environment & Air Quality Agent

18 actions+

Query air quality, emissions, carbon intensity, tidal data, and environmental monitoring from OpenAQ, EPA, NOAA, Climate TRACE, Open-Meteo, EEA, and more. Covers US and European monitoring stations.

›openaq— OpenAQ Air Quality Locations
›waqi— World Air Quality Index
›epa-aqs— EPA AQS State List
›epa-echo— EPA ECHO Facilities
›noaa-coops— NOAA CO-OPS Tides & Currents
›openmeteo-aq— Open-Meteo Air Quality
›climate-trace— Climate TRACE Emissions
›climate-trace-assets— Climate TRACE Asset-Level Emissions
›climate-trace-sectors— Climate TRACE Sector-Level Emissions
›copernicus— Copernicus Climate Data Store Collections
›opensensemap— openSenseMap Sensor Boxes
›carbon-intensity— UK Carbon Intensity
›epa-envirofacts— EPA Envirofacts
›epa-ghg— EPA Greenhouse Gas Reporting
›uk-floods— UK Flood Warnings & River Levels
›canada-weather— Environment Canada Weather Alerts
›epa-attains— EPA Water Quality Assessments
›noaa-cdo— NOAA Climate Data Online

health

Health & Medical Data Agent

19 actions+

Query disease stats, FDA drug recalls and adverse events, clinical trials, nutrition data, healthcare provider registries, and humanitarian reports from disease.sh, openFDA, ClinicalTrials.gov, USDA, WHO, CDC, and more.

›disease-outbreaks— Disease.sh COVID-19 Stats
›fda-recalls— FDA Drug Recalls
›fda-adverse-events— FDA Drug Adverse Events
›fda-devices— FDA Device Recalls
›cdc-data— CDC Data
›who-gho— WHO Global Health Observatory
›nih-clinical-trials— ClinicalTrials.gov Studies
›usda-food— USDA FoodData Central
›nppes-npi— NPPES NPI Registry
›nhs-scotland— NHS Scotland Open Data
›healthcare-gov— HealthCare.gov Metadata
›disease-sh-vaccine— Disease.sh Vaccine Coverage
›nih-reporter— NIH RePORTER Projects
›cdc-wonder— CDC Leading Causes of Death
›nhs-england— NHS England Statistics
›health-canada— Health Canada Drug Product Database
›pubchem-compound— PubChem Chemical Compound
›rxnorm-drugs— RxNorm Drug Lookup
›cms-provider-data— CMS Provider Data

space

Space & Astronomy Agent

12 actions+

Query near-Earth asteroids, the Astronomy Picture of the Day, exoplanet data, solar weather, upcoming launches, satellite tracking references, and real-time ISS position from NASA, NOAA SWPC, The Space Devs, and Where The ISS At.

›nasa-asteroids— NASA Near-Earth Asteroids
›nasa-apod— NASA Astronomy Picture of the Day
›nasa-exoplanets— NASA Exoplanet Archive
›solar-weather— NOAA Solar Weather (Kp Index)
›launch-schedule— Space Launch Schedule
›space-track— Space-Track Satellite Data
›iss-tracker— ISS Real-Time Location
›nasa-techport— NASA Technology Portfolio
›nasa-epic— NASA EPIC Earth Images
›nasa-power— NASA POWER Climate Data
›nasa-eonet— NASA EONET Natural Events
›nasa-close-approaches— NASA Asteroid Close Approaches

energy

Energy & Utilities Agent

10 actions+

Energy data from EIA, NREL, and Eurostat. Petroleum prices, electricity generation, alternative fuel stations, solar resource data, utility rates, PV energy estimates, and EU energy balances.

›eia-data— EIA Energy Data
›nrel-alt-fuel— NREL Alternative Fuel Stations
›nrel-solar— NREL Solar Resource
›nrel-utility-rates— NREL Utility Rates
›nrel-pvwatts— NREL PVWatts Solar Estimate
›nrel-transport-laws— NREL Transportation Laws & Incentives
›nrel-solar-dataset-query— NREL Solar Dataset Query
›nrel-census-rate— NREL Utility Rates by Census Region
›eurostat-energy— Eurostat Energy Balance
›nrel-building-components— NREL Building Component Library

aviation

Aviation & Flight Tracking Agent

1 actions+

Real-time aircraft tracking from OpenSky Network. Aircraft positions, callsigns, altitudes, velocities, squawk codes, and origin countries within any geographic bounding box.

›opensky— OpenSky Aircraft States

maritime

Maritime & Shipping Agent

1 actions+

Vessel metadata and AIS positions from Finnish Digitraffic. Ship lookups by MMSI or name, including callsign, IMO number, ship type, draught, destination, and ETA.

›imo— IMO GISIS Ship Data

transport

Transport & Vehicles Agent

10 actions+

Public transport and vehicle safety data: US BTS transportation statistics, NHTSA vehicle recalls/complaints/safety ratings, BC Ferries, Belgian iRail, Swiss Transport, Toronto TTC, Eurostat transport indicators, and UK transport.

›bts-stats— BTS Transportation Statistics
›bc-ferries— BC Ferries Schedule
›irail— iRail Belgian Railways
›swiss-transport— Swiss Public Transport
›myttc— Toronto TTC Routes & Predictions
›nhtsa-recalls— NHTSA Vehicle Recalls
›nhtsa-complaints— NHTSA Vehicle Complaints
›nhtsa-safety-ratings— NHTSA Safety Ratings (NCAP)
›eurostat-transport— Eurostat Transport Statistics
›uk-transport— UK Transport Statistics

geo

Geography & Geolocation Agent

7 actions+

Geocoding, elevation, national parks, and postal codes from the US Census Geocoder, USGS, NPS, OpenStreetMap/Nominatim, data.gouv.fr, and Indian Postal Pincode.

agriculture

Agriculture & Food Agent

3 actions+

Search USDA FoodData Central for nutrition data, access USDA Economic Research Service resources, and query FAO FAOSTAT domains.

›usda-fooddata— USDA FoodData Central
›usda-ers— USDA Economic Research Service
›usda-nass— USDA NASS Quick Stats

trade

Trade & Government Contracts Agent

2 actions+

International trade data including EU imports/exports from Eurostat, USITC trade data references, and federal contract opportunities.

›eurostat-trade— Eurostat International Trade
›usitc— USITC Harmonized Tariff Search

telecom

Telecommunications Agent

1 actions+

Access FCC broadband map data and spectrum information.

›fcc-ecfs— FCC Electronic Comment Filing System

Per-plan caps. Hard cap on Free only.

Rate limits are per-second and per-month. Hitting the per-second limit returns 429 with a Retry-After header. See Pricing for monthly request allowances and the separate page-meter table.

planper secper monthoverage

Free21,000hard cap

Pro · $4925100,000$1 / 1K

Business · $199100500,000$0.80 / 1K

Enterprise Starter · $4992002M$0.50 / 1K

Enterprise Growth · $1,49950010M$0.30 / 1K

Enterprise Scale · $4,9991,00050M$0.20 / 1K

[09/Pricing]

Two meters. One for API calls, one for pages of live work.

Every plan has two billable dimensions. API calls cover things we've already indexed — search, metadata, raw file proxy, pre-parsed rows, agent actions. pages cover live work — a Crawlee scrape, a Claude-backed PDF parse, a crawl URL. Pages up to your plan's monthly allowance are free; overage is metered per page via Stripe and invoiced at period end.

planAPI calls / mopages included / mopage overage

Free · $01,0000n/a — paid only

Pro · $49100,000500$0.025 / page

Business · $199500,0005,000$0.020 / page

Enterprise · contactcustomcustomnegotiated

What counts as an API call vs a page

operationcharges

GET /v1/datasets/search1 API call

GET /v1/datasets/:id1 API call

GET /v1/datasets/:id/file1 API call

GET /v1/datasets/:id/parsed (pre-parsed envelope)1 API call

POST /scrape/page (HTTP or browser)1 API call + 1 page

POST /scrape/crawl1 API call + 1 page per URL

POST /agents/:handle/actions/:id1 API call

How many pages is a PDF?

A page is ~25 KB of binary PDF content — we estimate from file size before the parse so you can preview the cost. The retrieval.parse.estimated_pages field in every dataset response carries this number, alongside retrieval.parse.per_page_cents. Cached Claude results charge zero pages — the first agent to read a dataset within a 30-day window pays; subsequent agents ride free until the upstream publisher updates.

Worked examples

Searching + downloading 5 CSVs from EPA:

17 calls total · 0 pages — covered by Free.

Claude-parsing 3 × 80-page IMLS PDFs:

3 calls + ~240 pages — within the 500 included on Pro $49/mo. Next month the same 3 docs charge 0 pages (cached).

200 news scrapes/day + 50 /search calls/day:

7.5K calls + 6K pages. Pro: $49 + 5,500 pages overage × $0.025 = $186.50. Business: $199 + 1,000 pages overage × $0.020 = $219. Pro is cheaper until ~10K pages/mo.

Full reference, grandfathering rules, and SDK/MCP migration notes: docs/PRICING.md.

[09/Errors]

One shape. Specific categories.

All error responses carry success: false, a stable error.category, and a human error.message. Retry rules depend on category.

categorystatusretry

auth_invalid401no — fix key / JWT

rate_limited429yes — respect Retry-After

quota_exhausted402no — upgrade or wait for period

input_invalid400no — check schema

upstream_unavailable502yes — exponential backoff

upstream_rate_limited429yes — upstream limit, try later

not_found404no

server_error500yes — backoff, report if persistent