Footnote data

The data behind the briefs — one curl away.

Name: Footnote WARN monthly aggregates (state × month)
Creator: Footnote
License: https://creativecommons.org/licenses/by/4.0/

Verified WARN filings across 47 U.S. jurisdictions, updated daily, and 2.1 million+ certified U.S. Department of Labor wage records — plus advertised-vs-attested pay, severance terms, and litigation posture. The same corpus that powers every Footnote brief — now callable directly.

Create a free API key

Sign in at your account, open the Data API card, and generate a key in one click. The plaintext key is shown once — store it somewhere safe.

Call the API

Every request is a bearer-token GET. No SDK, no OAuth dance.

curl -H "Authorization: Bearer fn_live_..." \
  "https://usefootnote.com/api/data/v1/warn/recent?state=CA&limit=5"

Read the license line

Every response carries a meta.license field. On the free tier it reads CC BY 4.0 — display the data with attribution (“Footnote (usefootnote.com)” and a link back). On paid tiers it reads commercial — licensed to your account for internal use and published derived work with attribution; not for redistribution as data or assembling a substitute dataset.

Developer tools

The terminal, or your assistant.

CLI quickstart

The whole API from your terminal — the same bearer key, no SDK.

export FOOTNOTE_API_KEY=fn_live_...

npx footnote-data warn recent --state MI
npx footnote-data h1b employer databricks
npx footnote-data datasets

Open source on npm — install nothing, npx runs it directly.

Connect your AI

Add Footnote as an MCP server and any MCP-capable assistant can query the corpus directly — every answer carries citations back to usefootnote.com.

URL     https://usefootnote.com/api/mcp
Header  Authorization: Bearer fn_live_...

Endpoint reference

14 routes, one corpus.

GET/api/data/v1/warn/recent

Recent WARN notices, newest first.

Param	Type	Description
state	string	Two-letter U.S. state code. Optional — omit for all states.
days	integer	Lookback window in days. Default 30, clamped to your tier's window.
limit	integer	Rows to return, 1–100. Default 50.

GET /api/data/v1/warn/recent?state=CA&limit=5

GET/api/data/v1/warn/notices

Search and paginate the full notice history.

Param	Type	Description
state	string	Two-letter U.S. state code.
employer	string	Contains-search on employer name. Minimum 3 characters.
since / until	date	YYYY-MM-DD. Clamped to your tier's window.
limit	integer	Rows to return, 1–100. Default 50.
offset	integer	Pagination offset, 0–5,000.

GET /api/data/v1/warn/notices?employer=amazon&since=2026-01-01&limit=25

GET/api/data/v1/warn/states

Per-state summaries — notice count, workers affected, latest filing date — over your tier's window. No params beyond auth.

GET /api/data/v1/warn/states

GET/api/data/v1/warn/export.csvPro / Enterprise

CSV export of the notice history — the entire window your tier licenses, in one file, no filter params. Every export carries a per-account export_id column, so a leaked file traces back to a key.

GET /api/data/v1/warn/export.csv

GET/api/data/v1/warn/historical.csvPro / Enterprise

Full multi-decade archive CSV — requires the one-time historical purchase (403 purchase_required otherwise).

GET /api/data/v1/warn/historical.csv

GET/api/data/v1/h1b/employer

H-1B sponsorship lookup over 2.1 million+ certified LCA filings. Free tier answers sponsors yes/no plus certified filing volume; paid tiers add fiscal-year trend, OES wage-level mix, filing entities, and — where the quality bar passes — role-level pay bands and state medians.

Param	Type	Description
name	string	Company name. Minimum 3 characters; matched against normalized certified filings.

GET /api/data/v1/h1b/employer?name=deloitte

GET/api/data/v1/sponsorship/employer

Sponsorship posture from federal petition OUTCOMES, FY2009 onward — initial vs continuing approvals and denials per fiscal year. Complements /h1b/employer: LCA filings are intent; these are outcomes. Free tier answers matched + posture (growing / shrinking / maintaining / minimal) + the latest year's counts; paid tiers add the full fiscal-year series and denial rate. Petition counts, never headcount.

Param	Type	Description
name	string	Employer legal name (2–160 chars). Exact normalized match plus registered aliases — including known corporate renames.

GET /api/data/v1/sponsorship/employer?name=Meta Platforms

GET/api/data/v1/h1b/top-sponsors

Top H-1B sponsors by certified filing volume, with latest fiscal year and a link to each employer's public pay page. Free tier: top 25. Paid tiers: up to 500.

Param	Type	Description
limit	integer	Rows to return. Free up to 25, paid up to 500.

GET /api/data/v1/h1b/top-sponsors?limit=25

GET/api/data/v1/wage-comparison/employer

Advertised (public job posting) vs attested (certified DOL H-1B LCA) wages for the same occupation and area — a join no other source publishes. Free tier: how many role/area comparisons exist and whether any advertised range sits below the attested band. Paid tiers: the full comparison rows with the advertised range's position in the attested distribution. Reported as neutral position, never a divergence claim — level differences move a single posting up or down the band.

Param	Type	Description
name	string	Employer name. Minimum 2 characters; matched against posted ranges and certified LCA filings.

GET /api/data/v1/wage-comparison/employer?name=databricks

GET/api/data/v1/severance/employer

Severance and separation terms extracted from public SEC Exhibit-10 agreements, aggregated to the employer. Every figure is quote-grounded — it appears verbatim in the filing. Free tier: how many agreements are on file. Paid tiers: the extracted terms (multiples, cash, benefit continuation) with the source filing.

Param	Type	Description
name	string	Employer name. Minimum 2 characters; matched against SEC filers.

GET /api/data/v1/severance/employer?name=coinbase

GET/api/data/v1/litigation/employer

Employer litigation posture from federal PACER/RECAP dockets, categorized by nature of suit (IP/trade-secret, contract/non-compete, wage & hour, employment civil rights) and direction (as plaintiff vs defendant). Attribution is exact — the employer must be a named party. Free tier: matched case count. Paid tiers: the category breakdown with public docket links. Never renders a private individual's name.

Param	Type	Description
name	string	Employer name. Minimum 2 characters; matched as an exact party to the case.

GET /api/data/v1/litigation/employer?name=coinbase

GET/api/data/v1/enforcement/employer

U.S. DOL Wage & Hour enforcement posture — concluded WHD cases matched to the employer by exact normalized name (WHD publishes no EIN, so we under-match rather than mis-attribute). Free tier: case count and whether WHD flags a repeat FLSA (minimum-wage/overtime) violator. Paid tiers: agreed back-wage and penalty totals, H-1B and child-labor violation detail, and the most significant cases with WHD case IDs.

Param	Type	Description
name	string	Employer name. Minimum 2 characters; matched by exact normalized name.

GET /api/data/v1/enforcement/employer?name=halliburton

GET/api/data/v1/osha/employer

U.S. OSHA workplace-safety enforcement — inspections and citations matched to the employer by exact normalized establishment name. Concentrated in industrial, logistics, and manufacturing employers (an office is rarely inspected). Free tier: inspection count and whether any willful/repeat citations exist. Paid tiers: penalties, the serious/willful/repeat severity breakdown, and per-state detail.

Param	Type	Description
name	string	Employer name. Minimum 2 characters; matched by exact normalized establishment name.

GET /api/data/v1/osha/employer?name=tesla

GET/api/data/v1/datasets

The live provenance index: row counts, coverage windows, and freshness for every corpus behind this API — measured from the database at request time, never hand-maintained. Built for the footnotes of YOUR work: what you queried, and exactly how fresh it was. A null count means the measurement failed; we do not guess.

GET /api/data/v1/datasets

Response shape

Every endpoint returns the same envelope — an array of records plus a meta block with the count, the window applied, your tier, the source, and the license.

{ "data": [...], "meta": { "count": 5, "window_days": 30, "tier": "free",
  "source": "Official state WARN publications...", "license": "CC BY 4.0..." } }

Notice objects carry: employer_name_raw, state_code, notice_date, effective_date, workers_affected, city, layoff_type, source_url.

Tiers & limits

Start free, scale when you need to.

Get started

Free

Enough to confirm it works in your product.

50 calls/day · 10/min burst
WARN, last 30 days
H-1B sponsor yes/no
CC BY 4.0 for display, with attribution
No CSV export

Get your key

For buildersFull analytics

Data Pro

$79/mo

10,000 calls/day · 120/min burst
Full 24-month live window
CSV export (per-account watermark)
Full H-1B analytics — trends, wage-level mix, role bands
Advertised-vs-attested wages, severance terms, litigation posture
Commercial license

Custom scale

Enterprise

From$299/mo

100,000 calls/day · custom limits
Unwindowed — the full archive, no 24-month clamp
WARN ↔ LCA ↔ SEC joins
Licensed bulk exports — CSV, Parquet
SLA
Negotiated license

hello@usefootnote.com

One-time add-on

WARN Historical Archive

~14,000 notices — the full archive of every state source feed we have ever run, including feeds since retired — reaching back to 1998 where states publish deep history. (The live tracker holds the current 24-month window across 47 jurisdictions.) Depth varies by state; many publish only ~2 years.
Notices as published by the states — nothing backfilled.
Per-account watermark (export_id) on every row.
One-time, account-level — works with any key tier or the browser download. Commercial license.

$149one-time

H-1B data — live

H-1B sponsorship, from the same corpus.

Whether an employer sponsors, certified filing volumes and fiscal-year trends, OES wage-level mix, and — for employers past the quality bar — role-level pay bands and state medians, drawn from the same 2.1 million+ certified DOL wage-filing corpus that backs Footnote briefs and pay pages. See h1b/employer and h1b/top-sponsors in the endpoint reference above. Sponsors below the quality bar return volume truths, never thin bands — if we can't cite it, we don't serve it.

Errors

Every error is shaped the same.

Failures return a JSON body of { error: { code, message } } with the matching HTTP status.

Status	Code	Meaning
401	missing_key / invalid_key	No key, or one we don't recognize. Pass Authorization: Bearer fn_live_…
403	key_suspended / key_revoked / upgrade_required	The key isn't active, or the route is tier-gated (CSV export on the free tier).
429	burst_limit	Too many requests too fast. Retry-After: 60
429	daily_cap	Daily call cap reached for your tier. Retry-After: seconds until UTC midnight (the daily meter reset)
400	bad_state / bad_employer / bad_date	A parameter failed validation — see the endpoint's params.

Fair use

Keys are issued per account, every call is metered, and anomalous traffic is monitored. Displaying our data with attribution is welcome, and encouraged — building a competing backend on top of our metering budget is not.

Citing this data

Footnote data may be cited in published research and journalism with attribution. Every response carries a meta block naming the source, the matching discipline, and the units; the /api/data/v1/datasets index reports live row counts and freshness so your own footnote can state exactly what you queried and when. Suggested form:

Footnote Data API, usefootnote.com/data. Dataset: warn_notices,
retrieved 2026-07-12. Coverage and freshness per /api/data/v1/datasets.

A machine-readable OpenAPI 3.1 contract is published at /api/data/v1/openapi.json — import it into a notebook, Postman, or your pipeline's client generator. The contract's endpoint descriptions carry the caveats deliberately: for this audience, the caveats are the product.

Open data

A free, open aggregate of the WARN corpus — one row per state and month with the notice count and the sum of published worker counts, sourced from official state WARN filings across 47 U.S. jurisdictions and updated daily. Licensed CC BY 4.0 — reuse it anywhere with attribution to “Footnote — usefootnote.com”. Worker totals sum only counts the states published: a floor, never an estimate.

Download the CSV — columns: state_code, month, notice_count, workers_sum. Row-level notices, longer windows, and the multi-decade archive stay behind the API above.

What WARN is — and isn't

The WARN Act requires advance notice of large layoffs, but coverage thresholds vary by state — a small layoff, or one below a state's size threshold, may never generate a filing. The absence of a notice is not evidence of the absence of layoffs. Fields a given state doesn't publish come back as null — never guessed, never backfilled. Read more on our methodology, our sources, and the live WARN tracker.

Build on the receipts.

A free key takes one click. The corpus is the same one every Footnote brief is built from — verified, cited, and updated daily.

Create an API key See the data live