Finance & Market Data
FMP Earnings Calendar API Python Example & Workflow
Use the FMP Earnings Calendar API with Python, normalize dates and estimates, validate changes, handle rate limits, and build reliable earnings workflows.
Published: April 12, 2026 · By the QVeris Team
TL;DR
Use FMP's stable /stable/earnings-calendar endpoint with an API key and explicit from/to dates. FMP specifically recommends a date window when requesting future events.
Dates, BMO/AMC timing, EPS estimates, revenue estimates, and event availability may change. Keep snapshots and compare revisions instead of overwriting the only record.
Map provider symbols to stable security identity, separate event date from fiscal period, preserve the provider session label, and attach retrieval time and validation status.
The calendar tells you what is scheduled or reported; it does not prove an exchange-local timestamp, filing publication time, or final company confirmation unless those are validated separately.
Recommended pattern: fetch a bounded window, store the raw payload, normalize each record into your own event schema, diff it against the prior snapshot, and emit alerts only from accepted changes.
Prerequisites and architecture boundary
This implementation is for research dashboards, portfolio calendars, earnings-monitoring agents, and pre/post-event workflows. You need an FMP API key, an allowed plan, a date-window policy, secure secret storage, and a destination such as a database or queue.
Store FMP_API_KEY in a secret manager or environment variable. Never embed it in browser JavaScript, source control, screenshots, logs, or agent prompts.
Choose a bounded UTC date range, for example today through the next seven days. Smaller repeatable windows simplify retries and revision detection.
Maintain a security master that maps symbol, exchange, issuer, security, and identifier history. A ticker alone is not a durable key.
Use a scheduler for repeat retrieval and persist the previous snapshot or hash. Without state, the system cannot distinguish a new event from a revised event.
FMP Earnings Calendar API Python example
The official stable endpoint is https://financialmodelingprep.com/stable/earnings-calendar. The example below supplies an API key and explicit date window, raises on HTTP errors, validates the JSON shape, and never logs the credential.
import os
from datetime import date, timedelta
import requests
API_URL = "https://financialmodelingprep.com/stable/earnings-calendar"
API_KEY = os.environ["FMP_API_KEY"]
start = date.today()
end = start + timedelta(days=7)
response = requests.get(
API_URL,
params={
"from": start.isoformat(),
"to": end.isoformat(),
"apikey": API_KEY,
},
timeout=(3.05, 20),
)
response.raise_for_status()
events = response.json()
if not isinstance(events, list):
raise ValueError("Expected the FMP earnings calendar to return a list")
print(f"received {len(events)} earnings events")Understand the response before writing business logic
FMP documents announcement date, estimated EPS, and actual EPS as core earnings-calendar data. Its related earnings documentation also describes release-session labels such as before market open (BMO) and after market close (AMC), while the changelog records fields including fiscalDateEnding and updatedFromDate. Inspect the live payload available to your plan before relying on any field.
| Field concept | Use | Do not assume |
|---|---|---|
| symbol | Provider-facing security lookup | A permanent global identity |
| date | Scheduled or reported calendar date | An exchange-local exact timestamp |
| time / session | BMO, AMC, or other provider timing label | A precise clock time |
| epsEstimated / eps | Expected and actual EPS when available | That missing actual EPS means zero |
| revenueEstimated / revenue | Expected and actual revenue when returned | Consistent currency and scale without validation |
| fiscalDateEnding | The fiscal period associated with the event | The same thing as announcement date |
| updatedFromDate | Provider update context when present | A complete revision audit trail by itself |
Normalize event date, fiscal period, session, and estimates
Keep the raw FMP record unchanged, then create a separate canonical event. A normalized record should make uncertainty visible instead of turning a date or BMO/AMC label into a false exact timestamp.
{
"event_id": "earnings:security-123:2026-08-06",
"issuer_id": "issuer-123",
"security_id": "security-123",
"symbol_as_reported": "EXAMPLE",
"event_date": "2026-08-06",
"release_session": "after_market_close",
"release_time_precision": "session_only",
"exchange_timezone": "America/New_York",
"fiscal_period_end": "2026-06-30",
"eps_estimate": 1.23,
"eps_actual": null,
"revenue_estimate": null,
"revenue_actual": null,
"provider": "financial_modeling_prep",
"retrieved_at": "2026-08-03T08:00:00Z",
"validation_status": "accepted_with_unknowns",
"raw_record_hash": "sha256:..."
}Step-by-step earnings monitoring implementation
Retrieve a small overlap around the target period—for example yesterday through the next seven days—so delayed jobs do not create silent gaps.
Before transformation, store request parameters, HTTP status, retrieval time, response hash, and the raw record or an immutable object reference.
Resolve the symbol, map BMO/AMC to controlled session values, attach exchange timezone, and keep fiscal period distinct from event date.
Use security identity plus event date and fiscal period. Do not deduplicate only on symbol or only on date.
Classify new, removed, rescheduled, session-changed, estimate-revised, and actual-reported events. Preserve both old and new values.
Generate one event key per accepted change so retries do not send duplicate notifications or trigger the same downstream job twice.
Validate each event before it reaches an alert or agent
Control API keys, rate limits, caching, and alert load
| Control | Recommended implementation | Failure prevented |
|---|---|---|
| Secret handling | Server-side secret store, rotation, least privilege, redacted logs | Credential leakage and uncontrolled use |
| Bounded windows | Small rolling range with intentional overlap | Wasteful requests and missed events |
| Cache policy | Cache raw window responses; invalidate by schedule and revision needs | Duplicate calls and inconsistent readers |
| Backoff | Jittered bounded retry for transient errors; respect 429 guidance | Retry storms and quota exhaustion |
| Alert fan-out | Queue accepted changes and deduplicate by event version | Duplicate messages and downstream spikes |
Do not hardcode plan quotas in application logic or this guide. Verify current endpoint access, call limits, commercial rights, and pricing in FMP's official plan documentation before deployment.
Common FMP earnings calendar failure modes
Supply both from and to, verify ISO dates and API-key access, and test a wider known earnings window. FMP's help content specifically calls out the need for a date range.
Check multiple listings, duplicate provider records, rescheduled events, and fiscal-period differences. Resolve security identity before deduplication.
Treat this as a revision, not delete-plus-new noise. Link old and new versions, record detection time, and withdraw obsolete scheduled alerts.
A session label is not an exact time. Keep session-only precision and apply the listing exchange's timezone and calendar only when scheduling a local operational window.
Null means unavailable at that retrieval time, not zero. Schedule post-release refreshes and record when the actual first appears.
Separate authentication, subscription access, and rate-limit handling. Do not hide these conditions behind an empty calendar result.
Where QVeris fits in an earnings workflow
FMP is the data provider for this calendar endpoint. QVeris can help an agent discover and inspect related financial, transcript, filing, news, and notification capabilities before calling them. Your application still owns credentials, the normalized event store, licensing checks, revision logic, validation, and alert policy.
Find calendar, transcript, filing, press-release, quote, and notification capabilities based on the workflow goal.
Review schema, provider, cost, latency, date coverage, and required parameters before execution.
Execute the selected capability and retain request parameters, provider trace, retrieval time, status, and raw evidence.
Normalize into the event contract, compare revisions, then trigger watchlists, post-release retrieval, variance checks, or human review.
FMP Earnings Calendar API FAQ
FMP documents the stable endpoint as https://financialmodelingprep.com/stable/earnings-calendar. Supply an API key and an explicit from/to date window, especially for future events.
FMP states that future events require both from and to parameters. Also verify date formatting, API-key access, subscription coverage, and whether the window contains scheduled reports.
No. Dates, sessions, EPS estimates, and revenue estimates can change. Store retrieval time and a version or hash, then compare snapshots rather than overwriting the only copy.
Treat them as sessions, not precise timestamps. Preserve the provider value, map it to a controlled enum, and use the exchange calendar and timezone when scheduling alerts.
Yes, but it should consume validated normalized records rather than unchecked raw data. Preserve source, retrieval time, event status, estimates, fiscal period, and revision history.
Verify the endpoint, changes, timing, and access
FMP documentation is the source of truth for current parameters, fields, cycle times, access tiers, and commercial terms. Re-run contract tests when FMP changes the stable endpoint or response schema.
A verified profile link does not guarantee entitlement, field availability, price or current execution success; inspect the current contract before calling.