# Early Vote & Mail Ballot Tracker — County Turnout & Results (`shelvick/early-vote-tracker`) Actor County-level US election data in one sweep: daily early-vote & mail-ballot returns by county, party, method and day, voter-registration statistics with history, and county results history 2000-2024. Honest per-state coverage labels; built for forecasting and analysis agents. - **URL**: https://apify.com/shelvick/early-vote-tracker.md - **Developed by:** [Scott Helvick](https://apify.com/shelvick) (community) - **Categories:** Business, Developer tools, News - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $4.25 / 1,000 county data row (standard)s This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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 ## Early Vote & Mail Ballot Tracker Election-forecasting and political-analysis agents need county-level early-vote and mail-ballot numbers that no training corpus can contain — and today those numbers live in fifty different state file formats. This Actor is an **early vote tracker** that returns daily **mail ballot returns by county**, **voter registration statistics by county and party**, and **county election results 2000–2024** as one normalized sweep, with honest per-state coverage labels. ### What this does - **Early vote & mail ballots (daily).** County × party × method returns for covered states — **daily absentee ballot counts**, mail ballots requested / returned / accepted, and early in-person votes, one cumulative snapshot per day so you get the returns time series, not just today's number. Current-cycle files light up as each state publishes them; prior-cycle archives are there to baseline against. - **Voter registration by county and party.** County-level registration statistics — registered voters per county × party — as a current snapshot plus the monthly/weekly history where the state publishes it. In no-party-registration states only a `TOTAL` row exists and the record says party breakdown is omitted by law, not missing. - **County election results history.** The **county-level presidential results** panel 2000–2024 plus Senate 2022, keyed by 5-digit FIPS — a `county-level presidential results API` behind the same schema as the fresh data. Alaska's house-district reporting is kept honest (keyed to district, not force-mapped to a county). - **One normalized schema across every source.** Every state source is a different parser; the output is one unified row shape discriminated by `dataset`, so an agent sums party keys and joins FIPS the same way in every state. - **Honest coverage, never a silent empty.** Every requested state × dataset slice that is not live comes back as a labeled coverage row (`not_covered`, `in_season_pending`, `gateway_deferred`, `archive_only`, `failed`), and the run's `COVERAGE` key-value record always carries per-slice delivered counts and reasons. - **Use cases:** feed a daily early-vote model with fresh county × party × method returns during the voting window; baseline this cycle's mail-ballot returns against the prior cycle's same-day archive; pull the full county presidential panel 2000–2024 to train or validate a county-level model; track registration drift by county and party between snapshots; assemble a single fresh-plus-historic county election dataset without stitching fifty state portals together. ### Why daily freshness matters The demand this is built for is a pipeline that re-runs *daily* during the Sept–Nov voting window. Daily early-vote counts are **post-training-cutoff by construction** — today's ballots-returned number cannot be in any model's training data, so an agent that needs it *must* call a live tool. That is the whole thesis: freshness a static corpus can't match. The expensive, brittle part is that every state ships its numbers differently — one state's aggregate CSV, another's tab-delimited text, a third's open-data query, a fourth's spreadsheet. Assembling county × party × method returns across states, day after day, and keeping the schema stable while the underlying files churn mid-season is exactly the work you don't want inside your model. This Actor is that assembly layer: the slow, walled, format-churning sources are refreshed behind an index, and your call is a fast sweep over normalized rows. And it's honest about the edges. A source that only publishes during an active election, a state that's behind a bot wall, a results panel that doesn't exist at the county level — each comes back as a *labeled* row, so your pipeline can branch on coverage instead of guessing whether an empty result means "no data" or "no ballots." A smaller map that tells the truth beats a bigger one that returns silent zeros. ### How it compares to raw sources and static datasets | Approach | County-level | Fresh daily in-season | One schema across states | Honest coverage labels | |---|---|---|---|---| | Individual state portals / files | Yes | Varies | No (per-state formats) | No | | Static county election datasets | Yes | No (historic only) | Within one dataset | N/A | | National exit-poll / topline feeds | No (state/national) | Sometimes | No | No | | **Early Vote & Mail Ballot Tracker** | **Yes (FIPS)** | **Yes** | **Yes** | **Yes** | The bet: multi-jurisdiction assembly behind one schema, plus daily freshness and honest coverage, is worth more to a forecasting workflow than any single state portal scraped in isolation or any snapshot dataset frozen at last cycle. ### Input | Field | Type | Required | Default | Description | |---|---|---|---|---| | `datasets` | array | | all three | Which datasets to sweep: any of `early_vote`, `registration`, `results`. Empty = all three. Each is billed only for the county rows it returns. | | `states` | array | | all covered | Two-letter postal codes, e.g. `["NC","FL","PA"]`. Empty = every covered state for each requested dataset. A requested-but-uncovered state returns a labeled coverage row, never a silent empty. | | `dateFrom` | string | | — | ISO `YYYY-MM-DD`, inclusive. Bounds `early_vote` snapshot dates and `registration` as-of dates. Ignored for `results`. | | `dateTo` | string | | — | ISO `YYYY-MM-DD`, inclusive upper bound for `early_vote` / `registration`. Ignored for `results`. | | `counties` | array | | all | 5-digit FIPS filter, e.g. `["37183"]` (Wake County, NC). Empty = all counties. FIPS is the county key across every dataset; a single-county filter turns the sweep into a targeted lookup. | | `resultsYears` | array | | all | Year filter for `results`, e.g. `["2020","2024"]` (numeric strings are coerced). Applies only to `results`. | | `electionId` | string | | — | Optional: pin `early_vote` to one election by election-day date, e.g. `"2024-11-05"`. Empty = every election whose daily snapshots fall in the date window. | | `maxRows` | integer | | `200000` | Safety cap on total county data rows returned **and** billed per run. Coverage rows are free and don't count. The per-run max-charge cap is the hard budget stop. | ### Output One dataset item per row — a unified superset discriminated by `dataset`; dataset-specific fields are populated for that shape and `null` otherwise. An `early_vote` row (daily mail-ballot returns, `status: "ok"`): ```json { "dataset": "early_vote", "state": "NC", "status": "ok", "county_fips": "37183", "county": "Wake", "party": "DEM", "party_detail": null, "election_id": "2024-11-05", "election_name": "2024 General Election", "date": "2024-10-28", "method": "mail", "ballots_returned": 12987, "ballots_accepted": 12750, "in_person_votes": null, "source": "State Board of Elections (county absentee counts)", "as_of": "2024-10-28 11:00AM", "field_notes": [] } ```` A `registration` row (`registered` per county × party): ```json { "dataset": "registration", "state": "FL", "status": "ok", "county_fips": "12086", "county": "Miami-Dade", "party": "REP", "snapshot_date": "2026-07-01", "registered": 462180, "source": "State Division of Elections (party affiliation by county)", "field_notes": [] } ``` A `results` row (county presidential history): ```json { "dataset": "results", "state": "NC", "status": "ok", "county_fips": "37183", "county": "Wake", "year": 2024, "office": "US PRESIDENT", "candidate": "KAMALA D HARRIS", "votes": 340199, "total_votes": 621988, "field_notes": [] } ``` A coverage row (requested slice not live — free, never billed): ```json { "dataset": "results", "state": "TX", "status": "gateway_deferred", "coverage_note": "This state's source is not integrated yet for this dataset.", "field_notes": [] } ``` Key fields: `status` (row outcome — only `ok` bills), `party` (normalized DEM/REP/UNA/OTH/TOTAL key, safe to sum), `party_detail` (the source's own party code verbatim where it emits one), and `field_notes` (why a field is structurally absent — e.g. a count column a state doesn't publish, or party omitted by law). Each run also writes a `COVERAGE` key-value record listing every requested slice with its delivered row count and reason — authoritative per run, and coverage expands over time. ### Example Sweep this cycle's early-vote returns plus the county presidential history for three states: ```bash curl -X POST "https://api.apify.com/v2/acts/shelvick~early-vote-tracker/run-sync-get-dataset-items?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"datasets":["early_vote","results"],"states":["NC","FL","PA"],"dateFrom":"2026-09-01","dateTo":"2026-11-03","resultsYears":["2020","2024"]}' ``` Returns the daily early-vote rows in the date window plus the 2020 and 2024 county presidential rows for each state, with a labeled coverage row for anything requested that isn't live yet. ### Calling from an AI agent Agents are the primary customer. Three ways to call it: - **Apify MCP server** (`mcp.apify.com`): expose `shelvick/early-vote-tracker` as a tool; the input schema and per-field descriptions are advertised to the model, so an agent can construct a valid sweep from the tool description alone. Pay per call via x402 USDC on Base or Skyfire managed tokens. - **Apify SDK (Python):** ```python from apify_client import ApifyClient client = ApifyClient("YOUR_TOKEN") run = client.actor("shelvick/early-vote-tracker").call( run_input={"datasets": ["early_vote"], "states": ["NC", "FL", "PA"], "dateFrom": "2026-09-01", "dateTo": "2026-11-03"} ) for row in client.dataset(run["defaultDatasetId"]).iterate_items(): print(row["state"], row["county"], row["party"], row["date"], row.get("ballots_returned")) ``` - **REST:** `POST /v2/acts/shelvick~early-vote-tracker/run-sync-get-dataset-items` for a synchronous sweep, or the async `/runs` endpoint plus polling for a large national pull. ### Pricing Pay-per-event, billed only on success. Each **county data row** is charged once, after it is pushed to the dataset (push-then-charge), metered per run. The rate depends on what kind of row it is: - **Live-tracking rows** (early-vote and registration) bill at a standard per-row rate, and a **lower volume rate applies automatically** to rows beyond a per-run threshold — large daily sweeps get cheaper per row, by design. - **Results-history rows** bill at a flat rate lower than live-tracking rows, so pulling the full historical panel stays inexpensive. Coverage rows (`not_covered`, `in_season_pending`, `gateway_deferred`, `archive_only`, `failed`) are returned but **never charged**, and a run stopped by your budget cap bills only the rows actually delivered — every charge is clamped to your remaining budget in code, so a broad national sweep can't produce a runaway bill. A single platform run-start fee applies per run. See the **Pricing** tab on this Store page for the current per-row rates, the volume threshold, and any active subscriber discounts. ### Behavior - **Row statuses:** `ok` (a billed county data row); `not_covered` (state/dataset not in scope yet); `in_season_pending` (source published only during an active election — e.g. some early-vote files off-season); `gateway_deferred` (a bot-walled source not yet integrated); `archive_only` (historical only, not currently refreshing); `failed` (the backing data could not be reached for that slice). Only `ok` bills. - **Never a false empty.** If the backing service is unreachable or a slice errors, that slice comes back as a `failed` row with an error string and the run is marked failed — the sweep never silently returns nothing. Zero-row live slices are explained in the `COVERAGE` manifest, and an empty slice inside an active election window raises a diagnostic rather than passing quietly. - **Run-level failures (rare):** input validation only — states must be 2-letter codes, counties 5-digit FIPS, dates ISO `YYYY-MM-DD`. - **Latency:** a single-county or single-state sweep returns in a few seconds; a broad national sweep (tens of thousands of rows) is paged and pushed incrementally and scales with row count. `maxRows` and the per-run max-charge cap bound the largest pulls. ### FAQ **Do I get today's ballot counts, or last week's?** The latest snapshot the source has published, per state. In-season, states that publish daily are refreshed daily; each day's cumulative snapshot is retained, so a date range gives you the returns time series, not just the newest figure. **What does a `null` party or count column mean?** It's structural, not a gap. In no-party-registration states party is `TOTAL`-only and omitted by law; a count column a state doesn't publish is left `null` rather than duplicated from another column. The row's `field_notes` says which and why. **Is the results data official?** It's the standard county-level returns panel — president 2000–2024 and Senate 2022 — normalized to FIPS. County-level Governor and House panels don't exist as a multi-cycle county series, and the coverage record says so rather than inventing them. **How do I keep a national sweep from over-charging?** Set `maxRows` and the run's max-charge cap. Charges are clamped to your remaining budget, and dropped rows are free and explained in the `COVERAGE` record. **Which states are covered?** Read the run's `COVERAGE` record — it's authoritative per run. Early-vote coverage centers on the states that publish clean daily county files and expands as more come online; registration covers several partisan-registration states; results covers all 50 states for the county presidential panel. ### What this doesn't do - **No individual voter data.** Aggregate county rows only — county × party × method counts, never a voter file, never a name, address, or ballot-level record. This is a deliberate design stance, not a coverage gap: where a source is individual-level, aggregation happens before anything is stored, and raw individual records are never retained or served. - **No forecasting or modeling.** Raw normalized returns and the archived baseline series — the projection, turnout model, or seat forecast is yours to build on top. - **No real-time streaming or monitoring.** A point-in-time sweep of the latest ingested data, not a live feed or a change-watcher. - **No individual candidate-finance, precinct-level, or exit-poll data.** County is the finest grain; precinct and sub-county breakdowns are out of scope. - **Not a 50-state guarantee for the fresh datasets.** Early-vote and registration coverage is honest and expanding; uncovered slices return labeled coverage rows. For a turnout model or seat projection, build it on top of these rows — this Actor is the fresh-data primitive, not the model. For individual voter registration records or a voter file, this Actor deliberately does not serve them; use an appropriately-authorized voter-data provider. For precinct-level or ballot-level returns, use a precinct-returns source — county is the finest grain here. *** Design notes: [www.scotthelvick.com/tools/early-vote-tracker](https://www.scotthelvick.com/tools/early-vote-tracker) # Actor input Schema ## `datasets` (type: `array`): Which county-level election datasets to sweep. Any combination of: early\_vote (daily early-vote & mail-ballot returns by county × party × method × day), registration (voter-registration statistics by county × party, current + history), results (county results history — president 2000-2024 + Senate 2022). Empty = all three. Billing is per county row returned; results rows bill at a lower rate, and a volume rate applies to large sweeps (see the Pricing tab). ## `states` (type: `array`): Two-letter US state postal codes to scope the sweep, e.g. \["NC","FL","PA"]. Empty = all covered states per dataset. Early-vote coverage: NC, FL, PA (CO lights up in-season). Registration: CA, PA, FL, CO, KY, NC, OR. Results: all 50 states + DC. A requested state not yet covered returns a labeled coverage row (not\_covered / gateway\_deferred / in\_season\_pending) — never a silent empty, never charged. The run's COVERAGE record is authoritative. ## `dateFrom` (type: `string`): Start date (ISO YYYY-MM-DD, inclusive) bounding early\_vote returns (by snapshot date) and registration statistics (by 'as of' date). Ignored for results (use resultsYears). Empty = no lower bound. Example: "2026-09-01". ## `dateTo` (type: `string`): End date (ISO YYYY-MM-DD, inclusive) bounding early\_vote returns and registration statistics. Ignored for results. Empty = no upper bound. Example: "2026-11-03". ## `counties` (type: `array`): Filter to specific counties by 5-digit FIPS code, e.g. \["37183"] (Wake County, NC). Empty = all counties in the requested states. FIPS is the county key across every dataset; a single-county filter turns the sweep into a targeted lookup over the same index. ## `resultsYears` (type: `array`): Filter the results dataset to specific election years, e.g. \["2020","2024"]. Applies only to results (county president 2000, 2004, 2008, 2012, 2016, 2020, 2024; Senate 2022). Empty = all available years. Ignored for early\_vote / registration. ## `electionId` (type: `string`): Optional: pin the early\_vote sweep to one election, keyed by election-day date (ISO YYYY-MM-DD), e.g. "2024-11-05" (2024 General) or "2026-11-03" (2026 General). Empty = every election whose daily snapshots fall in the dateFrom / dateTo window. Ignored for registration / results. ## `maxRows` (type: `integer`): Safety cap on the total number of county data rows returned AND billed in one run — protects a broad national sweep from an unbounded charge. Coverage rows (not\_covered, etc.) are free and do not count against this. Default 200000 (a full national results-history sweep is ~110k rows); the per-run maximum charge (maxTotalChargeUsd) is the hard budget stop. ## Actor input object example ```json { "datasets": [ "early_vote", "registration", "results" ], "states": [ "NC" ], "dateFrom": "2026-01-01", "dateTo": "2026-11-03", "counties": [ "37183" ], "resultsYears": [ "2020", "2024" ], "maxRows": 200000 } ``` # Actor output Schema ## `results` (type: `string`): County-level rows for this sweep (early-vote returns, registration statistics, and results history, plus labeled coverage rows for anything requested but not live). # 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 = { "datasets": [ "early_vote", "registration", "results" ], "states": [ "NC" ], "dateFrom": "2026-01-01", "dateTo": "2026-11-03", "counties": [ "37183" ], "resultsYears": [ "2020", "2024" ], "electionId": "" }; // Run the Actor and wait for it to finish const run = await client.actor("shelvick/early-vote-tracker").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 = { "datasets": [ "early_vote", "registration", "results", ], "states": ["NC"], "dateFrom": "2026-01-01", "dateTo": "2026-11-03", "counties": ["37183"], "resultsYears": [ "2020", "2024", ], "electionId": "", } # Run the Actor and wait for it to finish run = client.actor("shelvick/early-vote-tracker").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 '{ "datasets": [ "early_vote", "registration", "results" ], "states": [ "NC" ], "dateFrom": "2026-01-01", "dateTo": "2026-11-03", "counties": [ "37183" ], "resultsYears": [ "2020", "2024" ], "electionId": "" }' | apify call shelvick/early-vote-tracker --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=shelvick/early-vote-tracker", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Early Vote & Mail Ballot Tracker — County Turnout & Results", "description": "County-level US election data in one sweep: daily early-vote & mail-ballot returns by county, party, method and day, voter-registration statistics with history, and county results history 2000-2024. Honest per-state coverage labels; built for forecasting and analysis agents.", "version": "0.0", "x-build-id": "0WqGAByl5p2c9Tf8B" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/shelvick~early-vote-tracker/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-shelvick-early-vote-tracker", "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/shelvick~early-vote-tracker/runs": { "post": { "operationId": "runs-sync-shelvick-early-vote-tracker", "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/shelvick~early-vote-tracker/run-sync": { "post": { "operationId": "run-sync-shelvick-early-vote-tracker", "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": { "datasets": { "title": "Datasets", "type": "array", "description": "Which county-level election datasets to sweep. Any combination of: early_vote (daily early-vote & mail-ballot returns by county × party × method × day), registration (voter-registration statistics by county × party, current + history), results (county results history — president 2000-2024 + Senate 2022). Empty = all three. Billing is per county row returned; results rows bill at a lower rate, and a volume rate applies to large sweeps (see the Pricing tab).", "items": { "type": "string" } }, "states": { "title": "States", "type": "array", "description": "Two-letter US state postal codes to scope the sweep, e.g. [\"NC\",\"FL\",\"PA\"]. Empty = all covered states per dataset. Early-vote coverage: NC, FL, PA (CO lights up in-season). Registration: CA, PA, FL, CO, KY, NC, OR. Results: all 50 states + DC. A requested state not yet covered returns a labeled coverage row (not_covered / gateway_deferred / in_season_pending) — never a silent empty, never charged. The run's COVERAGE record is authoritative.", "items": { "type": "string" } }, "dateFrom": { "title": "Date from", "type": "string", "description": "Start date (ISO YYYY-MM-DD, inclusive) bounding early_vote returns (by snapshot date) and registration statistics (by 'as of' date). Ignored for results (use resultsYears). Empty = no lower bound. Example: \"2026-09-01\"." }, "dateTo": { "title": "Date to", "type": "string", "description": "End date (ISO YYYY-MM-DD, inclusive) bounding early_vote returns and registration statistics. Ignored for results. Empty = no upper bound. Example: \"2026-11-03\"." }, "counties": { "title": "Counties (FIPS)", "type": "array", "description": "Filter to specific counties by 5-digit FIPS code, e.g. [\"37183\"] (Wake County, NC). Empty = all counties in the requested states. FIPS is the county key across every dataset; a single-county filter turns the sweep into a targeted lookup over the same index.", "items": { "type": "string" } }, "resultsYears": { "title": "Results years", "type": "array", "description": "Filter the results dataset to specific election years, e.g. [\"2020\",\"2024\"]. Applies only to results (county president 2000, 2004, 2008, 2012, 2016, 2020, 2024; Senate 2022). Empty = all available years. Ignored for early_vote / registration.", "items": { "type": "string" } }, "electionId": { "title": "Election ID (early_vote)", "type": "string", "description": "Optional: pin the early_vote sweep to one election, keyed by election-day date (ISO YYYY-MM-DD), e.g. \"2024-11-05\" (2024 General) or \"2026-11-03\" (2026 General). Empty = every election whose daily snapshots fall in the dateFrom / dateTo window. Ignored for registration / results." }, "maxRows": { "title": "Max county rows", "minimum": 1, "maximum": 2000000, "type": "integer", "description": "Safety cap on the total number of county data rows returned AND billed in one run — protects a broad national sweep from an unbounded charge. Coverage rows (not_covered, etc.) are free and do not count against this. Default 200000 (a full national results-history sweep is ~110k rows); the per-run maximum charge (maxTotalChargeUsd) is the hard budget stop.", "default": 200000 } } }, "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 } } } } } } } } } } ```