# European ESEF Filing & Quality Monitor (`truenorth/european-esef-filing-quality-monitor`) Actor

Export attributable European filing metadata and source-provided XBRL issue counts from the XBRL International Filings Repository.

- **URL**: https://apify.com/truenorth/european-esef-filing-quality-monitor.md
- **Developed by:** [TrueNorth](https://apify.com/truenorth) (community)
- **Categories:** Automation, AI, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.90 / 1,000 results

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/actors/running/actors-in-store.md#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

## European ESEF Filing & Quality Monitor

Exports normalized filing metadata and source-provided issue counts from the
[XBRL International Filings Repository](https://filings.xbrl.org). Each Dataset
item identifies the exact API page and UTC retrieval time.

This Actor uses the public JSON:API catalog only. It does not download filing
packages, parse facts, extract validation-message details, use a browser, or
send undocumented server-side filters. All configured country, date, entity
name, and issue-count filters run locally after a page is validated.

### Input

Default catalog mode scans `/api/filings` serially with `include=entity`.
`maxItems` limits emitted records, while `maxPages` limits fully processed
source pages. `null` means no limit when input is supplied through the API.

Monitoring stores filing hashes in `PROCESSED_FILINGS_STATE`. With
`monitoring=true` and `emitMode="newOrChanged"`, unchanged filings are counted
but not emitted. Dataset delivery is at-least-once; consumers can deduplicate
with `fxoId + sha256`.

Issuer mode remains deliberately disabled because no captured issuer-response
fixture exists to prove that endpoint contract.

Example:

```json
{
  "mode": "catalog",
  "countries": ["DE", "FR"],
  "onlyWithQualityIssues": true,
  "maxItems": 100,
  "maxPages": 10
}
```

### Output semantics

`errorCount`, `warningCount`, and `inconsistencyCount` are copied from source
metadata. `qualityStatus="clean"` means only that those three source-provided
counts are zero; it does not prove correctness or regulatory compliance.
Output is not audit assurance, investment advice, or an affiliation with or
endorsement by XBRL International.

Run summary is stored as `OUTPUT`; bounded diagnostics are stored as
`RUN_DIAGNOSTICS`.

### Local development

```sh
pnpm install --frozen-lockfile
pnpm format
pnpm lint
pnpm typecheck
pnpm test:coverage
pnpm build
apify validate-schema
```

Fixture mode is local-only and requires an absolute path:

```sh
ESEF_FIXTURE_PATH="$PWD/research/filings-sample.json" \
  apify run --purge --input-file tests/fixtures/local-input.json
```

Setting `ESEF_FIXTURE_PATH` in Apify Cloud fails closed.

# Actor input Schema

## `mode` (type: `string`):

Catalog is available. Issuer mode remains contract-gated and fails closed.

## `entityIdentifiers` (type: `array`):

Issuer mode only; currently rejected until its source contract is captured.

## `countries` (type: `array`):

Uppercase two-letter country codes matched locally.

## `periodEndFrom` (type: `string`):

Inclusive YYYY-MM-DD lower bound.

## `periodEndTo` (type: `string`):

Inclusive YYYY-MM-DD upper bound.

## `dateAddedFrom` (type: `string`):

Inclusive source timestamp or date lower bound.

## `dateAddedTo` (type: `string`):

Inclusive source timestamp or date upper bound.

## `entityNameContains` (type: `string`):

Unicode case-insensitive local substring.

## `minErrorCount` (type: `integer`):

Inclusive minimum source-provided error count.

## `minWarningCount` (type: `integer`):

Inclusive minimum source-provided warning count.

## `minInconsistencyCount` (type: `integer`):

Inclusive minimum source-provided inconsistency count.

## `onlyWithQualityIssues` (type: `boolean`):

Require at least one source-provided error, warning, or inconsistency.

## `pageSize` (type: `integer`):

Records requested per source API page.

## `maxPages` (type: `integer`):

Omit for no page cap.

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

Omit for no item cap.

## `monitoring` (type: `boolean`):

Compare filing hashes with versioned state across runs.

## `emitMode` (type: `string`):

newOrChanged requires monitoring.

## `requestDelayMillis` (type: `integer`):

Minimum delay before each subsequent source request.

## `requestTimeoutMillis` (type: `integer`):

Per-attempt source request timeout.

## `maxRequestRetries` (type: `integer`):

Retries for timeout, HTTP 408, 429, and 5xx failures.

## Actor input object example

```json
{
  "mode": "catalog",
  "entityIdentifiers": [],
  "countries": [],
  "minErrorCount": 0,
  "minWarningCount": 0,
  "minInconsistencyCount": 0,
  "onlyWithQualityIssues": false,
  "pageSize": 100,
  "maxItems": 5,
  "monitoring": false,
  "emitMode": "all",
  "requestDelayMillis": 2000,
  "requestTimeoutMillis": 30000,
  "maxRequestRetries": 4
}
```

# Actor output Schema

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

No description

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

No description

## `diagnostics` (type: `string`):

No description

# 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 = {
    "maxItems": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("truenorth/european-esef-filing-quality-monitor").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 = { "maxItems": 5 }

# Run the Actor and wait for it to finish
run = client.actor("truenorth/european-esef-filing-quality-monitor").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 '{
  "maxItems": 5
}' |
apify call truenorth/european-esef-filing-quality-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,truenorth/european-esef-filing-quality-monitor"
        }
    }
}
```

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/fcg34ePRc6LElJGWk/builds/mxvU018qtGbbZuqpj/openapi.json