# FCC ECFS Filings Watch (`mikee368/fcc-filings-watch`) Actor

Watch FCC ECFS filings by docket and filer name. The first run stores a free baseline. Later runs return only new deduped filings received after lastSeen. Equipment authorization is not included.

- **URL**: https://apify.com/mikee368/fcc-filings-watch.md
- **Developed by:** [Mike Berckmoes](https://apify.com/mikee368) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.00 / 1,000 new filings

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

## FCC ECFS Filings Watch

Watch FCC Electronic Comment Filing System filings by docket and by filer name. Each later run returns filings whose `date_received` is at or after the stored watermark and whose ID is not already stored. The first run is a free baseline and stores those watermark filings as uncharged snapshot rows.

This version reads the ECFS filings API only. It does not cover equipment authorization.

### What you get

A dataset row for each new filing, plus free `baseline` rows on the first run for a Monitor ID. One key-value record named `OUTPUT` holds the whole batch (new filings, baseline snapshots, error rows, and whether the cap stopped the run). News Scout should read `OUTPUT` when the run finishes. This Actor does not send a webhook per filing.

| Field | Meaning |
|---|---|
| `submissionId` | ECFS `id_submission` |
| `dateReceived` | FCC `date_received` |
| `filers`, `proceedings` | Names and docket numbers on the filing |
| `submissionType`, `filingStatus` | ECFS type and status |
| `documentUrls` | Document links from the record |
| `textExcerpt` | First 500 characters of the filing text |
| `sourceUrl` | ECFS search link for the filing |
| `rowType` | `baseline` (free), `filing` (charged), `error` (free), or `capped` (free) |

### How to use it

1. Add up to **10** dockets and **10** filer names (you can lower that with `maxDockets` and `maxFilers`; the hard caps are 25). The status message names the cap.
2. Paste your free [api.data.gov](https://api.data.gov/signup/) key into **api.data.gov key**. If you leave it empty, or type the public `DEMO_KEY`, the run uses that shared key. The log and the status message both warn that `DEMO_KEY` allows about 10 requests, which is enough for only a few dockets.
3. Run once. The dataset gets one free `baseline` row for each filing at the newest `date_received`. `lastSeen` and those filing IDs are stored for this Monitor ID. That baseline is not charged.
4. Schedule the same Monitor ID. The next run stores a row for a filing received at or after `lastSeen` when that filing's ID is not already stored.

### How much does it cost?

Pay per new filing: **`filing` at $0.002**. The price is configured in `.actor/pricing.json` and is not applied on the platform until you say so.

The first baseline is free, including its snapshot rows. An error row is free. A filing past `maxFilings` is not stored and is not charged; the run adds one free `capped` row instead. Runs use 128 MB.

### Good to know

- **API.** `GET https://publicapi.fcc.gov/ecfs/filings` with `proceedings.name` and `filers.name`. The key is a query parameter and is not copied into the dataset or the watch state.
- **Date filter.** The live API accepts `date_received=[gte]YYYY-M-D[lte]YYYY-M-D`. A timestamp, or `[gt]` without `[lte]`, returns HTTP 400. `[gt]` on a calendar day still includes later timestamps that day, and `[lte]` on a day excludes later timestamps that day. The Actor sends a day window from the `lastSeen` day through two days ahead of today, then keeps a row when its timestamp is `>= lastSeen` and its ID is not already stored.
- **State.** The named store `fcc-filings-watch-state` keeps `seen-<monitorId>` with two fields: `lastSeen` and `ids`. Nothing else. Every run replaces that ID list with IDs inside the query window (timestamps at or after `lastSeen`). When the watch is current, that window is the recent overlap, and the API end bound is today plus two days. IDs older than `lastSeen` are dropped so the set does not keep the whole history.
- **Caps.** Extra dockets or filers past the cap are not queried. New filings past `maxFilings` stay unseen so the next run can return them. A failed query does not move `lastSeen`.
- **DEMO_KEY.** On 15 Oct 2026 the demo key's response included `x-ratelimit-limit: 10`. The header had no reset time, so this README does not state the window. A long list on `DEMO_KEY` can fail partway; those queries become free error rows.

### Input example

```json
{
  "dockets": ["22-270"],
  "filers": [],
  "monitorId": "default",
  "maxFilings": 50
}
```

# Actor input Schema

## `dockets` (type: `array`):

FCC proceeding numbers, for example 22-270 or RM-11868. One ECFS query per docket. At most maxDockets per run (default 10, hard cap 25).

## `filers` (type: `array`):

Filer or company names, matched with the ECFS filers.name field. One query per name. At most maxFilers per run (default 10, hard cap 25). A filing that also matches a docket is stored once.

## `apiKey` (type: `string`):

Your free api.data.gov key. Leave empty, or enter DEMO_KEY, to use the public fallback. The log and the status message warn that DEMO_KEY allows about 10 requests, enough for only a few dockets. The key is not written to the dataset or the watch state.

## `monitorId` (type: `string`):

Name of the watch state. The named store keeps lastSeen and the seen filing IDs for this ID only.

## `resetState` (type: `boolean`):

Forget lastSeen and the seen filing IDs for this Monitor ID. The next run is a free baseline again.

## `maxDockets` (type: `integer`):

How many dockets from the list are queried. The rest are skipped and reported. Hard cap 25.

## `maxFilers` (type: `integer`):

How many filer names from the list are queried. The rest are skipped and reported. Hard cap 25.

## `maxFilings` (type: `integer`):

How many new deduped filings are stored and charged. One free capped row records the stop. Filings past the cap are not stored and are not charged. Hard cap 200.

## Actor input object example

```json
{
  "dockets": [
    "22-270"
  ],
  "filers": [],
  "monitorId": "default",
  "resetState": false,
  "maxDockets": 10,
  "maxFilers": 10,
  "maxFilings": 50
}
```

# Actor output Schema

## `overview` (type: `string`):

One JSON record for the whole run: new filings, errors, and whether the cap was hit

## `filings` (type: `string`):

Dataset with one row per new deduped filing, plus free baseline rows on the first run. Error and capped rows are in the same dataset and are not charged.

## `summary` (type: `string`):

Baseline flag, lastSeen, counts, and the per-run caps

# 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 = {
    "dockets": [
        "22-270"
    ],
    "filers": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("mikee368/fcc-filings-watch").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 = {
    "dockets": ["22-270"],
    "filers": [],
}

# Run the Actor and wait for it to finish
run = client.actor("mikee368/fcc-filings-watch").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 '{
  "dockets": [
    "22-270"
  ],
  "filers": []
}' |
apify call mikee368/fcc-filings-watch --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mikee368/fcc-filings-watch"
        }
    }
}
```

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/fBobb3FEvOF2jhwaH/builds/JEO89Zt6OLQCePYhD/openapi.json