Company calendars API reference

Dividend and stock split calendars for a window of days

Overview

Company dividends and stock splits for a window of days, across every listed company we cover. Every request needs a Bearer key, and REST and MCP share one account quota.

Dates run from 30 days back to 90 days ahead, and one request spans at most 7 days. Leave start out for today in UTC, and leave end out for the same day as start. Outside that range the answer is 400 invalid_query, and a longer span is 400 range_too_large.

Only USA is covered for now. Another country returns 404 not_covered. Only companies in our symbol list appear, with our id and name, and the lines of one issuer are one row.

Base URL: https://api.narwhalapi.com. The MCP tool is company_calendars, with one action for each route below.

Plans and limits

What	Free	Basic	Pro
Dividends and splits calendars	Included	Included	Included

See pricing for plan prices and monthly request limits. Each request counts as one call unless a route says otherwise.

Each request is one call, whatever the number of rows.
A company without an active listing in our symbol list is left out.
A split ratio is new shares for old: 4:1 gives four for one, and 1:10 is a reverse split.

Endpoints

Every route is a GET and needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.

Company dividends calendar

GET /v1/calendars/dividends

Dividends going ex in the window: the ex-date, the amount per share and its currency. start and end are inclusive days (YYYY-MM-DD); left out, start is today (UTC) and end is start. Dates run from 30 days back to 90 days ahead (400 invalid_query outside), and a request spans at most 7 days (400 range_too_large). country is USA, the only country for now (404 not_covered). Only companies in our symbol list appear, with our id and name; units and share classes of one issuer are one row. Open to every plan and one call a request.

MCP: tool company_calendars, action dividends.

Parameters

Parameter	Where	Required	Type	Meaning
`start`	query	No	date	First day (YYYY-MM-DD), inclusive. Left out means today (UTC). Between 30 days back and 90 days ahead.
`end`	query	No	date	Last day, inclusive. Left out means `start`. At most 7 days from `start` (400 range_too_large).
`country`	query	No	string	Three-letter country code of the listing. Left out means USA, the only country for now (another one is 404 not_covered).

Response fields

Field	Type	Sent	Meaning
`entries`	list of object	Always	By ex-date, then id.
`entries[].ex_date`	date	Always	First day the share trades without the dividend.
`entries[].id`	string	Always	Our listing id, for example XNAS:MSFT.
`entries[].symbol`	string	Always	The listing's ticker.
`entries[].name`	string	Always	The company's name.
`entries[].amount`	string	Always	Dividend per share, in `currency`.
`entries[].currency`	string	Always	Currency of `amount`.
`next_cursor`	string	Always	Always null: a request of at most 7 days is one page.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/calendars/dividends?start=2026-10-26&end=2026-11-01"

{
  "entries": [
    {
      "ex_date": "2026-10-29",
      "id": "XNYS:KO",
      "symbol": "KO",
      "name": "The Coca-Cola Company",
      "amount": "0.51",
      "currency": "USD"
    }
  ],
  "next_cursor": null
}

Company splits calendar

GET /v1/calendars/splits

Stock splits taking effect in the window, with the ratio as new shares for old (4:1 gives four for one; 1:10 is a reverse split). start and end are inclusive days (YYYY-MM-DD); left out, start is today (UTC) and end is start. Dates run from 30 days back to 90 days ahead (400 invalid_query outside), and a request spans at most 7 days (400 range_too_large). country is USA, the only country for now (404 not_covered). Only companies in our symbol list appear, with our id and name; units and share classes of one issuer are one row. Open to every plan and one call a request.

MCP: tool company_calendars, action splits.

Parameters

Parameter	Where	Required	Type	Meaning
`start`	query	No	date	First day (YYYY-MM-DD), inclusive. Left out means today (UTC). Between 30 days back and 90 days ahead.
`end`	query	No	date	Last day, inclusive. Left out means `start`. At most 7 days from `start` (400 range_too_large).
`country`	query	No	string	Three-letter country code of the listing. Left out means USA, the only country for now (another one is 404 not_covered).

Response fields

Field	Type	Sent	Meaning
`entries`	list of object	Always	By date, then id.
`entries[].date`	date	Always	First day the shares trade split-adjusted.
`entries[].id`	string	Always	Our listing id, for example XNAS:MSFT.
`entries[].symbol`	string	Always	The listing's ticker.
`entries[].name`	string	Always	The company's name.
`entries[].ratio`	string	Always	New shares for old: 4:1 gives four shares for each one held; 1:10 is a reverse split.
`next_cursor`	string	Always	Always null: a request of at most 7 days is one page.

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/calendars/splits?start=2026-10-26&end=2026-11-01"

{
  "entries": [
    {
      "date": "2026-10-28",
      "id": "XNAS:EXMP",
      "symbol": "EXMP",
      "name": "Example Holdings Inc.",
      "ratio": "4:1"
    }
  ],
  "next_cursor": null
}

Errors

Errors use the shared problem shape with a request_id. See Errors and quota for the shape and the quota headers. Failed requests are not charged.

Code	Status	Meaning
`invalid_query`	400	A parameter is missing, unknown, repeated or outside its range.
`range_too_large`	400	The window is longer than the route allows.
`not_covered`	404	The market, country or company is not covered yet.
`quota_exceeded`	429	Your plan has fewer calls left than the request needs.
`area_unavailable`	503	This area cannot answer right now.