# FMCSA New-Registration Radar: Pre-Authority Carrier Alerts (`yungstentech/fmcsa-new-authority-radar`) Actor Watch your state(s), carrier operation type and fleet-size band for newly-registered FMCSA carriers: each new census registration arrives once as a deduped, contact-ready BD row (legal name, phone, email, address, fleet size). Detects new registrations (pre-authority), not authority activation. - **URL**: https://apify.com/yungstentech/fmcsa-new-authority-radar.md - **Developed by:** [Paul Mikulskis](https://apify.com/yungstentech) (community) - **Categories:** Lead generation, Agents, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $19.00 / filter watch-month This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README **FMCSA New-Registration Radar** watches the FMCSA Company Census for **newly-registered motor carriers** in the state(s) and operation type you choose, and delivers each one as a deduplicated business-development row with the fields the carrier filed: legal name, DBA, phone, email, address, operation type and fleet size. You name a territory once and put the actor on a daily Apify Schedule; each run diffs the census, delivers only carriers you have not seen before, and never re-shows one you already got. It runs inside your own Apify account, so you get API access, scheduling, integrations and monitoring for free, with nothing to log into and no key to manage. It is also callable as an MCP tool, so an agent can pull fresh carriers into a prospecting loop. It detects **new census registrations** (the roughly 21-day pre-authority window before a carrier's operating authority activates), not operating-authority activation itself. See "Terminology, plainly" below. ### What does FMCSA New-Registration Radar do? The [FMCSA Company Census File](https://data.transportation.gov/resource/az4n-8mr2.json) is the US-DOT open-data record of registered motor carriers, updated daily (Socrata metadata Update Frequency R/P1D; rowsUpdatedAt 2026-07-05). New carrier registrations arrive in a steady stream: roughly 380 per day nationally (11,421 carriers registered in the trailing 30 days, self-probed 2026-07-06), split 6,091 interstate to 5,321 intrastate over the same window (measured 2026-07-06). A newly-registered carrier is a new trucking company that, over the next few weeks, sets up insurance, files its BOC-3, and lines up freight factoring, so it is the moment freight-factoring and trucking-insurance desks want to reach it. This actor turns that census into a standing, territory-filtered watch. You define a filter once, put it on a schedule, and each run: 1. Queries the census for carriers whose `add_date` (registration date) falls in a rolling look-back window for your states and operation type. 2. Aggregates the feed by `dot_number`, so a carrier that filed several addresses is one alert, not several. 3. Compares the result against your filter's memory and delivers only the newly-registered carriers you have not seen before. 4. Optionally POSTs the new alerts to a webhook you choose. Every delivered row carries the phone and email the carrier filed with FMCSA. About 99.7% of new registrations carry both (11,392 of 11,421 in the trailing 30 days, measured 2026-07-06), so a delivered row is contactable straight from the source, without skip-tracing. ### Why use FMCSA New-Registration Radar? - **First contact in the pre-authority window.** Reach a new entrant carrier in the days after it registers, while it is still choosing an insurer and a factor, not after its authority is active and the competition has already called. - **Only your territory, deduplicated.** You watch one or a few states, get alerted once per DOT number from the day you start, and never see the historical back-catalog or a repeat. - **Contact-ready rows.** Each row is a business-development payload with the carrier's own filed phone and email, not a raw record you have to enrich. - **Verifiable.** Every alert row carries a SAFER carrier-snapshot link keyed on its DOT number, so you can confirm any carrier against FMCSA before you act on it. - **Self-serve and agent-native.** It runs in your own Apify account and is callable as an MCP tool, a form factor the email-list vendors of motor carrier alerts do not offer. ### How to use FMCSA New-Registration Radar 1. Open the **Input** tab and choose your **states** (2-letter USPS codes) and **carrier operation** (interstate, intrastate, or all). Interstate is the default and roughly halves the volume. 2. Optionally narrow with **minimum power units** or **fleet-size bands** to drop no-truck registrants, and leave **require contact fields** on so every delivered row is contactable. 3. Set a **filter name** (for example `tx-interstate`). This names the watch so its deduplication memory persists across scheduled runs. 4. Run it once. The first run establishes an uncharged **baseline** of the carriers already in scope and watches forward from that moment. It does not bill you for the back-catalog. 5. Put it on a daily **Schedule**. The census updates daily, so the honest latency is "within about a day of FMCSA posting it." 6. Set the run's **max total charge per run** high enough to cover the monthly watch fee (see Pricing). If it is too low, the run delivers nothing and tells you to raise it. #### Worked example Input (also the store default), a Texas interstate watch: ```json { "mode": "watch", "states": ["TX"], "carrierOperation": "interstate", "minPowerUnits": 1, "filterName": "tx-interstate", "maxAlertsPerRun": 50 } ```` The **first run** returns a single uncharged baseline row (BD fields null, the count is illustrative): ```json { "event_type": "baseline", "filterName": "tx-interstate", "billing": "uncharged", "add_date": null, "legal_name": null, "phone": null, "email_address": null, "source_url": "https://data.transportation.gov/resource/az4n-8mr2.json", "note": "Baseline established: 41 carrier(s) currently in scope are on file for this filter; watching forward for newly-registered carriers from today." } ``` A **later run**, once a new interstate carrier registers in Texas, returns one alert row (values illustrative, field names exact): ```json { "dot_number": "4213908", "legal_name": "LONE STAR HAULING LLC", "dba_name": null, "phone": "2145550137", "email_address": "dispatch@lonestarhauling.example", "phy_street": "1420 INDUSTRIAL BLVD", "phy_city": "DALLAS", "phy_state": "TX", "phy_zip": "75207", "carrier_mailing_state": "TX", "carrier_operation": "Interstate", "power_units": 2, "total_drivers": 2, "fleetsize": "A", "status_code": "A", "add_date": "2026-07-03", "source_url": "https://safer.fmcsa.dot.gov/query.asp?searchtype=ANY&query_type=queryCarrierSnapshot&query_param=USDOT&query_string=4213908", "checked_at": "2026-07-04T09:12:00.000Z", "filterName": "tx-interstate", "event_type": "new-carrier", "billing": "included-tier", "note": null } ``` You can download the dataset in JSON, CSV, Excel or HTML. #### Demo dataset A real report-mode output from this actor is public, so you can see actual delivered rows before you run anything: 799 interstate carriers that registered in Texas in June 2026 (one flat row per carrier, exact field names as above), plus one cohort-summary row. No login or API token needed: - Browse it: https://api.apify.com/v2/datasets/cs8PupeaEpICmFbaW/items?format=html - Raw JSON: https://api.apify.com/v2/datasets/cs8PupeaEpICmFbaW/items?format=json ### Output data Each **new-carrier alert row** carries these fields, mapped straight from the census with no enrichment: | Field | Meaning | |---|---| | `dot_number` | USDOT number: the carrier identity and the dedupe key. | | `legal_name`, `dba_name` | Legal name and trade name. | | `phone`, `email_address` | The phone and email the carrier filed with FMCSA (see "Contacts, plainly"). | | `phy_street`, `phy_city`, `phy_state`, `phy_zip` | Physical address. | | `carrier_mailing_state` | Mailing state. | | `carrier_operation` | Decoded label: `Interstate`, `Intrastate Non-Hazmat`, or `Intrastate Hazmat`. | | `power_units`, `total_drivers` | Trucks and drivers the carrier reported at registration. | | `fleetsize`, `status_code` | Census fleet-size band code and status code. | | `add_date` | Registration date, normalized to ISO `YYYY-MM-DD`. | | `source_url` | SAFER carrier-snapshot link keyed on the DOT number, to re-verify the carrier. | | `checked_at` | When this run read the census. | | `filterName` | The named watch that produced the row. | | `event_type` | `new-carrier` for an alert; also `baseline`, `digest-no-new`, `truncation-marker`, `billing-blocked` for uncharged status rows, and `report-carrier` / `cohort-report-summary` in report mode. | | `billing` | How the row was billed: `included-tier`, `volume-tier`, `dry-run`, `uncharged`, or `cohort-report`. | | `note` | A human message on status rows; null on alert rows. | Status rows (`baseline`, `digest-no-new`, `truncation-marker`, `billing-blocked`) carry null BD fields and an explanatory `note`, and are never charged. A `digest-no-new` row is returned when a run finds nothing new; a `truncation-marker` names how many alerts a cap withheld; a `billing-blocked` row explains that the run's max charge was below the watch fee. **Report mode** returns one flat row **per carrier** (`event_type` `report-carrier`), each carrying the same BD fields and field names as an alert row, followed by exactly one **summary row** (`event_type` `cohort-report-summary`). The summary row has null BD fields and carries the cohort header: `filterDescription`, `period`, a `summary` (total count, counts by state, counts by operation), the `sources`, and a human `note`. Every report row is `billing` `cohort-report`, and the whole report is billed once at $15. Because each carrier is its own row, a report downloads cleanly to CSV/Excel and renders one carrier per line in the Output table. ### Modes - **watch** (default): the standing, deduplicated filter-watch described above. - **report**: a one-off cohort of every carrier registered in your state(s) and operation type over an `add_date` period (`period` as `YYYY-MM` or `YYYY-MM..YYYY-MM`), billed once at $15. Use it for the recent back-catalog or a forwardable territory snapshot. - **unwatch**: forget a saved filter's memory. No charge. - **list-events**: replay a filter's delivered-alert history. No charge. - **dryRun** (any mode): fetch and diff but return at most 5 preview rows, charge nothing, and touch no memory. Use it to sanity-check a filter before scheduling. ### Pricing This actor is pay-per-event. Actor start is free. - **Filter watch-month, $19.00** per named filter per calendar month, charged on the first run of the month that completes a successful query on a fresh feed. Your account's **first calendar month is free** (alerts still bill during it). Baseline and re-baseline runs are never charged, and the fee is deferred while the feed is stale. - **New-carrier alert, $0.00001** for the first 300 delivered per filter-month (Apify's required event minimum, displayed as $0.01 / 1,000 and effectively included in the watch fee), then **$0.03** each beyond the 300th. The row is pushed before it is charged. - **Cohort report, $15.00** per report-mode run; a failed query charges nothing. #### What a real state costs The 300 effectively included alerts cover a narrowed filter but are exceeded by the largest single-state interstate filters. The Apify event floor adds at most $0.003 across those first 300 alerts, so it does not change the buyer math. Texas interstate ran about 670 new registrations in 30 days (measured 2026-07-06), so a Texas interstate watch is the $19 watch fee plus roughly 370 alerts beyond the tier at $0.03, about $11, for roughly **$30 per month all-in**. Across the biggest single states the all-in lands roughly **$20 to $30 per month**: Illinois (322 registrations in 30 days) and Georgia (319) sit just under $20, Florida (421) about $23, California (610) about $28, Texas (670) about $30, all measured 2026-07-06. A one- or two-state filter is the intended use; a national filter is deliberately not the wedge here and would accrue far more volume, so two monthly guards (`maxAlertRowsPerMonth`, default 1000, and `maxMonthlySpendUsd`, default $50) stop charging and switch to uncharged marker rows before a broad filter can surprise-bill. #### Set your per-run max charge correctly The $19 watch fee lands on a single run, so you must set that run's **"max total charge per run"** high enough to cover it. With `maxAlertsPerRun` at its default of 50, a single run bills at most $19 plus 50 alerts at $0.03 ($1.50), so $20.50; set the run's max total charge to at least **$21**, and $25 leaves headroom. If you set it below $19, the actor does not silently under-deliver: the run delivers nothing, advances no memory, and pushes one uncharged `billing-blocked` row telling you to raise the cap and rerun. You then receive that month's alerts on the rerun once the fee bills. ### Baseline-forward behavior Alerts begin from the day you start watching a filter. The first run seeds the carriers already in scope (uncharged) and watches forward, so you are never billed for the historical back-catalog. If you **widen a saved filter** under the same name (add a state, drop the power-unit floor), the actor re-baselines it, again with no back-catalog charge. For the recent back-catalog, use **report mode**. ### Terminology, plainly This actor reads the FMCSA Company Census registration delta. It detects **newly-registered** carriers in the roughly 21-day **pre-authority** window, and does not read operating-authority status, which lives in FMCSA's L\&I system and is a possible future enrichment. The copy here says "newly registered" and "pre-authority" throughout; it does not claim to detect an operating-authority grant. ### Contacts, plainly The `phone` and `email_address` on each row are the phone and email the carrier filed with FMCSA, taken straight from the public census row. About 99.7% of new registrations carry both (measured 2026-07-06); a 3,000-row sample found phones about 99.8% well-formed 10-digit numbers, emails near-unique per carrier (0.3% shared across more than one carrier), and about 73% on free-mail domains consistent with owner-operators (probes/contact-quality.md, 2026-07-06). FMCSA carries no role field, so these are the carrier's own filed contacts, not verified "owner" contacts. ### Compliance Rows are public FMCSA registration records; any outreach you send using them must comply with the TCPA and CAN-SPAM. That compliance duty is yours as the sender, and is standard for any lead product. ### FAQ and support - **Where does the data come from?** The FMCSA Company Census File on the US-DOT open-data portal (`data.transportation.gov/resource/az4n-8mr2`). It is a public carrier record; the actor reads it keyless, with no login. - **What is the latency?** The census updates daily, so the honest promise is "within about a day of FMCSA posting a registration," not real-time. - **Is this the same as authority data?** No. People searching for "new authority leads" usually mean this pre-authority registration moment, but the actor reads census registrations, not L\&I authority grants. Reaching a carrier at registration is earlier than reaching it once authority is active. - **Is it legal and compliant?** It reads a public government record and redistributes public registration facts. It is registry information, not advice; your outreach compliance is described under Compliance above. - **Can I watch more states or get authority status?** Up to 10 states per filter today. An L\&I operating-authority join is a possible future enrichment. Use the Issues tab to request one or report a problem. # Actor input Schema ## `mode` (type: `string`): What this run does. watch: establish (first run) or advance a standing filter-watch and deliver newly-registered carriers. unwatch: forget a saved filter's memory. list-events: replay this filter's delivered-alert history. report: one-off newly-registered cohort report for the state(s) and add\_date period you name (billed once, $15). ## `states` (type: `array`): Which 2-letter USPS state codes to watch, matched against the carrier's physical state (and optionally its mailing state). At least one state is required for a watch (up to 10). Report mode may leave this empty for a nationwide cohort. ## `carrierOperation` (type: `string`): Which carrier operation type to watch. interstate (census code A) is the factoring/insurance buyer's default and roughly halves the firehose; intrastate covers codes B and C; all includes every operation type. ## `minPowerUnits` (type: `integer`): Drop carriers that registered fewer than this many power units (trucks/tractors). 0 keeps every registrant; 1 filters out no-truck registrations. ## `fleetSizeBand` (type: `array`): Optional census fleetsize band codes to keep (0 and A through Z, smallest to largest). Empty keeps all bands. Use this to restrict to larger fleets. ## `requireContact` (type: `boolean`): Drop carriers that filed neither a phone nor an email with FMCSA. On by default: about 99.7% of new registrations carry both, so this rarely fires but guarantees every delivered row is contactable. ## `matchMailingState` (type: `boolean`): When on, a carrier matches your states if EITHER its physical state or its mailing state is in the list. Off by default (physical state only). ## `maxAlertsPerRun` (type: `integer`): Hard cap on new-carrier alerts delivered and charged in a single run. Any overflow is not added to the seen-set and redelivers on the next run, and a truncation marker names how many were withheld. Bounds a catch-up run. ## `maxAlertRowsPerMonth` (type: `integer`): Per-account monthly ceiling on delivered alerts, counted across ALL of your filters this month (not per filter). Past it, the run stops charging and switches to uncharged marker rows (naming how many were withheld) instead of billing further. Guards against a slow national accrual. ## `maxMonthlySpendUsd` (type: `integer`): Product-level cap on cumulative volume-tier charges per filter-month. Once reached, the run stops charging volume-tier alerts and pushes uncharged marker rows instead. Complements the monthly alert-count ceiling; whichever trips first stops charging. ## `safetyDays` (type: `integer`): How many days back the watch query always re-scans (on top of your last-seen watermark) to absorb rows FMCSA posts late. Larger is safe: the DOT-number seen-set dedupes, so a wider look-back never double-alerts, and the query stays cheap. ## `webhookUrl` (type: `string`): Optional https URL that receives a POST with the new alerts after each run. Best-effort alerting only: the dataset is the durable record. If you need to verify the caller, put a secret token in the URL yourself. ## `filterName` (type: `string`): Names this filter within your account so its deduplication memory persists across scheduled runs. Lowercased and restricted to letters, digits and hyphens (1 to 40 characters). Changing a saved filter's scope under the same name re-baselines it (no back-catalog charge). ## `period` (type: `string`): Report mode only. The registration-date window for the cohort report, as YYYY-MM (a single month) or YYYY-MM..YYYY-MM (an inclusive range), for example 2026-06 or 2026-04..2026-06. ## `dryRun` (type: `boolean`): When true, fetch, aggregate and diff but return at most 5 preview rows, charge nothing and touch no filter memory. Use it to sanity check your filter before scheduling. ## Actor input object example ```json { "mode": "watch", "states": [ "TX" ], "carrierOperation": "interstate", "minPowerUnits": 1, "requireContact": true, "matchMailingState": false, "maxAlertsPerRun": 50, "maxAlertRowsPerMonth": 1000, "maxMonthlySpendUsd": 50, "safetyDays": 3, "filterName": "tx-interstate", "dryRun": false } ``` # Actor output Schema ## `newCarrierAlerts` (type: `string`): No description ## `runSummary` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "states": [ "TX" ], "minPowerUnits": 1, "maxAlertsPerRun": 50, "maxAlertRowsPerMonth": 1000, "maxMonthlySpendUsd": 50, "safetyDays": 3, "filterName": "tx-interstate" }; // Run the Actor and wait for it to finish const run = await client.actor("yungstentech/fmcsa-new-authority-radar").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "states": ["TX"], "minPowerUnits": 1, "maxAlertsPerRun": 50, "maxAlertRowsPerMonth": 1000, "maxMonthlySpendUsd": 50, "safetyDays": 3, "filterName": "tx-interstate", } # Run the Actor and wait for it to finish run = client.actor("yungstentech/fmcsa-new-authority-radar").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "states": [ "TX" ], "minPowerUnits": 1, "maxAlertsPerRun": 50, "maxAlertRowsPerMonth": 1000, "maxMonthlySpendUsd": 50, "safetyDays": 3, "filterName": "tx-interstate" }' | apify call yungstentech/fmcsa-new-authority-radar --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=yungstentech/fmcsa-new-authority-radar", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "FMCSA New-Registration Radar: Pre-Authority Carrier Alerts", "description": "Watch your state(s), carrier operation type and fleet-size band for newly-registered FMCSA carriers: each new census registration arrives once as a deduped, contact-ready BD row (legal name, phone, email, address, fleet size). Detects new registrations (pre-authority), not authority activation.", "version": "0.0", "x-build-id": "DIxUsmlg67e9I1AhY" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/yungstentech~fmcsa-new-authority-radar/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-yungstentech-fmcsa-new-authority-radar", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/yungstentech~fmcsa-new-authority-radar/runs": { "post": { "operationId": "runs-sync-yungstentech-fmcsa-new-authority-radar", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/yungstentech~fmcsa-new-authority-radar/run-sync": { "post": { "operationId": "run-sync-yungstentech-fmcsa-new-authority-radar", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "mode": { "title": "Mode", "enum": [ "watch", "unwatch", "list-events", "report" ], "type": "string", "description": "What this run does. watch: establish (first run) or advance a standing filter-watch and deliver newly-registered carriers. unwatch: forget a saved filter's memory. list-events: replay this filter's delivered-alert history. report: one-off newly-registered cohort report for the state(s) and add_date period you name (billed once, $15).", "default": "watch" }, "states": { "title": "States", "maxItems": 10, "type": "array", "description": "Which 2-letter USPS state codes to watch, matched against the carrier's physical state (and optionally its mailing state). At least one state is required for a watch (up to 10). Report mode may leave this empty for a nationwide cohort.", "items": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "DC", "PR", "VI", "GU", "AS", "MP" ] } }, "carrierOperation": { "title": "Carrier operation", "enum": [ "interstate", "intrastate", "all" ], "type": "string", "description": "Which carrier operation type to watch. interstate (census code A) is the factoring/insurance buyer's default and roughly halves the firehose; intrastate covers codes B and C; all includes every operation type.", "default": "interstate" }, "minPowerUnits": { "title": "Minimum power units", "minimum": 0, "type": "integer", "description": "Drop carriers that registered fewer than this many power units (trucks/tractors). 0 keeps every registrant; 1 filters out no-truck registrations.", "default": 0 }, "fleetSizeBand": { "title": "Fleet-size bands (optional)", "type": "array", "description": "Optional census fleetsize band codes to keep (0 and A through Z, smallest to largest). Empty keeps all bands. Use this to restrict to larger fleets.", "items": { "type": "string", "enum": [ "0", "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z" ] } }, "requireContact": { "title": "Require contact fields", "type": "boolean", "description": "Drop carriers that filed neither a phone nor an email with FMCSA. On by default: about 99.7% of new registrations carry both, so this rarely fires but guarantees every delivered row is contactable.", "default": true }, "matchMailingState": { "title": "Also match mailing state", "type": "boolean", "description": "When on, a carrier matches your states if EITHER its physical state or its mailing state is in the list. Off by default (physical state only).", "default": false }, "maxAlertsPerRun": { "title": "Max alerts per run", "minimum": 1, "maximum": 500, "type": "integer", "description": "Hard cap on new-carrier alerts delivered and charged in a single run. Any overflow is not added to the seen-set and redelivers on the next run, and a truncation marker names how many were withheld. Bounds a catch-up run.", "default": 50 }, "maxAlertRowsPerMonth": { "title": "Max alert rows per month", "minimum": 300, "type": "integer", "description": "Per-account monthly ceiling on delivered alerts, counted across ALL of your filters this month (not per filter). Past it, the run stops charging and switches to uncharged marker rows (naming how many were withheld) instead of billing further. Guards against a slow national accrual.", "default": 1000 }, "maxMonthlySpendUsd": { "title": "Max monthly spend (USD)", "minimum": 1, "type": "integer", "description": "Product-level cap on cumulative volume-tier charges per filter-month. Once reached, the run stops charging volume-tier alerts and pushes uncharged marker rows instead. Complements the monthly alert-count ceiling; whichever trips first stops charging.", "default": 50 }, "safetyDays": { "title": "Look-back safety days", "minimum": 0, "maximum": 30, "type": "integer", "description": "How many days back the watch query always re-scans (on top of your last-seen watermark) to absorb rows FMCSA posts late. Larger is safe: the DOT-number seen-set dedupes, so a wider look-back never double-alerts, and the query stays cheap.", "default": 3 }, "webhookUrl": { "title": "Webhook URL (optional)", "type": "string", "description": "Optional https URL that receives a POST with the new alerts after each run. Best-effort alerting only: the dataset is the durable record. If you need to verify the caller, put a secret token in the URL yourself." }, "filterName": { "title": "Filter name", "type": "string", "description": "Names this filter within your account so its deduplication memory persists across scheduled runs. Lowercased and restricted to letters, digits and hyphens (1 to 40 characters). Changing a saved filter's scope under the same name re-baselines it (no back-catalog charge).", "default": "default" }, "period": { "title": "Report period (report mode)", "type": "string", "description": "Report mode only. The registration-date window for the cohort report, as YYYY-MM (a single month) or YYYY-MM..YYYY-MM (an inclusive range), for example 2026-06 or 2026-04..2026-06." }, "dryRun": { "title": "Dry run (preview, no charge)", "type": "boolean", "description": "When true, fetch, aggregate and diff but return at most 5 preview rows, charge nothing and touch no filter memory. Use it to sanity check your filter before scheduling.", "default": false } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```