Earnings dates

Given an array of tickers and/or ISINs, return their calendar events within a window (today + days, or an explicit from/to range). ISINs are resolved to tickers via ticker_reference.

Upcoming calendar events (from calendar_events) within a date window — today, next 5d, 14d, or an explicit from/to range — enriched with ticker / name / ISIN.

List all tickers currently in the earnings MongoDB cache.

Ticker mit widerspruechlicher Identitaet werden ausgelassen und nur gezaehlt -- sie stehen im Cache, sind aber keiner Firma sicher zuzuordnen.

Manually invalidate the cached earnings for a ticker. The next call to /confidence or /fetch will re-fetch live data.

Return the earnings calendar for a ticker, filtered by confidence.

This endpoint reads from MongoDB only — no live fetch. If the ticker is not yet cached, call first:

• GET /earnings/fetch/{identifier}?origin=yf (fast, always saves)
• GET /earnings/confidence/{identifier} (all sources, saves if conf ≥ 0.9)

Accepts: ticker, ISIN, CIK, WKN (prefix notation for all-digit WKNs: wkn:623100).

Fetch earnings from all sources and compute cross-source confidence scores. Results are cached in MongoDB for cache_hours hours.

The state of the dates lane in one call.

Answers: how many tickers have any dates at all, how many are confirmed, how large the repair backlog is, and which source actually delivers. This is the endpoint on which repair progress can be read off.

Batch-fetch earnings for multiple identifiers in parallel (max 5 concurrent).

Accepts a list of identifiers — each can be ticker, ISIN, WKN (with wkn: prefix), CIK, or any format supported by the single-fetch endpoint.

origin applies to all items in the batch.

Start a background job that fetches earnings for a large list of identifiers.

Returns immediately with a job_id — poll GET /earnings/jobs/{job_id} for progress.

• identifiers: plain list of tickers, ISINs, WKNs, or CIKs (no limit)
• origin: yf (fast, always saves) or all (5 sources, saves if confidence ≥ 0.9)
• concurrency: parallel fetches (default 10, max 50)

``json {

"identifiers": ["AAPL", "MSFT", "DE0006231004", "isin:US5949181045"],
"origin": "yf",
"concurrency": 20

} ``

Collect earnings data and save it to MongoDB.

origin=tiered (default) yfinance first; if it returns nothing, or

less than confidence 0.9, the remaining five sources
follow. On a single lookup confirmation is worth the
cost, so unlike in bulk mode this escalates even on a
hit.

origin=yf yfinance.info only. A diagnostic mode. Unsuitable for

bulk runs, because only a single source is asked and an
empty result then looks like a genuine "no date" — use
tiered for that.

origin=massive massive.com /v3/reference/tickers/{ticker}/earnings.

Returns full history plus all future quarters.

origin=all All six sources, always contacted.

Data is stored as soon as at least one date has been found; the quality sits in the quality sub-document (confirmed from confidence 0.9). A hit from only one source is therefore not lost, but stays recognisable as such.

Accepts any identifier:

List the most recent bulk jobs (newest first).

Poll the status of a bulk fetch / refresh job.

status values:

• pending — queued, not yet started
• running — in progress (done / total shows progress)
• done — finished (check failed for partial errors)

Start a background job that re-fetches earnings for every ticker already in the MongoDB earnings_cache.

• stale_only: when true, only re-fetch entries older than stale_hours
• stale_hours: age threshold in hours (default 24)
• origin / concurrency: same as /fetch/bulk

Returns immediately with a job_id.

Start a background job that fetches earnings for all ticker_reference entries that already have an ISIN and match the requested security types.

Defaults:

• market="stocks"
• active=true
• type_filters=["CS", "ADRC"]
• include_untyped_stocks=false

ADRS is accepted as an alias and normalized to ADRC.

Start a background job that fetches earnings for every ticker stored in the ticker_reference collection (populated via POST /tickers/sync).

Filters narrow down which tickers are included (default: active stocks). Returns immediately with a job_id — poll GET /earnings/jobs/{job_id}.

Fetches dates for tickers that have none yet, or only unconfirmed ones.

Two passes:

• only_empty=true (default) — documents without any date at all. The

$exists predicate on dates.0 structurally excludes documents that
already carry dates, so they cannot consume budget.

• only_unconfirmed=true — documents that have dates but whose

quality.confirmed is false. Here the fetch escalates until a second
source confirms.

Resumable without offsets: the worklist is derived from probe_at and quality.empty_streak, sorted by probe_at ascending. Aborting mid-run costs nothing — the next call derives the remaining tickers afresh. When nothing is due any more the answer is 422; the cron loop treats that as success and therefore terminates on its own.

Incremental earnings sync. Walks ticker_reference and re-fetches only the tickers whose cached earnings in earnings_cache are missing or older than max_age_days (checked against earnings_cache.fetched_at).

Identifier resolution per ticker:

1. ticker_reference.isin            → isin:<ISIN>
2. fallback yahoo_profiles.yahoo_symbol (joined on ticker) → ticker:<SYMBOL>
3. last resort: the raw ticker        → ticker:<TICKER>

Fetches in tiers (origin=tiered). Returns a job_id — poll GET /earnings/jobs/{job_id}.