# US Legislative Bill Monitor — All 50 States (LegiScan) (`kenduffy/us-legislative-bill-monitor-all-50-states-legiscan`) Actor Monitor legislation across all 50 states and Congress by keyword. Powered by LegiScan. Supports scheduled runs with delta mode — only new and updated bills returned. Bring your own LegiScan API key. - **URL**: https://apify.com/kenduffy/us-legislative-bill-monitor-all-50-states-legiscan.md - **Developed by:** [Ken Duffy](https://apify.com/kenduffy) (community) - **Categories:** Automation, News, Other - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $20.00 / 1,000 bill results 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 ## US Legislative Bill Monitor — All 50 States (LegiScan) Search and monitor US legislation across all 50 states, Washington DC, and the US Congress from a single Actor. Bring your own free LegiScan API key. Designed to run on a schedule and return only the bills that have changed since your last run. --- ### What this Actor does Given a keyword (e.g. `guns`, `cannabis`, `AI`, `medicaid`) and a year range, this Actor: 1. Queries the [LegiScan](https://legiscan.com) `getSearch` API for matching bills in every selected jurisdiction. 2. Fetches the full detail of each matching bill via `getBill`. 3. Returns one JSON record per bill with the fields most policy-monitoring workflows need: bill number, title, sponsors, intro date, full-text PDF URL, current status, and stable identifiers for joining with your own systems. In **monitor mode**, it remembers what it has already seen and skips bills whose underlying data has not changed — making it cheap and quota-efficient to run on a weekly cadence. ### Who it's for - **Policy monitoring teams** tracking legislation by topic across multiple states - **Journalists and researchers** building issue-focused legislative databases - **Advocacy organizations** watching for movement on specific bills or topics - **Regulatory and compliance teams** in industries affected by state-level rule changes - **Lobbyists and government-affairs professionals** needing structured, queryable bill data - **Developers** building products on top of US legislative data who don't want to scrape 50 different state websites ### Prerequisite: get a free LegiScan API key This Actor uses the LegiScan API and requires **your own** API key. The Actor never stores it. 1. Register at https://legiscan.com/legiscan 2. The free tier includes **30,000 API requests per month** under LegiScan's personal-use terms. That covers thousands of bills per month, especially with monitor mode. 3. Paste your key into the `legiscanApiKey` input field when you start a run. Marked as a secret in the input form, so it's obscured in logs and the run UI. If you plan to use this Actor commercially or redistribute the data downstream, please review LegiScan's commercial terms — those obligations apply to whoever holds the API key (i.e. you), not to this Actor. ### Inputs | Field | Type | Required | Default | Description | |---|---|---|---|---| | `legiscanApiKey` | string (secret) | yes | — | Your personal LegiScan API key. | | `keyword` | string | yes | — | Search term to match in bill text (e.g. `guns`, `abortion`, `AI`). Supports LegiScan's full-text search syntax. | | `states` | array of strings | no | `[]` (all) | State postal codes to search (e.g. `["AK", "CA", "TX"]`). Use `US` for federal Congress. Leave empty to search all 50 states + DC + Congress. | | `yearStart` | integer | no | `2023` | Earliest year to include. | | `yearEnd` | integer | no | `2026` | Latest year to include (inclusive). | | `maxBillsPerStatePerYear` | integer | no | `200` | Hard cap per (state, year) combination. Prevents accidental quota burn. Set high (e.g. 5000) to fetch everything. | | `monitorMode` | boolean | no | `false` | When `true`, the Actor skips bills whose LegiScan `change_hash` matches the value stored from a prior run. Only new or updated bills are returned. See "Monitor mode" below. | #### Minimal input ```json { "legiscanApiKey": "YOUR_LEGISCAN_KEY", "keyword": "guns" } ```` That single call searches every US jurisdiction across 2023–2026. #### Targeted input ```json { "legiscanApiKey": "YOUR_LEGISCAN_KEY", "keyword": "data privacy", "states": ["CA", "TX", "NY", "FL"], "yearStart": 2024, "yearEnd": 2026, "monitorMode": true } ``` ### Sample output Each row in the default dataset looks like this: ```json { "billNumber": "HB89", "title": "Gun Violence Protective Orders", "state": "AK", "session": "34th Legislature", "sponsors": [ "Andrew Josephson", "Sara Hannan", "Genevieve Mina", "Andrew Gray" ], "primarySponsor": "Andrew Josephson", "dateIntroduced": "2025-02-10", "billTextUrl": "https://www.akleg.gov/PDF/34/Bills/HB0089A.PDF", "legiscanUrl": "https://legiscan.com/AK/bill/HB89/2025", "stateUrl": "https://www.akleg.gov/basis/Bill/Detail/34?Root=HB89", "status": 1, "statusDate": "2025-02-10", "lastAction": "COSPONSOR(S): GRAY", "lastActionDate": "2025-03-12", "billId": 1963810, "changeType": "new" } ``` #### Field reference | Field | Description | |---|---| | `billNumber` | The bill number as used by the state (`HB89`, `SB173`, `HR459`, etc.) | | `title` | Short title from LegiScan | | `state` | Two-letter postal code; `US` for federal Congress | | `session` | Legislative session name when available | | `sponsors` | Full names of all sponsors, in order returned by LegiScan | | `primarySponsor` | First sponsor whose role is "Primary"; falls back to first sponsor | | `dateIntroduced` | Earliest action date in the bill's history (typically the first reading) | | `billTextUrl` | Direct URL to the bill text PDF — usually hosted on the state legislature's own site | | `legiscanUrl` | LegiScan's canonical page for the bill | | `stateUrl` | The state legislature's own detail page for the bill | | `status`, `statusDate` | LegiScan's status code and the date that status was reached | | `lastAction`, `lastActionDate` | Most recent action and when it occurred | | `billId` | LegiScan's stable internal ID — safe to use as a primary key | | `changeType` | `"new"`, `"updated"`, or `"unchanged"`. Always present from v0.2 onward. | ### Monitor mode The killer feature for scheduled use. When `monitorMode: true`: 1. Every bill the Actor sees has a `change_hash` (LegiScan's content fingerprint). 2. The Actor maintains a persistent map of `billId → change_hash` in a named Key-Value Store across runs. 3. On each run, before fetching a bill's full detail, the search-result hash is compared to the stored value. 4. **If the hashes match, the bill has not changed and is skipped entirely** — no detail fetch, no dataset row. 5. **If the hashes differ or the bill is new, it is fetched and emitted** with `changeType: "updated"` or `"new"`. #### Why this matters The `getBill` call is the expensive one (one quota request per bill). In a typical weekly run on a busy keyword, only a small fraction of previously-seen bills will have changed. Monitor mode can cut the per-run quota cost by 90%+ on stable weeks while still surfacing every real change. #### Suggested usage - **First run:** `monitorMode: false`. Pull everything matching your query to establish a baseline dataset. - **Subsequent scheduled runs:** `monitorMode: true`. Each run's dataset becomes "what changed this week" — perfect for piping into an email digest, Slack notification, or downstream pipeline. Set up via Apify **Schedules** (Console → your Actor → Schedules tab) to run weekly, daily, or on any cron pattern. ### How it works under the hood 1. The Actor enumerates the cartesian product of `(state, year)` from your input and issues one `getSearch` request per combination. 2. LegiScan returns bill summaries with `change_hash`. In monitor mode, hashes are compared here and unchanged bills are filtered out before any detail fetch. 3. For each surviving bill, `getBill` is called to retrieve sponsors, full action history, and bill text URLs. 4. Records are pushed to the default dataset. The updated hash map is written to the named Key-Value Store `legiscan-change-hashes`. Concurrency is capped at 3 simultaneous requests. Failures are retried up to 3 times. The Actor honours LegiScan's response status codes and surfaces API errors clearly in the log. ### Current limitations The following are documented constraints in the current release. Items marked **planned** have a target release. - **LegiScan quota is yours to manage.** A wide search across all 50 states + Congress for multiple years can consume the free tier's 30,000 monthly requests quickly. Use `maxBillsPerStatePerYear` as a guardrail and monitor mode for any recurring run. Sizing guidance is available on request. - **`session` field may be null** when LegiScan returns the session as a nested object format the current parser does not unwrap. Fix **planned** for v0.2.x. As a workaround, `legiscanUrl` always encodes the session year (e.g. `.../bill/HB89/2025`). - **Amendments, votes, fiscal notes, and committee history** are excluded by design in v0.2 to keep output rows compact. **Planned** as opt-in flags in v0.3. - **Multi-keyword `OR` queries** are not exposed as a dedicated input. LegiScan's full-text syntax supports them — pass the operators directly in the `keyword` field. - **Hash store is shared across all runs of this Actor.** Bills seen under one keyword are remembered when they reappear under another. This is normally desirable for monitoring but worth knowing if you run multiple parallel queries. Per-keyword isolation is **planned** for v0.3. ### Pricing This Actor uses Apify's pay-per-event model. You pay only for what you run: | Event | Charge | |---|---| | **Actor Start** | $0.50 per run (billed once per GB of allocated memory; the default 1 GB build counts as a single event) | | **Bill result** | $0.02 per bill written to the dataset | Users supply their own free LegiScan API key — get one at [legiscan.com/legiscan](https://legiscan.com/legiscan). The Actor never stores it. #### Estimated cost by run profile | Scenario | Bills returned | Approx. cost | |---|---|---| | Single state, single year, narrow keyword | ~10 | $0.70 | | Single state, 4-year range (e.g. Alaska 2023–2026) | ~10 | $0.70 | | All 50 states + DC + Congress, single year, cold run | ~300 | $6.50 | | All 50 states + DC + Congress, 4-year range, cold run | ~1,000 | $20.50 | | **Weekly monitor-mode run after a baseline** (typical: a handful of changes) | 0–10 | $0.50–$0.70 | Monitor mode is the way to make ongoing tracking cheap: once your baseline is established, each scheduled run typically costs no more than the Actor Start charge plus a few cents in delta bills. LegiScan API quota is separate and consumed against your own LegiScan account — not billed by Apify. ### Attribution Bill data is provided by [LegiScan](https://legiscan.com). LegiScan is a trademark of LegiScan, Inc. This Actor is an independent integration with LegiScan's public API and is not affiliated with, sponsored by, or endorsed by LegiScan. Bill text PDFs are hosted by the respective state legislatures (or the US Congress for federal bills) and linked directly in each output record. ### Support Use the **Issues** tab on the Actor's Apify page for: - Bug reports — broken runs, missing or malformed fields, unexpected errors - Feature requests scoped to this Actor - Schema questions and integration guidance **Response targets:** - **Critical** (Actor not running, breaking schema change): acknowledged within two business days; mitigation or workaround communicated as soon as available. - **Standard** (bugs, questions, feature requests): acknowledged within three business days. For LegiScan API quota, key management, or data-quality questions about LegiScan itself, contact LegiScan directly via [legiscan.com](https://legiscan.com). Apify usage charges and billing are handled by Apify through the Console's billing settings. ### Roadmap Items are tagged as **planned** (committed, in development) or **considering** (under evaluation, no commitment). - **v0.2.x — planned.** Parse the nested `session` object so the field is reliably populated. - **v0.3 — planned.** Opt-in inclusion of amendments, vote rollcalls, fiscal notes, and committee actions. - **v0.3 — planned.** Per-keyword hash-store isolation for subscribers running multiple parallel monitors. - **v0.4 — considering.** Bulk dataset sync via LegiScan's `getDataset` endpoint (1,000 quota calls covers ~3.5M records — fundamentally different architecture, separate companion Actor). - **v0.4 — considering.** Export of the change-hash store as a side-output, so subscribers can drive their own diffing logic in downstream systems. Roadmap is informed by user feedback; the Issues tab is the right channel to influence priority. # Actor input Schema ## `legiscanApiKey` (type: `string`): Your personal LegiScan API key. Get one free at https://legiscan.com/legiscan (30,000 requests/month, personal use). The Actor never stores this key. ## `keyword` (type: `string`): Search term to match in bill text (e.g. 'artificial intelligence', 'data privacy', 'cannabis'). Supports LegiScan's full-text search syntax. ## `states` (type: `array`): Postal codes to search (e.g. AK, CA, TX). Use 'US' for federal Congress. Leave empty to search all 50 states + DC + Congress. ## `yearStart` (type: `integer`): Earliest year to include. ## `yearEnd` (type: `integer`): Latest year to include (inclusive). ## `maxBillsPerStatePerYear` (type: `integer`): Stop after this many bills per state per year. Prevents accidental quota burn. Set high (e.g. 1000) to fetch everything. ## `monitorMode` (type: `boolean`): When true, skip bills whose LegiScan change\_hash matches the value stored from a previous run. Only new or updated bills are emitted, and unchanged bills consume no detail-fetch quota. Designed for scheduled weekly runs. First run with this flag emits everything as 'new'. ## Actor input object example ```json { "keyword": "artificial intelligence", "states": [], "yearStart": 2023, "yearEnd": 2026, "maxBillsPerStatePerYear": 200, "monitorMode": false } ``` # 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 = { "keyword": "artificial intelligence" }; // Run the Actor and wait for it to finish const run = await client.actor("kenduffy/us-legislative-bill-monitor-all-50-states-legiscan").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 = { "keyword": "artificial intelligence" } # Run the Actor and wait for it to finish run = client.actor("kenduffy/us-legislative-bill-monitor-all-50-states-legiscan").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 '{ "keyword": "artificial intelligence" }' | apify call kenduffy/us-legislative-bill-monitor-all-50-states-legiscan --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=kenduffy/us-legislative-bill-monitor-all-50-states-legiscan", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "US Legislative Bill Monitor — All 50 States (LegiScan)", "description": "Monitor legislation across all 50 states and Congress by keyword. Powered by LegiScan. Supports scheduled runs with delta mode — only new and updated bills returned. Bring your own LegiScan API key.", "version": "0.2", "x-build-id": "ZTvPvRY5G0IpvnNQF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/kenduffy~us-legislative-bill-monitor-all-50-states-legiscan/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-kenduffy-us-legislative-bill-monitor-all-50-states-legiscan", "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/kenduffy~us-legislative-bill-monitor-all-50-states-legiscan/runs": { "post": { "operationId": "runs-sync-kenduffy-us-legislative-bill-monitor-all-50-states-legiscan", "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/kenduffy~us-legislative-bill-monitor-all-50-states-legiscan/run-sync": { "post": { "operationId": "run-sync-kenduffy-us-legislative-bill-monitor-all-50-states-legiscan", "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", "required": [ "legiscanApiKey", "keyword" ], "properties": { "legiscanApiKey": { "title": "LegiScan API key", "type": "string", "description": "Your personal LegiScan API key. Get one free at https://legiscan.com/legiscan (30,000 requests/month, personal use). The Actor never stores this key." }, "keyword": { "title": "Keyword", "type": "string", "description": "Search term to match in bill text (e.g. 'artificial intelligence', 'data privacy', 'cannabis'). Supports LegiScan's full-text search syntax." }, "states": { "title": "States", "uniqueItems": true, "type": "array", "description": "Postal codes to search (e.g. AK, CA, TX). Use 'US' for federal Congress. Leave empty to search all 50 states + DC + Congress.", "default": [], "items": { "type": "string" } }, "yearStart": { "title": "Year start", "minimum": 2009, "maximum": 2100, "type": "integer", "description": "Earliest year to include.", "default": 2023 }, "yearEnd": { "title": "Year end", "minimum": 2009, "maximum": 2100, "type": "integer", "description": "Latest year to include (inclusive).", "default": 2026 }, "maxBillsPerStatePerYear": { "title": "Cap per state per year", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Stop after this many bills per state per year. Prevents accidental quota burn. Set high (e.g. 1000) to fetch everything.", "default": 200 }, "monitorMode": { "title": "Monitor mode (delta only)", "type": "boolean", "description": "When true, skip bills whose LegiScan change_hash matches the value stored from a previous run. Only new or updated bills are emitted, and unchanged bills consume no detail-fetch quota. Designed for scheduled weekly runs. First run with this flag emits everything as 'new'.", "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 } } } } } } } } } } ```