footnote — the Footnote Data API from your terminal

Employment-diligence data from primary public records: statutory WARN layoff notices, certified H-1B/LCA wage filings, USCIS petition outcomes, DOL Wage & Hour and OSHA enforcement, DOL debarment, H-2 seasonal-labor and PERM green-card certifications, ICE SEVP OPT/STEM-OPT top employers, federal litigation posture, and severance terms parsed from SEC filings. Counts are measured, matches are exact-or-absent, and absence of evidence is always distinguished from evidence of absence.

Free keys get trust/posture answers (WARN, H-1B, debarment) — 50 calls/day over the last 30 days. Developer ($29/mo) keeps the same datasets at 1,000 calls/day with a year of WARN depth. The volume/series datasets — H-2, PERM, OPT — are Data Pro ($79/mo or $790/yr, 10,000 calls/day, 24-month window); a free or Developer key hitting them gets a 403 upgrade_required that names the dataset and the way up, never a silent 404. footnote datasets lists every holding with its access tier.

Zero runtime dependencies. Node 18+. Docs and pricing: https://usefootnote.com/data.

Install

# one-off
npx footnote-data warn recent --state CA

# global
npm install -g footnote-data
footnote warn recent --state CA

Quickstart

# 1. Create a free account at https://usefootnote.com
# 2. Issue your API key at https://usefootnote.com/account  (Data API section — shown once)
# 3. Put it in your environment:
export FOOTNOTE_API_KEY=fn_live_your_key_here

# First call: layoff notices filed in California in the last 30 days
footnote warn recent --state CA

No key yet? Any command tells you exactly how to get one:

$ footnote warn recent
Pass your API key as: Authorization: Bearer fn_live_…

Get a free API key (50 calls/day) in three steps:
  1. Create a free account at https://usefootnote.com
  2. Issue your key at https://usefootnote.com/account (Data API section — the key is shown once)
  3. export FOOTNOTE_API_KEY=fn_live_…   (or pass --key fn_live_…)

Commands

Sample outputs below are illustrative of the response shape — run the command for live data.

WARN layoff notices

# Recent notices, newest first (free: last 30 days · Developer: last 365 · Pro: 24 months)
footnote warn recent --state CA --days 14 --limit 25

# Search by employer across states with a date window and pagination
footnote warn notices --employer "Boeing" --since 2026-06-01 --limit 50
footnote warn notices --state TX --until 2026-07-01 --offset 100

# Per-state summary: notice counts, workers affected, latest filing
footnote warn states

$ footnote warn recent --state CA --limit 2
employer_name_raw        state_code  notice_date  effective_date  workers_affected  city        layoff_type  source_url
───────────────────────  ──────────  ───────────  ──────────────  ────────────────  ──────────  ───────────  ────────────────────────────
Example Manufacturing    CA          2026-07-10   2026-09-08                   214  Fremont     Closure      https://edd.ca.gov/...
Sample Logistics Co      CA          2026-07-09   —                            88   Ontario     Layoff       https://edd.ca.gov/...

count: 2 · window_days: 30 · state: CA · tier: free
source: Official state WARN publications, ingested daily by Footnote (usefootnote.com)
license: CC BY 4.0 for display with attribution; no redistribution as a dataset/API

H-1B sponsorship & wages

# Does this employer sponsor? (certified LCA corpus)
footnote h1b employer "Databricks"

# Top sponsors by certified filing volume (free tier: top 25)
footnote h1b top-sponsors --limit 10
footnote h1b active-sponsors --limit 10   # certified-to-employ-today, by covered positions

# Petition OUTCOMES (USCIS) + current attestation INTENT (LCA), in one view
footnote sponsorship "Meta Platforms"

# Advertised (job posting) vs DOL-attested wages, same occupation and area
footnote wage-comparison "Example Corp"

$ footnote sponsorship "Example Corp"
employer                                example corp
matched_as                              entity
matched                                 true
posture                                 growing
latest_fiscal_year.fiscal_year          2023
latest_fiscal_year.initial_petition_approvals  412
current_attestation.matched             true
current_attestation.fiscal_year         2026
current_attestation.certified_filings   380
data_gaps                               (none)

tier: free
▲ upgrade: Full fiscal-year series and denial rates are on Data Pro — usefootnote.com/data

Employer enforcement & filings records

# DOL Wage & Hour enforcement posture (concluded cases, exact-name matched)
footnote enforcement "Example Restaurants LLC"

# OSHA inspections and citations
footnote osha "Example Warehousing"

# Federal litigation posture (CourtListener/RECAP; employer-level aggregates only)
footnote litigation "Example Corp"

# Executive severance / change-in-control terms from SEC Exhibit 10 filings
footnote severance "Example Corp"

Work authorization & debarment

# DOL debarment status — free tier: current / lapsed / none + program labels
footnote debarment "Example Staffing LLC"

# H-2A/H-2B seasonal-labor certifications for an employer (Data Pro)
footnote h2 "Example Farms" --program h2a --fy 2026

# National H-2 KPIs + the USCIS approved-worker trend (Data Pro)
footnote h2 summary

# PERM green-card certification decision counts (Data Pro)
footnote perm "Example Corp" --fy 2026

# ICE SEVP Top-200 OPT / STEM-OPT employers, ranked (Data Pro)
footnote opt-top --fy 2024 --limit 25

$ footnote debarment "Example Staffing LLC"
employer_query   example staffing
matched          true
status           current
programs         OFLC H-2A

tier: free
match: exact normalized legal name + registered spelling variants (never fuzzy); …
interpretation: status is derived at read time — 'current' = a debarment in force today …
▲ upgrade: Full debarment history — dates, entity spelling, willful flag, and violation text — is on Data Pro

Honesty rails these commands keep, straight from the record:

• debarment — a no-match is not a clean bill (it means no exact-legal-name entry on the DOL list); status is derived at read time, never stored.
• h2 — wages are RAW rates with their unit, never annualized (seasonal work); worker counts are OFLC application workers, not visas issued.
• h2 summary — OFLC certification (intent) and USCIS approvals (outcome) are different pipeline stages and are never divided into a conversion rate.
• perm — a PERM certification is DOL's step one of green-card sponsorship, not a green card; there is no prevailing-wage field.
• opt-top — opt_or_stem_opt_students is the source's own combined count and is not opt_students + stem_opt_students (a student in both programs is counted once per program); these are students, not employees.

Dataset provenance

# Row counts, coverage windows, and freshness — measured live at request time
footnote datasets

Built for citations: the response includes a suggested footnote of the form "Footnote Data API (usefootnote.com/data), retrieved <date>; dataset: <dataset>."

footnote get — works with endpoints that don't exist yet

The passthrough issues an authenticated GET against any path under the API, so when Footnote ships a new endpoint the CLI already supports it — no update required. This is the auto-upgrade property: the CLI grows with the API.

# Any endpoint, current or future
footnote get /api/data/v1/warn/recent state=CA limit=5

# Discover every endpoint from the live OpenAPI contract (public, no key needed)
footnote get /api/data/v1/openapi.json

# CSV export (Data Pro) — text bodies pass through untouched
footnote get /api/data/v1/warn/export.csv > warn-24mo.csv

# Full historical archive (one-time purchase)
footnote get /api/data/v1/warn/historical.csv > warn-all.csv

Output modes

• TTY: aligned tables for lists, key/value views for lookups, meta printed beneath.
• --json or piped: the raw response body, exactly as the API returned it.

footnote warn states --json | jq '.data[0]'
footnote h1b top-sponsors | jq '.data[].employer_name'   # piped ⇒ JSON automatically

Exit codes: 0 success · 1 API or network error · 2 usage error.

Rate limits

| Tier | Calls/day | Burst | WARN window | Price | |---|---|---|---|---| | Free | 50 | 10/min | 30 days | $0 | | Data Pro | 10,000 | 120/min | 24 months | see usefootnote.com/data | | Enterprise | 100,000 | 600/min | full archive | contact |

Hitting the free cap is the product working — the CLI shows you the way up:

╭────────────────────────────────────────────────────────────────────────────╮
│  Daily cap reached (50/day on the free tier).                              │
│                                                                            │
│  The free tier is enough to confirm Footnote works inside your product.    │
│  For production volume, Data Pro is 10,000 calls/day with a 24-month WARN  │
│  window — $79/mo.                                                          │
│                                                                            │
│  Your daily meter resets at 2026-07-17T00:00:00.000Z.                      │
│                                                                            │
│  https://usefootnote.com/data#pricing                                      │
╰────────────────────────────────────────────────────────────────────────────╯

Configuration

| Setting | Env var | Flag | Default | |---|---|---|---| | API key | FOOTNOTE_API_KEY | --key fn_live_… | — | | API origin | FOOTNOTE_API_URL | --api-url https://… | https://usefootnote.com | | Colors | NO_COLOR | --no-color | on for TTY |

MCP / AI assistants

An MCP server (@footnote/mcp) exposing these endpoints as tools is planned. Today, point any OpenAPI-capable agent or tool at the live machine-readable contract:

https://usefootnote.com/api/data/v1/openapi.json

License & attribution

CLI code: MIT.

Data returned on the free tier is licensed CC BY 4.0 for display with attribution — credit Data: Footnote (usefootnote.com) where you show it; redistribution as a dataset or API is not permitted. Paid tiers are governed by your Footnote Data agreement. Every response's meta.license states the terms that apply to that call.

Endpoint reference

| Command | Endpoint | |---|---| | warn recent | GET /api/data/v1/warn/recent | | warn notices | GET /api/data/v1/warn/notices | | warn states | GET /api/data/v1/warn/states | | h1b employer | GET /api/data/v1/h1b/employer | | h1b top-sponsors | GET /api/data/v1/h1b/top-sponsors | | h1b active-sponsors | GET /api/data/v1/h1b/active-sponsors | | sponsorship | GET /api/data/v1/sponsorship/employer | | enforcement | GET /api/data/v1/enforcement/employer | | litigation | GET /api/data/v1/litigation/employer | | osha | GET /api/data/v1/osha/employer | | severance | GET /api/data/v1/severance/employer | | wage-comparison | GET /api/data/v1/wage-comparison/employer | | debarment | GET /api/data/v1/debarment | | h2 | GET /api/data/v1/h2/employers | | h2 summary | GET /api/data/v1/h2/summary | | perm | GET /api/data/v1/perm/employers | | opt-top | GET /api/data/v1/opt/top-employers | | datasets | GET /api/data/v1/datasets | | get <path> | GET <any /api/data/v1 path> |