# US Federal Register Documents (`grit-77/us-federal-register-documents`) Actor

Federal Register document scraper for US rule and notice research. Export document metadata, source summaries, dates, citations and links as JSON.

- **URL**: https://apify.com/grit-77/us-federal-register-documents.md
- **Developed by:** [Grit](https://apify.com/grit-77) (community)
- **Categories:** News, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$1.00 / 1,000 documents

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## US Federal Register Documents

Federal Register scraper returns published document records, source summaries, dates, citations, and document links.

Federal Register scraper uses the public source named below and writes its results to the Actor dataset.

Use the official [Federal Register API](https://www.federalregister.gov/developers/documentation/api/v1) to find final rules, proposed rules, notices and presidential documents. Each document becomes one row; optional detail enrichment adds citations, dockets, effective dates, comment deadlines and text links. Summaries come from the source's abstract; no AI-generated summary is added.

### What it returns

Fields vary by result type and optional enrichment. The examples below are from `sample_output.json`.

| Output field | Type | Example value or excerpt from saved sample |
|---|---|---|
| `status` | string | `"ok"` |
| `documentNumber` | string | `"2025-24102"` |
| `title` | string | `"Effluent Limitations Guidelines and Standards for the Steam Electric Power Generating Point Source …` |
| `documentType` | string | `"RULE"` |
| `type` | string | `"Rule"` |
| `publicationDate` | string | `"2025-12-31"` |
| `agencies` | array | `["Environmental Protection Agency"]` |
| `agencySlugs` | array | `["environmental-protection-agency"]` |
| `summary` | string | `"The U.S. Environmental Protection Agency (the EPA or Agency) is finalizing a Clean Water Act (CWA) …` |
| `excerpt` | string | `"Unleashing American Energy, directs Federal agencies to review and remove, as appropriate and to th…` |
| `htmlUrl` | string | `"https://www.federalregister.gov/documents/2025/12/31/2025-24102/effluent-limitations-guidelines-and…` |
| `pdfUrl` | string | `"https://www.govinfo.gov/content/pkg/FR-2025-12-31/pdf/2025-24102.pdf"` |
| `publicInspectionPdfUrl` | string | `"https://public-inspection.federalregister.gov/2025-24102.pdf?1767102318"` |
| `apiUrl` | string | `"https://www.federalregister.gov/api/v1/documents/2025-24102.json"` |
| `citation` | string | `"90 FR 61328"` |
| `action` | string | `"Final rule."` |
| `effectiveDate` | string | `"2026-03-02"` |
| `commentsCloseDate` | null | `null` |
| `commentUrl` | null | `null` |
| `docketIds` | array | `["EPA-HQ-OW-2009-0819"]` |
| `regulationIdNumbers` | array | `["2040-AG54"]` |
| `cfrReferences` | array | `[{"chapter": null, "citation_url": null, "part": 423, "title": 40}]` |
| `topics` | array | `["Environmental protection"]` |
| `rawTextUrl` | string | `"https://www.federalregister.gov/documents/full_text/text/2025/12/31/2025-24102.txt"` |
| `bodyHtmlUrl` | string | `"https://www.federalregister.gov/documents/full_text/html/2025/12/31/2025-24102.html"` |
| `fullTextXmlUrl` | string | `"https://www.federalregister.gov/documents/full_text/xml/2025/12/31/2025-24102.xml"` |
| `retrievedAt` | string | `"2026-10-05T14:05:58.524200+00:00"` |
| `errors` | array | `[]` |

| Field | Meaning |
|---|---|
| `status`, `errors` | `ok` for a normalized result; `error` plus messages for a failed document |
| `documentNumber`, `title` | Source identifier and document title |
| `documentType`, `type` | API code (`RULE`, `PRORULE`, `NOTICE`, `PRESDOCU`) and human-readable type |
| `publicationDate` | Publication date in YYYY-MM-DD format |
| `agencies`, `agencySlugs` | Publishing agency names and official identifiers |
| `summary` | Original abstract with HTML markup removed; null when absent |
| `excerpt` | Keyword-matching source excerpt, when available |
| `htmlUrl`, `pdfUrl` | Source document page and published PDF link |
| `publicInspectionPdfUrl` | Source public-inspection PDF link, when available |
| `apiUrl` | Official document JSON endpoint |
| `citation`, `action` | Federal Register citation and agency action description (detail mode) |
| `effectiveDate`, `commentsCloseDate`, `commentUrl` | Source dates and comment link (detail mode; nullable) |
| `docketIds`, `regulationIdNumbers` | Source docket and regulation identifiers (detail mode) |
| `cfrReferences`, `topics` | Source CFR references and topic arrays (detail mode) |
| `rawTextUrl`, `bodyHtmlUrl`, `fullTextXmlUrl` | Source document-content links (detail mode) |
| `retrievedAt` | Time this row was normalized, in UTC |

Missing optional text, dates and links remain null; missing optional arrays are empty. If detail enrichment fails, the row retains available search metadata with `status: "error"` and is not charged. Malformed search records can have only identity fields and errors.

The dataset has Documents, Dates and dockets, and Source links views. The default key-value store also receives `SUMMARY` with result/error counts, elapsed seconds, applied filters, resolved agencies and budget-stop status. A failed search writes its error in `SUMMARY` and fails the run.

### Input example

```json
{
  "keyword": "climate",
  "agencies": ["EPA"],
  "documentType": "RULE",
  "dateFrom": "2025-01-01",
  "dateTo": "2025-12-31",
  "order": "newest",
  "includeDetails": true,
  "maxItems": 5,
  "concurrency": 3,
  "maxRetries": 3,
  "requestTimeoutSecs": 30
}
```

| Input | Default | Behavior |
|---|---|---|
| `keyword` | Empty | Official full-text search expression; empty searches without a keyword |
| `agencies` | `[]` | Slugs, full names, abbreviations or numeric ID strings; any listed agency can match |
| `documentType` | `all` | `all`, `RULE`, `PRORULE`, `NOTICE` or `PRESDOCU` |
| `dateFrom`, `dateTo` | Empty | Inclusive publication bounds, YYYY-MM-DD; either bound can be omitted |
| `order` | `newest` | `newest`, `oldest` or `relevance` |
| `includeDetails` | `true` | Fetch individual metadata; `false` returns search metadata without detail requests |
| `maxItems` | `100` | 1–10,000; limits successful and error rows combined |
| `concurrency` | `5` | 1–20 simultaneous detail requests |
| `maxRetries` | `3` | 0–5 retries after transient network/source errors |
| `requestTimeoutSecs` | `30` | 10–120 seconds per network operation |

The [official agency directory](https://www.federalregister.gov/api/v1/agencies.json) lists accepted names, abbreviations, IDs and slugs. For example, `EPA`, `Environmental Protection Agency`, `145` and `environmental-protection-agency` resolve to the same agency. Unknown or ambiguous agency inputs fail with an actionable message.

### Output example

Actual field excerpt from the real dataset saved in `sample_output.json`; the file contains the complete rows:

```json
{
  "status": "ok",
  "documentNumber": "2025-24102",
  "title": "Effluent Limitations Guidelines and Standards for the Steam Electric Power Generating Point Source Category-Deadline Extensions",
  "documentType": "RULE",
  "type": "Rule",
  "publicationDate": "2025-12-31",
  "agencies": ["Environmental Protection Agency"],
  "citation": "90 FR 61328",
  "effectiveDate": "2026-03-02",
  "pdfUrl": "https://www.govinfo.gov/content/pkg/FR-2025-12-31/pdf/2025-24102.pdf",
  "errors": []
}
```

### Pricing

Proposed pay-per-event fee: **$0.001 per `document` event**, or **$1 per 1,000 successful documents**. Error rows and zero-match searches have no document event charge. Apify platform costs depend on your plan. This build is unpublished; the owner must configure the proposed event before paid publication.

The dated Store comparison and event setup are in [PRICING.md](PRICING.md). On 2026-10-05 the most-used directly comparable [Federal Register Rules & Regulations Search](https://apify.com/ryanclinton/federal-register-search) charged $0.002 per document; the proposed document fee is 50% lower.

### Limits

- The actor caps a run at 10,000 result rows. Split larger searches into narrower date ranges. It follows official next-page links, including source continuation tokens, rather than relying solely on the reported page count.
- Filters describe publication dates, not effective dates. The source can include scheduled documents; set `dateTo` when you need a closed historical period.
- The actor returns metadata and document links. It does not download full document bodies or PDF files.
- Source availability, throttling, schema changes and record corrections can affect runs. Transport failures and HTTP 408/429/500/502/503/504 retry with bounded backoff; other HTTP failures surface immediately.
- A search/agency-directory failure fails the run. A document-level parsing/detail failure yields an uncharged error row and other documents continue. Review `status`, `errors` and `SUMMARY` before using results.
- One detail batch can finish after the spending limit is reached, but no additional rows are emitted. Do not configure a second paid default-dataset-item event alongside `document`.
- Deduplication applies within a run. Reusing a local storage directory appends to its dataset; use fresh storage when testing another run.

### FAQ

**What limits a search?** `maxItems` caps document and error rows; narrow publication dates for broader searches. Detail enrichment makes extra requests.

**Do I need a proxy, login, or source API key?** No. The actor calls the public Federal Register API without source credentials or a configured proxy.

**How is it priced?** The proposed pay-per-event model charges the `document` event for each successfully saved document. Error rows and empty searches have no custom document charge; platform usage may be separate.

**How are source rate limits handled?** Requests that receive retryable responses use bounded retries and honor `Retry-After` when present. Detail requests are bounded by `concurrency`.

**How fresh is a record?** Results come from the source API at run time. Compare `publicationDate` with `retrievedAt`; publication dates are distinct from effective dates.

**Why are citations or deadlines missing?** Enable `includeDetails`; the source may still omit them. A failed detail lookup produces an error row.

### Use with AI agents / MCP

After the owner publishes this actor, connect it through Apify's [Actors MCP server](https://docs.apify.com/platform/integrations/mcp). Give the agent a keyword, publication window, agency and result cap. Have it cite `htmlUrl` or `pdfUrl`, retain `documentNumber`, and exclude rows whose `status` is `error`. Treat a missing abstract or deadline as missing source information. This actor does not implement its own MCP server or call a model.

### Local development and checks

The prescribed environment already contains the dependencies; do not install into the shared virtual environment. Runtime requirements are `apify` and `httpx`; `pytest` is needed for development tests.

On Windows, from this actor directory:

```powershell
$env:APIFY_LOCAL_STORAGE_DIR = Join-Path $PWD 'storage'
C:/GritWork/earn/.venv/Scripts/python -m src
C:/GritWork/earn/.venv/Scripts/python -m pytest -q tests/test_config.py tests/test_parsing.py tests/test_crawler.py
C:/GritWork/earn/.venv/Scripts/python -m pytest -q -m live
apify validate-schema
```

Place the input JSON at `storage/key_value_stores/default/INPUT.json` before running. A real input and its dataset are retained there. `scripts/run_local.py` prepares fresh named storage, runs `python -m src` without the Apify CLI and captures receipts in `evidence/`. The live smoke test requests the official API; unit fixtures are saved official responses. Docker uses `apify/actor-python:3.12` and starts `python3 -m src`.

# Actor input Schema

## `keyword` (type: `string`):

Full-text search expression, for example climate or "clean water". Leave empty to search without a keyword.

## `agencies` (type: `array`):

Official slugs, full names, abbreviations or numeric ID strings. Examples: environmental-protection-agency, EPA, 145. Multiple agencies match any listed agency. Leave empty for all agencies.

## `documentType` (type: `string`):

Choose the type of published document.

## `dateFrom` (type: `string`):

Inclusive start date in YYYY-MM-DD format. Empty means no start date.

## `dateTo` (type: `string`):

Inclusive end date in YYYY-MM-DD format. Empty means no end date.

## `order` (type: `string`):

Order of results from the official API. Relevance is most useful with a keyword.

## `includeDetails` (type: `boolean`):

Fetch individual document metadata for citations, docket IDs, effective dates, comment deadlines and text links. Does not download document bodies or PDFs.

## `maxItems` (type: `integer`):

Hard cap on document and error rows combined, between 1 and 10,000. Narrow the date range to split larger searches.

## `concurrency` (type: `integer`):

Maximum detail requests in flight; searches are paginated sequentially.

## `maxRetries` (type: `integer`):

Retries after transport failures or HTTP 408, 429, 500, 502, 503 and 504, using bounded backoff and Retry-After.

## `requestTimeoutSecs` (type: `integer`):

Timeout for each source network operation.

## Actor input object example

```json
{
  "keyword": "climate",
  "agencies": [],
  "documentType": "all",
  "dateFrom": "",
  "dateTo": "",
  "order": "newest",
  "includeDetails": true,
  "maxItems": 100,
  "concurrency": 5,
  "maxRetries": 3,
  "requestTimeoutSecs": 30
}
```

# Actor output Schema

## `dataset` (type: `string`):

Federal Register documents with source summaries, metadata and PDF/HTML links.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keyword": "climate"
};

// Run the Actor and wait for it to finish
const run = await client.actor("grit-77/us-federal-register-documents").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "keyword": "climate" }

# Run the Actor and wait for it to finish
run = client.actor("grit-77/us-federal-register-documents").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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": "climate"
}' |
apify call grit-77/us-federal-register-documents --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,grit-77/us-federal-register-documents"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/hCXjinGMlkoJJWyMb/builds/GiqqNNktTTxH5Ln0h/openapi.json