Coverage and data quality

Arche reports what it has and how good it is, rather than making you infer coverage from empty responses. A request that finds nothing is answered, not failed — so before treating an empty result as a gap in the market, check whether it is a gap in coverage.

Check coverage first

Two questions have separate endpoints:

Both are cheap relative to a full extraction job, so it is worth querying them at the start of a backfill rather than discovering the boundary partway through.

Company coverage

Retrieve the coverage summary for a single issuer:

curl -X GET "https://api.arche.fi/v1/coverage/companies/0000320193" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

List coverage across issuers with deterministic ordering — cik ascending, tie-broken on the canonical company row — using the standard paginated envelope:

curl -X GET "https://api.arche.fi/v1/coverage/companies?page=1&page_size=50" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

For a narrower question — the latest filing on record and statement-version counts by type — use the company completeness summary:

curl -X GET "https://api.arche.fi/v1/edgar/companies/0000320193/completeness" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

Reading the coverage response

Two fields mean something narrower than their names suggest, and both are easy to misread as a quality score.

The *_populated counters pair with each *_expected field, and the per-statement ratios — income_statement_completeness, balance_sheet_completeness, cash_flow_statement_completeness — report the same period-level measure for one statement type.

Choosing companies on Free

Every paid plan covers every company Arche serves. The Free plan covers any 25 companies you choose. There is no list to pick from: a company takes one of your 25 slots the first time a request reaches it, and keeps the slot for as long as you keep querying it. A slot frees itself 30 days after the company was last queried.

See which companies you hold and when each slot frees:

curl -X GET "https://api.arche.fi/v1/coverage/selection" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

A mistyped CIK takes a slot like any other. Give one back straight away rather than waiting 30 days:

curl -X POST "https://api.arche.fi/v1/coverage/selection/release" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cik": "320193"}'

Releasing a company you do not hold succeeds and changes nothing.

When all 25 slots are in use, a request for a new company returns 403 with the code COVERAGE_SELECTION_FULL. details lists the companies the request could not reach (refused_ciks), the ones you hold (held_ciks), and the release endpoint. Release a slot, wait for one to expire, or move to a paid plan, which covers every company.

Metric coverage

Coverage for one canonical metric across the corpus:

curl -X GET "https://api.arche.fi/v1/coverage/metrics/REVENUE" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

Representative response:

{
  "data": {
    "metric": "REVENUE",
    "company_count": 7100,
    "years_covered": 18,
    "statement_count": 42525
  }
}

The metric name must be one Arche stores as a canonical statement metric. A name it does not serve is refused with 400, listing the names it accepts:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "http_status": 400,
    "message": "Unknown metric 'GROSS_MARGIN'. Expected one of: ACCOUNTS_PAYABLE, …, TOTAL_ASSETS.",
    "details": {},
    "trace_id": "…"
  }
}

GROSS_MARGIN is refused here because it is a derived ratio, computed on the modeling routes rather than mapped from a filing. A zero from this endpoint now always means the metric genuinely has no coverage, never that the name was wrong. See Metric catalog for which names live where.

Population statistics are scoped to a cohort and a filing form type, so both parameters are required. form_type takes the SEC's own spelling — 10-K or 10-Q, not FORM_10_K, which returns 400 VALIDATION_ERROR:

curl -X GET "https://api.arche.fi/v1/coverage/metrics?cohort=all&form_type=10-K" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

Representative response:

{
  "page": 1,
  "page_size": 50,
  "total": 4,
  "items": [
    {
      "metric_name": "TOTAL_ASSETS",
      "statement_type": "BALANCE_SHEET",
      "form_type": "10-K",
      "fiscal_period": "FY",
      "cohort": "ALL",
      "populated_rate": "1.000000",
      "sample_size": 43,
      "computed_at": "2026-06-07T19:08:44Z"
    }
  ]
}

These rows are precomputed on a sampled cohort, so sample_size is small and computed_at can lag. Use this endpoint for a rough population rate, and the per-metric route above for corpus-wide counts.

ALL is the only cohort with statistics today. A cohort that has never been computed is refused rather than answered with an empty page, and the refusal names the cohorts that do have rows:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "http_status": 400,
    "message": "No coverage statistics exist for cohort 'sp500'. Cohorts with statistics: ALL.",
    "details": {},
    "trace_id": "…"
  }
}

sp500 and dow30 are valid cohort labels that simply have no computed statistics yet — the refusal distinguishes that from a cohort in which no metric is populated, which an empty page could not.

Results are ordered statement_type, then fiscal_period, then metric_name, all ascending.

Data-quality issues

Persisted data-quality issues are queryable directly. Ordering is deterministic: severity descending, then cik, fiscal_year, fiscal_period, rule_code, and issue_id ascending, with nulls last on the fiscal fields.

curl -X GET "https://api.arche.fi/v1/data-quality/issues" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

To see quality signals in the context of the statement they describe, request the normalized statement with its DQ overlay. This identifies a statement by its full identity, not just the company:

curl -X GET "https://api.arche.fi/v1/edgar/companies/0000320193/statements/dq/overlay?statement_type=INCOME_STATEMENT&fiscal_year=2023&fiscal_period=FY&version_sequence=2" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

Reconciliation

Reconciliation checks answer whether a statement is internally consistent — whether the parts sum, and whether balances roll forward.

The ledger holds a row only where a rule actually produced a result, so most statement identities have none and answer with an empty page. Start with the summary to find the identities worth opening, then read the ledger for one of them. Going the other way round mostly returns total: 0, which says nothing was evaluated, not that nothing failed.

PASS, WARN and FAIL counts by category across a multi-year window:

curl -X GET "https://api.arche.fi/v1/edgar/reconciliation/summary?cik=0000789019&statement_type=BALANCE_SHEET&fiscal_year_from=2015&fiscal_year_to=2026" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

Representative response:

{
  "data": [
    {
      "fiscal_year": 2026,
      "fiscal_period": "Q2",
      "version_sequence": 5,
      "rule_category": "ROLLFORWARD",
      "pass_count": 0,
      "warn_count": 2,
      "fail_count": 1
    }
  ]
}

Each row names a full statement identity. Pass that identity — including version_sequence, which is required — to the ledger for the individual rule results:

curl -X GET "https://api.arche.fi/v1/edgar/reconciliation/ledger?cik=0000789019&statement_type=BALANCE_SHEET&fiscal_year=2026&fiscal_period=Q2&version_sequence=5" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

Representative response:

{
  "page": 1,
  "page_size": 200,
  "total": 3,
  "items": [
    {
      "cik": "0000789019",
      "statement_type": "BALANCE_SHEET",
      "fiscal_year": 2026,
      "fiscal_period": "Q2",
      "version_sequence": 5,
      "rule_id": "cash_rollforward_adjacent_periods",
      "rule_category": "ROLLFORWARD",
      "status": "WARNING",
      "severity": "NONE",
      "expected_value": null,
      "actual_value": null,
      "delta": null,
      "notes": {
        "details": { "reason": "INCOMPARABLE_CASH_SCOPES" }
      }
    }
  ]
}

A WARNING with severity: NONE and a reason in notes is the rule declining to compare rather than finding a discrepancy — INCOMPARABLE_CASH_SCOPES here means the two periods define cash differently. Read status together with severity and notes; a warning is not automatically a defect in the filing.

The point-in-time financials response embeds a condensed version of these signals under _meta.reconciliation and _meta.trust_score, so a single as_of query tells you both what was knowable and how well it reconciles.

Accounting identities

A statement read from /v1/edgar/companies/{cik}/statements with include_normalized=true, or from /v1/edgar/companies/{cik}/filings/{accession_id}/statements, carries the accounting identities checked against it under normalized_payload._meta.identity:

{
  "pass_rate": "1",
  "total_rules_count": 6,
  "supported_rules_count": 3,
  "skipped_rules_count": 3,
  "failed_rules_count": 0,
  "checks": [
    {
      "rule_id": "E11_IDENTITY_BALANCE_SHEET",
      "statement_type": "BALANCE_SHEET",
      "fiscal_year": 2026,
      "fiscal_period": "Q3",
      "status": "PASS",
      "severity": "NONE",
      "expected_value": "383266000000",
      "actual_value": "383266000000",
      "delta": "0",
      "tolerance": "38326600.0000"
    }
  ]
}

These checks are stricter than the checks that decide whether a statement is published, so a published statement can report a failing identity. Use the delta and tolerance to judge whether the difference matters to you.

Deterministic replay

Supported queries can be executed through a deterministic endpoint. It records an immutable manifest with the result, and gives you a replay token that returns that exact response later:

curl -X POST "https://api.arche.fi/v1/query/execute" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "query_type": "financial_state_time_series",
    "as_of_date": "2025-03-31",
    "include_result": true,
    "parameters": {
      "cik": "0000320193",
      "fiscal_year_from": 2023,
      "fiscal_year_to": 2024,
      "period_type": "annual",
      "page": 1,
      "page_size": 50
    }
  }'

query_type is required. parameters carries the arguments for that query type, and as_of_date applies the no-lookahead boundary. Four query types are supported:

For financials_as_of, the manifest's snapshot_hashes holds the hash of the as-of snapshot the answer was read from. It's the same snapshot_hash the as-of financials endpoint returns. The time-series types read no snapshot, so their list is empty; they are pinned by input_hash instead.

The returned replay token can be looked up later:

curl -X GET "https://api.arche.fi/v1/query/replay/REPLAY_TOKEN" \
  -H "X-Api-Key: $ARCHE_API_KEY" \
  -H "X-Request-ID: $(uuidgen)" \
  -H "Accept: application/json"

Replay returns the original response exactly as it was first returned, in result. It is checked against the manifest's result_hash before it is served. Replay also re-runs the query at the manifest's as-of date, and replay_mode reports what that re-run found:

stored_result_available is false only for tokens minted before results were stored. For those, result is present when the re-run reproduces the original hash, which proves it is the same response.