Developers — API Pricing, Docs & FAQ
API Endpoint Reference
Six datasets, one unified REST API. All endpoints return JSON and accept an X-API-Key header.
Getting Started
All requests go to https://warnfirehose.com/api/. Include your API key in every request:
Sign up at /account to get a free API key (25 calls/day). Paid plans unlock all states, historical data, bulk exports, and higher rate limits. See Pricing for details.
WARN Notices
WARN Act mass layoff and plant closure notices from all 50 U.S. states, updated daily.
Returns WARN notices filtered by state, date, company, city, industry, and more.
| Parameter | Type | Description |
|---|---|---|
| state | string | Two-letter state code (e.g., CA, TX) |
| company | string | Company name search (partial match) |
| city | string | City name filter |
| date_from | string | Start date (YYYY-MM-DD) |
| date_to | string | End date (YYYY-MM-DD) |
| limit | int | Results per page (default: 100, max: 5000) |
| offset | int | Pagination offset |
Returns aggregate stats: total records, states covered, date range, recent activity. No API key required.
Returns monthly counts for layoff trend charts.
| Parameter | Type | Description |
|---|---|---|
| months | int | Number of months of history (default: 12) |
Returns the companies with the most layoff notices or employees affected.
| Parameter | Type | Description |
|---|---|---|
| limit | int | Number of companies to return (default: 10) |
Returns all WARN notices for a company, plus ticker symbol, CIK, and related news articles. Powers the company detail pages.
| Parameter | Type | Description |
|---|---|---|
| company_name | string | Company name (path parameter, URL-encoded) |
Returns aggregate stats, top companies, trends, and latest notices for a state.
| Parameter | Type | Description |
|---|---|---|
| state_code | string | Two-letter state code (path parameter, e.g., CA) |
Full-text search across WARN, LCA, H-1B, SEC, bankruptcy, and JOLTS tables. Returns grouped results by dataset.
| Parameter | Type | Description |
|---|---|---|
| q | string | Search query (required) |
| limit | int | Results per dataset (default: 5) |
Returns each state with total notice and employee counts. Useful for building state selector dropdowns.
Returns yearly aggregate counts of notices and employees affected.
Returns WARN notices grouped by NAICS industry, with counts and employee totals.
Returns WARN notice counts grouped by state with lat/lng coordinates for map visualizations.
H-1B / LCA Visa Data
H-1B visa petitions (FY2009-2023) and Labor Condition Applications (FY2012-2026) from USCIS and DOL.
Returns top H-1B employers ranked by initial approvals. Filter by state and fiscal year.
Returns top employers filing Labor Condition Applications. Filter by state, fiscal year, visa class, and SOC code.
Returns summary stats: total petitions, approval rates, top employers, and wage distributions.
Returns summary stats: total applications, certification rates, top employers, and wage data.
Returns LCA petition counts and average wages by state. Filter by fiscal year and visa class.
Returns LCA petition counts by city/worksite. Filter by state, fiscal year, and visa class.
Returns LCA petition counts grouped by Standard Occupational Classification. Shows which occupations have the most visa activity.
Returns wage statistics for LCA petitions: average, median, min/max by occupation and state.
Returns year-over-year petition counts for a specific employer. Useful for tracking hiring trends.
Returns H-1B petition approvals and denials by state. Useful for geographic visa analysis.
DOL Unemployment Claims
Weekly initial and continued unemployment claims from the Department of Labor, dating back to 1984.
Returns weekly unemployment claims data with initial claims, continued claims, and insured unemployment rate.
Returns aggregate stats: total weeks of data, latest claims figures, and historical ranges.
Returns weekly national totals for initial and continued unemployment claims. Useful for macro trend analysis.
SEC 8-K Filings New
Material event filings (8-K) from SEC EDGAR. Covers restructurings, layoffs (Item 2.05), leadership changes, and more. Rolling 1-year window, refreshed daily.
Returns SEC 8-K filings filtered by ticker, CIK, company name, date range, or item type. Each record includes the accession number, ticker, company name, filing date, item codes, and links to the SEC filing.
| Parameter | Type | Default | Description |
|---|---|---|---|
| ticker | string | - | Stock ticker symbol (e.g., AAPL, MSFT) |
| cik | string | - | SEC Central Index Key |
| company | string | - | Company name (partial match) |
| start | string | - | Start date (YYYY-MM-DD) |
| end | string | - | End date (YYYY-MM-DD) |
| items | string | - | Filter by item code (e.g., "2.05" for layoffs/restructuring) |
| limit | int | 100 | Max results (up to 5000) |
Returns aggregate stats: total filings, unique companies/tickers, date range, filings in the last 7 and 30 days, and a breakdown of the most common item codes.
Returns companies ranked by number of 8-K filings. Each entry includes ticker, company name, CIK, filing count, and date range.
| Parameter | Type | Default | Description |
|---|---|---|---|
| start | string | - | Start date (YYYY-MM-DD) |
| end | string | - | End date (YYYY-MM-DD) |
| limit | int | 50 | Max results (up to 500) |
Returns daily counts of filings and unique companies. Useful for rendering trend charts.
| Parameter | Type | Default | Description |
|---|---|---|---|
| days | int | 90 | Number of days of history (max 365) |
Returns all 8-K filings for a given stock ticker. Ticker matching is case-insensitive (e.g., "aapl" and "AAPL" return the same results). Supports optional date filtering.
| Parameter | Type | Default | Description |
|---|---|---|---|
| ticker | string | - | Ticker symbol (path parameter, required) |
| start | string | - | Start date (YYYY-MM-DD) |
| end | string | - | End date (YYYY-MM-DD) |
| limit | int | 100 | Max results (up to 500) |
Cross-references SEC 8-K filers with WARN notice data. Returns companies that appear in both datasets, with filing counts and employee impact from each source. Useful for detecting corporate distress signals.
| Parameter | Type | Default | Description |
|---|---|---|---|
| days | int | 90 | Look-back window in days |
| limit | int | 50 | Max results |
Returns a fully parsed SEC 8-K filing with extracted key facts: dollar amounts, employee counts, restructuring language, officer changes, and exhibits. The accession number is a path parameter (e.g., 0001193125-23-123456).
Bankruptcy Filings New
Chapter 7 and Chapter 11 bankruptcy filings from PACER (federal bankruptcy courts), SEC EDGAR 8-K Item 1.03, and the FJC Integrated Database (historical backfill). Auto-matched against WARN companies. Rolling 1-year window, refreshed daily.
Returns bankruptcy filings filtered by company, chapter, court, date range, or WARN-matched only. Each record includes debtor name, chapter, court, filing date, docket URL, and any matched WARN company.
| Parameter | Type | Default | Description |
|---|---|---|---|
| company | string | - | Debtor or company name (partial match) |
| chapter | string | - | Bankruptcy chapter (e.g., "7", "11") |
| court | string | - | Court identifier |
| start | string | - | Start date (YYYY-MM-DD) |
| end | string | - | End date (YYYY-MM-DD) |
| warn_only | bool | false | Only return filings matched to WARN companies |
| limit | int | 100 | Max results (up to 5000) |
Returns aggregate stats: total filings, unique debtors, WARN-matched count, date range, filings in the last 7 and 30 days, and a breakdown by bankruptcy chapter.
Returns daily counts of bankruptcy filings and WARN-matched filings. Useful for trend visualizations.
| Parameter | Type | Default | Description |
|---|---|---|---|
| days | int | 90 | Number of days of history (max 365) |
Returns bankruptcy filing counts aggregated by state, including Chapter 11 vs Chapter 7 breakdown and WARN-matched counts.
| Parameter | Type | Default | Description |
|---|---|---|---|
| days | int | 365 | Look-back window in days (max 730) |
Returns bankruptcy filing counts aggregated by court. Includes court name, total filings, Chapter 11 count, WARN-matched count, and date range.
| Parameter | Type | Default | Description |
|---|---|---|---|
| days | int | 365 | Look-back window in days (max 730) |
| limit | int | 50 | Max results (up to 200) |
Returns bankruptcy cases where the debtor matches a company with WARN layoff notices. Includes WARN notice counts and total employees affected for each matched company.
| Parameter | Type | Default | Description |
|---|---|---|---|
| days | int | 365 | Look-back window in days (max 365) |
| limit | int | 50 | Max results (up to 200) |
JOLTS Labor Turnover
BLS Job Openings and Labor Turnover Survey — monthly data on openings, hires, quits, and layoffs by state and industry. Data from 2000-present.
/api/jolts/stats
Summary statistics and latest snapshot
/api/jolts/national
National time series for a given element
| Parameter | Type | Default | Description |
|---|---|---|---|
| element | str | — | JO (openings), HI (hires), TS (separations), QU (quits), LD (layoffs). Omit for all. |
| level | str | L | "L" for absolute numbers, "R" for percentage rate |
| year_from | int | — | Filter from year |
| year_to | int | — | Filter to year |
| limit | int | 500 | Max rows (up to 5000) |
/api/jolts/by-state
State-level comparison for latest month
| Parameter | Type | Default | Description |
|---|---|---|---|
| element | str | JO | JOLTS element code |
/api/jolts/by-industry
Industry-level comparison for latest month
| Parameter | Type | Default | Description |
|---|---|---|---|
| element | str | JO | JOLTS element code |
/api/jolts/trends
Monthly trend data (last 36 months)
| Parameter | Type | Default | Description |
|---|---|---|---|
| element | str | JO | JOLTS element code |
| state | str | — | Filter by state (2-letter code) |
Market Signals Exclusive
Proprietary algorithms that cross-reference WARN layoffs, H-1B/LCA visa petitions, SEC filings, and bankruptcy data to surface patterns invisible in any single dataset. Cached for 6 hours.
The Talent Displacement Index (TDI) identifies companies filing WARN layoff notices while simultaneously sponsoring H-1B/LCA visa petitions. A high TDI suggests workforce replacement rather than genuine downsizing. Formula: TDI = (LCA + H1B) / layoffs × log2(layoffs)
| Parameter | Type | Default | Description |
|---|---|---|---|
| months | int | 6 | Lookback window in months |
| min_layoffs | int | 50 | Minimum total layoffs to qualify |
| limit | int | 50 | Max results |
The Metro Contagion Score detects regional economic distress — cities where multiple unrelated companies are filing WARN notices within a tight window. Multi-industry contagion is the strongest warning sign. Formula: Score = companies² × log2(employees) / date_spread
| Parameter | Type | Default | Description |
|---|---|---|---|
| months | int | 3 | Lookback window in months |
| min_companies | int | 3 | Minimum companies in metro |
| limit | int | 50 | Max results |
The Industry Domino Index identifies systemic, industry-wide layoffs spreading across multiple states simultaneously. Cross-referenced with SEC restructuring filings and bankruptcies. Formula: Score = states × companies × log2(employees) / √date_spread
| Parameter | Type | Default | Description |
|---|---|---|---|
| months | int | 3 | Lookback window in months |
| min_states | int | 3 | Minimum states affected |
| limit | int | 30 | Max results |
/api/signals/summary
Top 5 from each signal index
Cross-Reference New
Endpoints that link data across multiple datasets. Combine WARN layoff notices, SEC 8-K filings, bankruptcy cases, and JOLTS labor turnover into a unified view of corporate distress.
The golden signal: ranks companies by composite risk score across all 6 datasets. Combines WARN volume/recency, SEC layoff/restructuring filings, bankruptcy filings, and H-1B denial rates into a single score. Returns companies sorted by distress level: Critical (7+), Elevated (4-6), Moderate (2-3).
Use cases: Recruiters (target displaced workers), hedge funds (short candidates), lawyers (WARN violations), insurance agents (COBRA outreach), outplacement firms (timing is everything).
| Parameter | Type | Default | Description |
|---|---|---|---|
| state | string | - | Filter by state (2-letter code) |
| min_score | int | 2 | Minimum risk score (1-10) |
| limit | int | 50 | Max results (up to 500) |
Returns a comprehensive market snapshot in one API call: WARN stats with 30-day trend direction (rising/falling/stable), top industries, at-risk companies, LCA/H-1B petition counts, DOL unemployment claims, SEC 8-K filing counts, bankruptcy totals, and JOLTS labor snapshot. Designed for dashboards, reports, and AI integrations that need the full picture fast.
Unified state profile combining all 6 datasets — WARN notices, LCA, H-1B, DOL claims, bankruptcies, and JOLTS. Returns a distress score with contributing signals, plus breakdowns for each dataset filtered to the requested state. One call gives you everything you need to assess a state's labor market health.
| Parameter | Type | Default | Description |
|---|---|---|---|
| state_code | string | - | 2-letter state abbreviation (path parameter, required). E.g. CA, TX, NY. |
Response fields: state, distress_score, distress_signals, warn (total, last_30d, top_industries, top_companies), lca (total_petitions, unique_employers, top_occupations), h1b (approvals, denials), dol_claims (latest_initial, latest_continued, week_ending), bankruptcies_warn_matched, jolts.
Get the composite risk signal for a single company. Returns the same scoring as the bulk endpoint but for one company — no minimum score threshold. Useful for embedding risk badges on company pages or building alerts.
Response fields: company, score, level (Critical/Elevated/Moderate/Low/None), factors (array), notice_count, employees_affected, latest_notice, states.
Returns a unified chronological timeline of all events for a company across all datasets: WARN layoff notices, SEC 8-K filings, bankruptcy cases, and JOLTS labor turnover. Uses fuzzy matching with SQL LIKE, so partial names work (e.g., "Amazon" matches "Amazon.com Services LLC"). Ideal for building company distress profiles.
Response fields: company (matched name), warn_notices (count), sec_filings (count), bankruptcy_cases (count), total_events, and a timeline array sorted by date descending. Each timeline event has a source field (warn, sec, or bankruptcy), a date, and source-specific fields (e.g., employees_affected for WARN, ticker/items for SEC, chapter/court for bankruptcy).
| Parameter | Type | Default | Description |
|---|---|---|---|
| company_name | string | - | Company name (path parameter, required). Uses fuzzy LIKE matching for partial names. |
Cross-references WARN layoff data with H-1B visa petition data. Shows companies or regions with both layoffs and active visa hiring.
Combines WARN notices, SEC filings, bankruptcy data, and JOLTS labor turnover by state for geographic analysis.
Combines WARN notices, SEC filings, bankruptcy data, and JOLTS labor turnover by city for local-level analysis.
Cross-references recent WARN notices with LCA visa petitions to show what occupations/skills each laid-off company was hiring for. Built for recruiters: find where skilled workers are becoming available and what roles they held.
| Parameter | Type | Default | Description |
|---|---|---|---|
| state | string | - | Filter by state (2-letter code) |
| soc_code | string | - | Filter by SOC occupation code (e.g. 15-1252) |
| days | int | 90 | Look back N days for WARN notices |
| limit | int | 30 | Max results |
Combines WARN notices, SEC filings, bankruptcy data, and JOLTS labor turnover by company. Returns companies with the most cross-dataset activity.