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 the current week (isPreview: true); PRO keys see the full forward window (about 30 days). Field richness is identical across tiers: the gate is how far ahead you can see, 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 the current week with isPreview: true; PRO returns the full forward window.

Parameters:

Parameter	Type	Required	Default	Description
ticker	string	No	-	Filter to a single ticker (e.g. AAPL)
week	string	No	-	Shorthand date window: this (current Mon-Sun) or next
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 the current 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 this week's 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
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 the current week.