Calendar API

Overview

The Calendar API exposes scheduled market events. It currently includes a discovery endpoint and an earnings calendar with report dates, session timing, fiscal quarters, confirmation status, and consensus EPS estimates.

Use cases:

• Build a pre-earnings watchlist: which of my tickers report in the next two weeks?
• Screen for catalysts in a date window (e.g. all confirmed reports between two dates)
• Feed earnings dates into a research agent so it knows when a thesis has a catalyst
• Cross-reference upcoming earnings with sentiment, insider, and institutional signals
• Separate before-open vs after-close reporters for session-aware planning

Scope: schedule data only. The default lower bound is the beginning of the current week, so the response can include dates that have already passed. An earlier from bound can reach older schedule rows that remain in the current snapshot. These rows contain schedule fields only, never actual reported results. Use the Earnings Analysis API for reported quarters: GET /api/v1/earnings/recent lists recent reports, and GET /api/v1/stocks/{ticker}/earnings-summaries returns the quarter's headline, KPI highlights, guidance, and call summary. For standardized figures use GET /api/v1/stocks/fundamentals and GET /api/v1/stocks/{ticker}/kpis.

Access: Every call requires an API key. FREE-tier keys receive the first week of the requested window with isPreview: true. PRO keys receive all matching rows available in the current snapshot. With no date parameters, the public lower bound is the Monday of the current US Eastern week. Both tiers receive the same event fields. Anonymous calls return 401 api_key_required.

---

GET /api/v1/calendar

Discovery endpoint. Lists the calendars exposed by this family so an agent can find them without hardcoding paths.

Authentication: API key required. This call does not consume monthly quota (metadata only); the per-minute rate limit still applies.

Parameters: none.

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/calendar"

Example Response:

{
  "calendars": [
    {
      "type": "earnings",
      "path": "/api/v1/calendar/earnings",
      "description": "Upcoming company earnings dates (forward window)"
    }
  ]
}

---

GET /api/v1/calendar/earnings

Returns company earnings schedule rows that match the requested filters. Each entry carries the report date, session timing, fiscal quarter, confirmation status, and consensus EPS estimate.

By default the response covers the current week onward, measured from the Monday of the current US Eastern week rather than from today, so it can include dates earlier in the week that have already passed. To reach further back than the current week, pass an explicit from. Entries are schedule data in every case (report date, session timing, fiscal quarter, confirmation status, consensus EPS) and never carry what a company actually reported.

Authentication: API key required. FREE tier returns the first week of the requested window with isPreview: true; PRO returns all matching rows available in the current snapshot. metadata.windowStart and metadata.windowEnd report the resolved response window, and metadata.count always equals data.earnings.length.

Parameters:

Parameter	Type	Required	Default	Description
ticker	string	No	-	Filter to a single ticker (e.g. AAPL)
week	string	No	-	Shorthand date window. this is the Monday-to-Sunday week containing the current US Eastern (America/New_York) date; next is the seven days immediately after that week ends. The window rolls over at midnight Eastern. Used only when both from and to are absent
from	string	No	start of current week	Inclusive lower date bound, ISO YYYY-MM-DD. Pass an earlier date to reach older schedule rows still present in the current snapshot
to	string	No	-	Inclusive upper date bound, ISO YYYY-MM-DD. Setting to equal to from is a valid single-day query
confirmed	boolean	No	-	Two-sided. true returns only company-confirmed dates, false returns only the still-estimated ones. Omit it to get both
time	string	No	-	Filter by session: before_open, after_close, during_market, or unknown

Example Request:

curl -H "X-SentiSense-API-Key: ss_live_YOUR_KEY" \
  "https://app.sentisense.ai/api/v1/calendar/earnings?week=next&confirmed=true"

from sentisense import SentiSenseClient

client = SentiSenseClient(api_key="ss_live_YOUR_KEY")
cal = client.get_earnings_calendar(week="next")
for e in cal.earnings:
    eps = f"est. ${e['estimatedEps']}" if e.get("estimatedEps") is not None else "no estimate"
    print(f"{e['earningsDate']} {e['ticker']} ({e['earningsTime']}) {eps}")

Response Schema:

Field	Type	Description
isPreview	boolean	true when limited to one week (FREE tier)
previewReason	string	"PRO_REQUIRED" or null
totalCount	int	On a preview, the number of matching events before the FREE one-week limit
upgrade	object	Present only when isPreview is true. Carries plan, message, price, url and relay: surface message and url to your user in one line, then continue with the preview data
data	object	{ earnings: [...], metadata: {...} }

Earnings event object:

Field	Type	Description
ticker	string	Stock ticker symbol
companyName	string	Company name
earningsDate	string	Report date, ISO YYYY-MM-DD
earningsTime	string	before_open, after_close, during_market, or unknown. Never null or absent. unknown means no session claim applies, either because the timing is unpublished or because none is possible: some issuers release on a Saturday or Sunday ahead of a Monday call, and a weekend has no open or close for the report to sit against. A weekend earningsDate is legitimate data, not an error to filter out
fiscalQuarter	string	Fiscal period label (e.g. Q2 2026), nullable
confirmed	boolean	Whether the company has confirmed the date (vs. estimated/projected)
estimatedEps	number	Consensus EPS estimate, nullable

Metadata object:

Field	Type	Description
generatedAt	int | null	Snapshot build time in epoch seconds, or null if unavailable; it is not a content revision, so compare event rows to detect changes
windowStart	string | null	Inclusive lower bound of the resolved response window, ISO YYYY-MM-DD
windowEnd	string | null	Inclusive upper bound of the resolved response window, ISO YYYY-MM-DD
count	int	Number of events in this response
source	string	Always "sentisense"

Example Response (PRO):

{
  "isPreview": false,
  "previewReason": null,
  "data": {
    "earnings": [
      {
        "ticker": "AAPL",
        "companyName": "Apple Inc.",
        "earningsDate": "2026-04-30",
        "earningsTime": "after_close",
        "fiscalQuarter": "Q2 2026",
        "confirmed": true,
        "estimatedEps": 1.62
      },
      {
        "ticker": "MSFT",
        "companyName": "Microsoft Corp.",
        "earningsDate": "2026-04-29",
        "earningsTime": "after_close",
        "fiscalQuarter": "Q3 2026",
        "confirmed": false,
        "estimatedEps": 3.05
      }
    ],
    "metadata": {
      "generatedAt": 1776528000,
      "windowStart": "2026-04-20",
      "windowEnd": "2026-05-20",
      "count": 2,
      "source": "sentisense"
    }
  }
}

FREE tier: same shape with isPreview: true, previewReason: "PRO_REQUIRED", a totalCount of the full-window event count, and data.earnings limited to one week (the first week of the window you requested).

Errors:

These are the query-validation failures. Each returns 400 with
{"error": "invalid_parameter", "message": "..."}:

Condition	Message
time is not one of the four session values	time must be one of [...]
week is neither this nor next	week must be 'this' or 'next'
from or to is not an ISO YYYY-MM-DD date	from/to must be ISO dates (YYYY-MM-DD)
to is earlier than from, with both supplied explicitly	to must not be before from
confirmed cannot be converted to a boolean	Parameter 'confirmed' must be of type Boolean

Authentication and rate limiting are separate from query validation. A request with no key returns
401 before controller validation, and one past the per-minute limit returns 429 with
Retry-After: 60.

Additional behavior:

• Unknown query parameters are ignored, not rejected. ?typo=value returns the same
  calendar as the request without it, so a misspelled filter silently does nothing rather
  than narrowing the result or erroring.
• from and to accept an empty value as absent, not as a malformed date. Sending
  ?from= is the same as omitting it, and the default lower bound still applies.
• A filter that matches no reports is a 200, with an empty earnings array and
  count: 0. A ticker, date range, or filter combination with no matching row is not an error.

Coverage

The calendar covers the curated US equity universe, not the whole market. GET /api/v1/stocks
returns the current covered ticker list. Use that list when interpreting calendar results:

• A ticker present in /api/v1/stocks can still have no matching calendar row in the current
  snapshot, date window, or filter set. An empty result does not establish that no report is scheduled.
• A ticker absent from /api/v1/stocks is outside current coverage, so no calendar row is expected
  for it in any window. If you need a ticker we do not cover, ask us and we will look at adding it.

Identifying events and detecting changes

Events have no id or revision counter. Use ticker to correlate rows across snapshots, then compare
the full rows. A later snapshot can change any schedule field or omit a row.
metadata.generatedAt reports build time, not a content revision.

There is no cancellation or postponement status in an event. If a row disappears, the response does
not distinguish cancellation, postponement, expiry from the snapshot window, or a coverage change.
An unconfirmed date remains estimated regardless of how long it persists.

Refresh and caching

The calendar is rebuilt a few times a week, and dates change in between when companies announce.
No fixed schedule is guaranteed, so polling once a day is ample for a pre-earnings workflow and
polling faster will not surface dates sooner.

metadata.generatedAt is the build time carried by the current snapshot. It is not a content
revision, so treat a moved value as "worth re-reading" rather than an unchanged value as proof
that nothing changed.

Cache responses for as long as your application needs them. The constraint is redistribution, not
retention: see the API Terms of Service.

Related: Earnings Analysis API for the per-quarter analysis of reports already filed.