# Earnings API Agent Guide

This file is optimized for agents and code assistants. Prefer it over scraping the human UI.

## Base URL

```text
https://api.earningsapi.com
```

## Authentication

All public data requests require an API key as a query parameter.

```text
?apikey=YOUR_API_KEY
```

If the request already has query parameters, append with `&`.

```text
/v1/calendar/earnings?date=today&apikey=YOUR_API_KEY
```

## Endpoint Selection

| User intent | Endpoint | Required inputs | Do not use when |
| --- | --- | --- | --- |
| Earnings calendar by date, backfill, daily sync, upcoming reports by day | `GET /v1/calendar/earnings` | `date` | User asks for one company's earnings history |
| One company's historical or upcoming earnings | `GET /v1/earnings` | `symbol` | User asks for all companies reporting on a date |
| EPS/revenue beat or miss plus post-earnings price and volume reaction | `GET /v1/earnings-reactions` | `symbol` | User only needs the next earnings date |
| First trading day post-earnings movers of at least 5 percent | `GET /v1/earnings-movers` | `date` | User needs all earnings events, not only movers |
| Macro or economic calendar events | `GET /v1/calendar/economic` | `date` | User asks for earnings events |
| Company profile, sector, industry, country, type, market cap | `GET /v1/profile/{symbol}` | `symbol` in path | User asks for earnings dates only |
| Current market session state | `GET /v1/market-status` | none | User asks for full holiday schedule |
| Market holiday and early-close schedule | `GET /v1/market-holidays` | none | User asks whether the market is open right now |
| Upcoming IPO calendar | `GET /v1/calendar/ipo` | none | User asks for past IPOs |
| Upcoming dividend calendar | `GET /v1/calendar/dividends` | none | User asks for past dividends |
| Unusual volume movers | `GET /v1/unusual-volume` | none | User asks specifically for earnings movers |

## Date Rules

- `YYYY-MM-DD` is accepted on date-based endpoints.
- `today`, `yesterday`, and `tomorrow` are accepted on earnings and economic calendar endpoints.
- Relative dates are resolved in New York time.
- `GET /v1/earnings-movers` expects the trading date being measured.

## Workflow Recipes

### Earnings Calendar Backfill + Daily Sync

Use `GET /v1/calendar/earnings?date=YYYY-MM-DD`.

Loop historical dates for backfill. Loop future dates or `today` for scheduled refresh. Store each response by `date`, and keep `pre`, `after`, and `notSupplied` as separate buckets or flattened rows.

### Watchlist Earnings Monitor

Use `GET /v1/earnings?symbol=AAPL`.

Loop symbols in the watchlist. Pick the nearest future event from the returned list for next earnings date. Keep historical rows if the user needs backtesting or context.

### n8n Earnings Alert Workflow

Use `GET /v1/calendar/earnings?date=today` and optionally `date=tomorrow`.

Create a schedule trigger, add an HTTP Request node, send `apikey` as a query parameter, then format `pre`, `after`, and `notSupplied` into Slack, Telegram, or email.

### Google Sheets Calendar Sync

Use `GET /v1/calendar/earnings?date=YYYY-MM-DD`.

In Apps Script, store the key in `PropertiesService`, loop dates, fetch JSON, flatten rows, and write to the active sheet.

### Post-Earnings Reaction Screener

Use `GET /v1/earnings-reactions?symbol=AAPL`.

Loop watchlist symbols. Filter rows where `eps.beat` or `revenue.beat` is true. Rank by large `reactions[].priceChange`.

### Daily Earnings Movers Digest

Use `GET /v1/earnings-movers?date=YYYY-MM-DD`.

Run after the measured trading day. Split positive and negative `priceChange` rows and store the daily digest.

### Macro Calendar Filter

Use `GET /v1/calendar/economic?date=today&usmajor=true`.

Set `usmajor=true` for U.S. major indicators only. Show `time`, `actual`, `consensus`, and `previous`.

### Profile Enrichment Join

Use `GET /v1/profile/{symbol}` after collecting symbols from another endpoint.

Join `sector`, `industry`, `marketCap`, `country`, `type`, and `tags` onto calendar rows.

### Market Status / Holiday-Aware Scheduler

Use `GET /v1/market-status` for current session state and `GET /v1/market-holidays` for holiday schedule.

Skip or reschedule jobs when `currentMarketStatus` is `closed` or when the date is a holiday.

## Common Mistakes

- Do not build URLs like `...?date=today?apikey=...`; use `&apikey=...` when a query string already exists.
- Do not use `/v1/earnings` for all companies on a date; use `/v1/calendar/earnings`.
- Do not use `/v1/calendar/earnings` for one company's earnings history; use `/v1/earnings?symbol=...`.
- Do not assume relative dates are local browser time; they resolve in New York time.
- Do not treat missing numeric values as zero. When unavailable, many fields return `null`.

## Machine-Readable Files

- `/openapi.json`
- `/api-catalog.json`
- `/llms.txt`