Calendar API

Overview

The Calendar API is a family of forward-looking market calendars. Each calendar is a time-ordered feed of scheduled events you can build alerts, screens, and positioning tools on top of. Earnings is the first feed; the /calendar/{type} namespace is built to grow.

The value of an earnings calendar is lead time. Knowing what reports tonight is commodity information. Knowing which companies report over the next several weeks, with consensus EPS and confirmation status attached, is what lets you position ahead of the event: build a pre-earnings watchlist, screen for catalysts in a given window, or wire earnings dates into a research agent. This is the kind of forward calendar that market-data services typically sell on upgraded plans; it is included in PRO.

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

Access: The earnings calendar requires an API key on every call. FREE-tier keys see one week (isPreview: true); PRO keys see the full forward window (about 30 days). On FREE the week you get back is the first week of the window you requested, so week=next returns next week. Field richness is identical across tiers: the gate is how much of the window you get back, not which columns you get. 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 upcoming company earnings, sorted by date. Each entry carries the report date, session timing, fiscal quarter, whether the company has confirmed the date, and the consensus EPS estimate.

By default the response covers the current week onward (already-reported earnings are excluded). To include earlier, already-reported dates, pass an explicit from.

Authentication: API key required. FREE tier returns one week with isPreview: true, taken from the start of the window you asked for; PRO returns the full forward window. Read metadata.windowStart / metadata.windowEnd to see exactly which days came back: they always bracket the events in data.earnings, and metadata.count always equals its 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, not at your local midnight. metadata.windowStart / metadata.windowEnd echo the resolved dates
from	string	No	start of current week	Inclusive lower date bound, ISO YYYY-MM-DD. Defaults to the current week's start (upcoming-only); pass an earlier date to include already-reported earnings. Overrides week
to	string	No	-	Inclusive upper date bound, ISO YYYY-MM-DD
confirmed	boolean	No	-	When true, only company-confirmed dates
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 events in the full PRO window before truncation (so you can show "showing N of totalCount")
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. Always one of these four; never null or absent. unknown means no session claim applies, either because the timing is not yet published or because none is possible: a few issuers release on a Saturday or Sunday ahead of a Monday call, and there is no weekend open or close for the report to sit against. A weekend earningsDate is therefore 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	When the snapshot was generated, epoch seconds
windowStart	string	First day covered, ISO YYYY-MM-DD
windowEnd	string	Last day covered, 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).