# Changelog of OSHA Inspections, Violations & Penalty Screener (`pyralislabs/osha-violations-penalty-screener`) Actor

- **URL**: https://apify.com/pyralislabs/osha-violations-penalty-screener/changelog.md
- **Full Actor documentation**: https://apify.com/pyralislabs/osha-violations-penalty-screener.md

## Changelog

### \[0.3.2] - 2026-06-10

#### Fixed

- **Rate-limit circuit breaker:** once any request exhausts its 429 retries, remaining violation-detail fetches are skipped immediately (with a clear per-record notice, and never charged) instead of each grinding through its own multi-minute backoff — a fully-throttled sweep now finishes in minutes with complete inspection data instead of stalling for hours
- Built-in-key violation runs reduced to 25 records and paced at 2.5s/request (own-key runs keep 50+ at 1.5s) — DOL's quota appears to combine a ~60-request burst bucket with a slow refill and a likely hourly cap

### \[0.3.1] - 2026-06-10

#### Fixed

- Violation-detail fetches now run sequentially at ~0.5 req/s (was 2 parallel at ~2 req/s), staying under DOL's sustained rate instead of exhausting the ~50-60 request burst and stalling runs for ~5 minutes mid-sweep
- Pacing automatically doubles for the rest of the run after the first 429, so a throttled run recovers once instead of repeatedly re-tripping the limit

### \[0.3.0] - 2026-06-10

#### Changed (verified against the live DOL v4 API with a real key)

- **Penalty screening redesigned (violation-first):** the v4 inspection dataset has no penalty field (confirmed via its metadata), so `minPenalty` now queries the violation dataset server-side (citations ≥ threshold within the date window, largest first) and then fetches only the matching inspections — 2–6 API requests instead of one per inspection. Semantics: "inspections with at least one citation at/above the threshold."
- `total_current_penalty` is now **computed by summing the inspection's citations**; `null` when violation detail was not fetched (previously it silently reported `0` from a nonexistent field)
- `minPenalty` > 0 auto-enables violation detail (needed to compute penalties; charged as `violation-detail` and included in output)
- `violations` is `[]` when an inspection was queried and has no citations (HTTP 204 from DOL), distinct from `null` (not queried)
- Default `maxResults` lowered 500 → 100

#### Added

- **Built-in-key guardrails:** runs on the shared key cap at 200 records (50 with violation detail) with a clear notice; user-supplied keys keep the full 10,000 limit
- **Rate-limit handling tuned to measured behavior** (~15–20 rapid requests trip DOL's throttle; recovery ~4–6 min): dedicated long 429 backoff schedule (~8.5 min total), violation-fetch pacing (250 ms) and concurrency 2
- Empty-body/204 responses handled as zero rows
- Local `.env` auto-loading for `DOL_API_KEY` (actor dir, then repo root) — `apify run` works out of the box
- Required DOL ToS attribution notice in README and in every output record (`attribution` field)

### \[0.2.0] - 2026-06-10

#### Changed

- Renamed actor to `osha-violations-penalty-screener` ("OSHA Inspections, Violations & Penalty Screener")
- `minPenalty` is now also applied server-side via the DOL `filter_object`, so `maxResults` counts qualifying records instead of raw records
- Violation-detail fetches now run with bounded concurrency (5 parallel) — large `includeViolations` runs are ~5× faster
- Dataset records are pushed in a single batched `pushData` call

#### Fixed (verified against the official DOL API User Guide + live API, June 10, 2026)

- **Request URL format**: `https://apiprod.dol.gov/v4/get/osha/{inspection,violation}/json` — the previous `/v4/dataset/osha_*` path did not exist and every real run would have failed
- **Authentication**: DOL v4 uses an `X-API-KEY` query parameter, not an `Authorization: Bearer` header
- **Filter operators**: v4 supports only `eq, neq, gt, lt, in, not_in, like` — `gte`/`lte` clauses replaced with inclusive-bound emulation (dates shifted by one day, penalty by one cent; client-side re-check stays authoritative)

#### Added

- `apiKey` input is now **optional**: falls back to the `DOL_API_KEY` secret environment variable, so end users need no login.gov/DOL account (DOL moved key registration behind login.gov)
- API key redaction in all error messages and logs (`X-API-KEY=***`)
- Exponential-backoff retry (1s → 32s, 5 attempts) on DOL API 429/5xx responses
- Page size raised to 1,000 (API allows up to 10,000 records / 5 MB per request)
- Local-run warning when `ACTOR_TEST_PAY_PER_EVENT` is not set, so PPE billing is never silently skipped during testing
- Store categories in actor metadata

### \[0.1.0] - 2026-06-08

#### Initial release

- Search 4M+ OSHA workplace inspection records via US DOL Enforcement API v4
- Filter by establishment name (partial match), state, NAICS code, SIC code, date range, and minimum penalty
- Optional per-citation violation detail (`includeViolations: true`) with CFR standard, gravity, penalty, and description
- Pay-per-event PPE billing: actor-start, inspection-record, violation-detail
- Push-then-charge ordering guarantees no charge for data not delivered
- Pagination support for result sets up to 10,000 records
- Structured JSON output with `schemaVersion` field for forward-compatibility