Skip to content
/api/v1/financials/status

System status for the XBRL pipeline: table row counts, last sync times, and pipeline health.

System status for the XBRL pipeline: table row counts, last sync times, and pipeline health.

freeSince v3.4.0

Why use this

Monitor pipeline health and data freshness.

Common use case

Admin dashboards, health checks, debugging data staleness issues.

System-status probe for the XBRL ETL pipeline (Phase 49+). No authentication, free (cost: 0). Returns table row counts (raw facts → standardized metrics → derived ratios), recent-sync timing per pipeline step, overall pipeline health, and staleness hours. The right endpoint for: status-page dashboards, ETL monitoring, debugging data-staleness alerts, and pre-flight checks before downstream consumers fetch financial data. Pair with GET /api/v1/financials/changes for the per-ticker delta feed and GET /api/v1/status for the broader system-wide health view (covers all FinRadar services beyond just XBRL).

Response schema

FieldTypeNullableDescription
data.databaseobjectnoRow counts for each XBRL pipeline table. Useful for capacity-planning and ETL-completeness checks. Sub-fields: `cf_facts` (raw concept-level facts — typically 40-50M post-Phase-49), `cf_standardized_metrics` (Phase-49 standardized metrics — typically 2-3M), `cf_derived_metrics` (Phase-49 derived ratios — typically 1.5-2M), `cf_companies` (covered ticker count — typically 7000-7300), `cf_concepts` (unique us-gaap + dei concepts seen — typically 20K-25K).
data.database.cf_factsintegernoTotal raw concept-level facts in the system (e.g. one row per (cik, concept, period, value) tuple from EDGAR's companyfacts JSON). Grows ~50K rows/day during normal filing cadence.
data.database.cf_standardized_metricsintegernoTotal Phase-49-standardized metrics (e.g. `revenue` collapsing across `us-gaap:Revenues` + `us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax` + `us-gaap:SalesRevenueNet`). One row per (ticker, fiscal-period, metric-name).
data.database.cf_derived_metricsintegernoTotal derived ratios (e.g. ROE, debt-to-equity, gross_margin). One row per (ticker, fiscal-period, ratio-name). Computed nightly from `cf_standardized_metrics`.
data.database.cf_companiesintegernoDistinct ticker count with at least one parsed XBRL fact. Equals the result count of `/api/v1/financials/tickers` with empty `q`.
data.last_updatestringnoISO-8601 UTC timestamp of the most-recent ETL completion (any step). Compare against current time for staleness detection.
data.recent_syncs[]arraynoRecent ETL step executions, sorted by `time DESC`. Each row represents one daily-pipeline step run.
data.recent_syncs[].stepstringnoPipeline step name. Values: `companyfacts_download` (EDGAR bulk JSON download), `facts_load` (ingest into cf_facts), `standardized_metrics` (Phase-49 standardization pass), `derived_metrics` (Phase-49 ratio computation), `delta_detection` (changes-feed population).
data.recent_syncs[].timestringnoISO-8601 UTC timestamp of step completion.
data.recent_syncs[].recordsintegernoRecords processed in this step run. For incremental loads this is the delta count; for full re-syncs (rare) this is the total table count.
data.recent_syncs[].duration_secnumbernoStep duration in seconds. Use as performance baseline (e.g. companyfacts_download typically 400-600 sec; standardized_metrics typically 150-200 sec). Spikes >2x baseline indicate degradation.
data.recent_syncs[].statusstringnoStep outcome: `success` / `failed` / `partial` / `skipped`. Failed steps surface in `pipeline_health: degraded`.
data.pipeline_healthstringnoOverall pipeline health summary. Values: `healthy` (last 4 step runs all succeeded, staleness < 24h), `degraded` (any failed step in last 24h OR staleness > 24h but < 48h), `critical` (staleness > 48h OR multiple consecutive failures). For status-page dashboards consume this directly; for deep diagnostics inspect `recent_syncs[]`.
data.staleness_hoursnumbernoHours since `last_update` (rounded to 1 decimal). Useful for staleness-alert thresholds (e.g. alert if > 30h — XBRL pipeline runs daily ~01:00 UTC, so 24-30h is normal weekend/holiday cycle).

Sample response

·
  • "status": "success"
  • "data":
    • "database":
    • "last_update": "2026-05-02T01:45:00Z"
    • "recent_syncs":
    • "pipeline_health": "healthy"
    • "staleness_hours": 8.5
    }
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected server-side failure. Retry with backoff; report if persistent.

Code samples

curl "https://api.finradar.ai/api/v1/financials/status" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).