# SEC XBRL Peer Financial Change Report (`taroyamada/sec-xbrl-peer-financial-change-report`) Actor

Compare selected public-company XBRL facts across a bounded ticker or CIK watchlist. Receive source-linked metric change alerts, descriptive peer variance reports, and compact exports from official SEC companyfacts or frames JSON APIs. First baselines and unchanged checks emit no rows and no charges

- **URL**: https://apify.com/taroyamada/sec-xbrl-peer-financial-change-report.md
- **Developed by:** [naoki anzai](https://apify.com/taroyamada) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 sec xbrl financial fact rows

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## SEC XBRL Peer Financial Change Report

For corp-dev, finance operations, research, and public-company monitoring teams, this Actor accepts ticker or CIK peer watchlists plus selected XBRL metrics and returns source-linked financial metric change alerts, descriptive peer variance reports, and compact evidence exports.

It uses official SEC `companyfacts` and `frames` JSON endpoints without an API key or login. A descriptive SEC User-Agent with an application identifier and contact email or URL is required.

### Store Quickstart

```json
{
  "watchlists": [
    {
      "id": "software-peers",
      "peers": [
        {
          "ticker": "MSFT"
        },
        {
          "ticker": "AAPL"
        }
      ],
      "metrics": [
        {
          "taxonomy": "us-gaap",
          "tag": "Revenues",
          "unit": "USD",
          "label": "Revenue",
          "sourceMode": "companyfacts"
        }
      ],
      "forms": [
        "10-K",
        "10-Q"
      ],
      "period": "latest",
      "varianceThresholdPercent": 20
    }
  ],
  "userAgent": "your-company-xbrl-watch/1.0 ops@yourcompany.com",
  "initialRunMode": "baseline_only",
  "generateReport": true,
  "emitExport": true
}
```

1. Start with `initialRunMode: "baseline_only"` and a small peer group. The first run saves a free baseline and emits zero rows and zero charges.
2. Run the same input later. Only a new or changed selected fact emits rows; an unchanged run emits zero rows and zero charges.
3. Set `generateReport: true` for the report-first output. Use `emitExport: true` when a compact JSON evidence package is needed. Keep `emitRawRows: false` unless individual fact rows are required.

The actor compares the selected facts as reported by SEC XBRL. It does not decide whether a company is attractive, safe, cheap, expensive, or likely to outperform.

### Input Examples

#### 1. Companyfacts revenue watch

```json
{
  "watchlists": [{
    "id": "software-peers",
    "peers": [{ "ticker": "MSFT" }, { "ticker": "AAPL" }],
    "metrics": [{ "taxonomy": "us-gaap", "tag": "Revenues", "unit": "USD", "label": "Revenue", "sourceMode": "companyfacts" }],
    "forms": ["10-K", "10-Q"],
    "period": "latest",
    "varianceThresholdPercent": 20
  }],
  "userAgent": "your-company-xbrl-watch/1.0 ops@yourcompany.com",
  "initialRunMode": "baseline_only",
  "generateReport": true,
  "emitExport": true
}
```

#### 2. CIK watchlist with annual assets

```json
{
  "watchlists": [{
    "id": "annual-assets",
    "peers": [{ "cik": "0000789019", "label": "Microsoft" }, { "cik": "0000320193", "label": "Apple" }],
    "metrics": [{ "taxonomy": "us-gaap", "tag": "Assets", "unit": "USD", "label": "Assets", "sourceMode": "companyfacts" }],
    "forms": ["10-K"],
    "period": "annual",
    "varianceThresholdPercent": 15
  }],
  "userAgent": "your-company-xbrl-watch/1.0 ops@yourcompany.com",
  "initialRunMode": "emit_backfill",
  "generateReport": true
}
```

#### 3. SEC frames watch

```json
{
  "watchlists": [{
    "id": "quarterly-frame",
    "peers": [{ "ticker": "MSFT" }, { "ticker": "AAPL" }],
    "metrics": [{ "taxonomy": "us-gaap", "tag": "Revenues", "unit": "USD", "label": "Quarterly revenue frame", "sourceMode": "frames", "frame": "CY2025Q4" }],
    "forms": ["10-Q", "10-K"],
    "period": "quarterly",
    "varianceThresholdPercent": 25
  }],
  "userAgent": "your-company-xbrl-watch/1.0 ops@yourcompany.com",
  "initialRunMode": "baseline_only"
}
```

### Output

The first output row for a changed run is a `sec_peer_variance_report`. It contains each metric group, peer values, the peer median, variance from that median, reporting period, form, and SEC source URLs. It is followed by one `sec_financial_metric_change_alert` per changed observation. Optional rows are `sec_financial_fact_row` and `sec_financial_export`.

Every row retains the taxonomy, tag, unit, CIK/ticker, period, filing date, form, accession number when available, and source-linked evidence. The actor never downloads filing exhibits as part of this workflow.

### Pricing

| Event | Price | Use |
| --- | ---: | --- |
| `sec-financial-fact-row` | $0.006 | Optional compact raw fact row |
| `sec-financial-metric-change-alert` | $0.25 | New or changed selected metric observation |
| `sec-peer-variance-report` | $12.00 | Descriptive report across the current peer groups |
| `sec-financial-export` | $8.00 | Compact JSON evidence export |

Baseline-only runs and unchanged runs are free. `emitUnchanged` is accepted for compatibility but never turns unchanged observations into billable rows. A per-run `maxChargeUsd` cap fails closed before delivery.

### Compliance Guardrails

- Official SEC `data.sec.gov` XBRL JSON endpoints and the official SEC ticker index only.
- No API key, login, private issuer data, filing exhibit download, scraping bypass, or CAPTCHA handling.
- Keep the User-Agent descriptive, include a real application contact in production, use bounded watchlists, and retain the default pacing unless you have a documented reason to change it.
- Peer variance is descriptive source-linked evidence. It is not investment advice, a valuation, a recommendation, a forecast, a materiality determination, or a guarantee.
- Confirm the reporting period, unit, taxonomy, dimensions, amendments, and linked filing before relying on an output.

### State and Billing Safety

State is written only after all billable rows have been delivered successfully. A state read/write failure stops the run. A delivery failure writes a failed-closed audit and does not commit the new baseline. The delivery audit is written to `sec-xbrl-peer-financial-delivery-audit.json` locally and `PHASE89_DELIVERY_AUDIT` in the Apify key-value store.

### Run the next report

- [SEC 13D & 13G Beneficial Ownership Change Report](https://apify.com/taroyamada/sec-13d-13g-beneficial-ownership-change-report) for source-linked ownership filing changes.
- [SEC 13F Institutional Holdings Change Report](https://apify.com/taroyamada/sec-13f-institutional-holdings-change-report) for source-linked quarterly holdings changes.
- [LEI Entity Lifecycle Watch Report](https://apify.com/taroyamada/lei-entity-lifecycle-watch-report) for source-linked legal-entity status and reference-data changes.

### Limitations

Companyfacts and frames may use different fiscal calendars, tags, dimensions, units, amendments, and filing periods. The Actor does not normalize accounting policy differences or decide whether two companies are economically comparable. It reports the selected public facts and the exact source context available from SEC JSON at retrieval time.

# Actor input Schema

## `watchlists` (type: `array`):

Each watchlist combines selected peers and XBRL metrics. Use CIKs for deterministic identity or tickers resolved through the official SEC ticker index.

## `monitorKey` (type: `string`):

Stable state namespace for a recurring peer portfolio.

## `userAgent` (type: `string`):

Required descriptive value, for example your-company-xbrl-watch/1.0 ops@yourcompany.com. Replace the example contact with your own application contact before production use.

## `initialRunMode` (type: `string`):

baseline\_only stores the first observations with zero rows; emit\_backfill emits current observations as a first paid report.

## `generateReport` (type: `boolean`):

Emit one report-first descriptive peer variance row when selected observations change.

## `emitRawRows` (type: `boolean`):

Optional low-priced compact XBRL fact rows for changed observations.

## `emitExport` (type: `boolean`):

Emit a compact JSON export of current observations and selected changes.

## `emitUnchanged` (type: `boolean`):

Accepted for compatibility, but unchanged observations remain free and emit zero rows and zero charges.

## `maxRequests` (type: `integer`):

Hard request bound including ticker index, companyfacts, and frames calls.

## `requestIntervalMs` (type: `integer`):

Minimum delay between official SEC requests. Keep a conservative interval and respect current SEC guidance.

## `maxChargeUsd` (type: `number`):

Fail closed before delivery if planned PPE charges exceed this cap.

## `dryRun` (type: `boolean`):

Return deterministic representative rows for all event types without SEC requests, state writes, or charges.

## Actor input object example

```json
{
  "watchlists": [
    {
      "id": "software-peers",
      "peers": [
        {
          "ticker": "MSFT"
        },
        {
          "ticker": "AAPL"
        }
      ],
      "metrics": [
        {
          "taxonomy": "us-gaap",
          "tag": "Revenues",
          "unit": "USD",
          "label": "Revenue",
          "sourceMode": "companyfacts"
        }
      ],
      "forms": [
        "10-K",
        "10-Q"
      ],
      "period": "latest",
      "varianceThresholdPercent": 20
    }
  ],
  "monitorKey": "sec-xbrl-peer-watch",
  "userAgent": "taroyamada-sec-xbrl-peer-financial-change-report/1.0 ops@example.com",
  "initialRunMode": "baseline_only",
  "generateReport": true,
  "emitRawRows": false,
  "emitExport": false,
  "emitUnchanged": false,
  "maxRequests": 40,
  "requestIntervalMs": 1100,
  "maxChargeUsd": 25,
  "dryRun": 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("taroyamada/sec-xbrl-peer-financial-change-report").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("taroyamada/sec-xbrl-peer-financial-change-report").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 '{}' |
apify call taroyamada/sec-xbrl-peer-financial-change-report --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,taroyamada/sec-xbrl-peer-financial-change-report"
        }
    }
}

```

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/FSd131FypRhVArDWF/builds/Y2Ze1jssVyR7EtI0Z/openapi.json