# Earnings Surprise (Beat/Miss) API
> Live earnings beat/miss track record for US stocks from Nasdaq — no key, nothing stored. The "does it beat the street" view of a stock: how its actual reported EPS has compared to the analyst consensus over the recent quarters, distinct from the earnings-calendar (upcoming dates), analyst (forward estimates) and financials APIs in the catalogue. The surprises endpoint returns the recent quarters with the actual EPS, the consensus forecast, the dollar and percent surprise, and whether the quarter was a beat, a miss or in line. The scorecard endpoint computes the track record — how many of the recent quarters beat, the beat rate, the average surprise, the latest result and the current beat/miss streak — so you can gauge how reliably a company tops expectations. Build earnings-quality screeners, beat-streak scanners, post-earnings-drift signals and event-driven trading tools on top of real Nasdaq earnings-surprise data. The surprise is the actual reported EPS versus the analyst consensus for the quarter; a positive percent surprise is a beat. Look up any US stock by its ticker.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/earningssurprise-api/..."
```

## Pricing
- **Free** (Free) — 11,600 calls/Mo, 3 req/s
- **Starter** ($8/Mo) — 182,000 calls/Mo, 10 req/s
- **Pro** ($24/Mo) — 772,000 calls/Mo, 28 req/s
- **Scale** ($55/Mo) — 2,760,000 calls/Mo, 60 req/s

## Endpoints

### Surprises

#### `GET /v1/surprises` — Recent quarters — actual vs consensus, beat/miss

**Parameters:**
- `symbol` (query, required, string) — Stock ticker Example: `AAPL`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/earningssurprise-api/v1/surprises?symbol=AAPL"
```

### Scorecard

#### `GET /v1/scorecard` — Computed track record — beat rate, streak

**Parameters:**
- `symbol` (query, required, string) — Stock ticker Example: `AAPL`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/earningssurprise-api/v1/scorecard?symbol=AAPL"
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/earningssurprise-api/v1/meta"
```


---
Marketplace page: https://www.oanor.com/api/earningssurprise-api
OpenAPI spec: https://www.oanor.com/api/earningssurprise-api/openapi.json