# 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"
```

**Response:**
```json
{
    "data": {
        "market": "US",
        "source": "Nasdaq",
        "symbol": "AAPL",
        "quarters": 4,
        "surprises": [
            {
                "result": "beat",
                "actual_eps": 2.01,
                "surprise_pct": 4.69,
                "consensus_eps": 1.92,
                "date_reported": "4/30/2026",
                "fiscal_quarter": "Mar 2026",
                "surprise_amount": 0.09
            },
            {
                "result": "beat",
                "actual_eps": 2.84,
                "surprise_pct": 7.17,
                "consensus_eps": 2.65,
                "date_reported": "1/29/2026",
                "fiscal_quarter": "Dec 2025",
                "surprise_amount": 0.19
            },
            {
                "result": "beat",
                "actual_eps": 1.85,
                "surprise_pct": 6.94,
                "consensus_eps": 1.73,
                "date_reported": "10/30/2025",
                "fiscal_quarter": "Sep 2025",
                "surprise_amount": 0.12
            },
            {
                "result": "beat",
                "actual_eps": 1.57,
                "surprise_pct": 10.56,
                "consensus_eps": 1.42,
                "date_reported": "7/31/2025",
                "fiscal_quarter": "Jun 2025",
                "surprise_amount": 0.15
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-12T01:42:10.828Z",
        "request_id": "bc642440-8db4-4a44-b978-
…(truncated, see openapi.json for full schema)
```

### 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"
```

**Response:**
```json
{
    "data": {
        "beats": 4,
        "market": "US",
        "misses": 0,
        "source": "Nasdaq",
        "symbol": "AAPL",
        "streak_type": "beat",
        "beat_rate_pct": 100,
        "latest_result": "beat",
        "current_streak": 4,
        "avg_surprise_pct": 7.34,
        "quarters_analyzed": 4,
        "latest_surprise_pct": 4.69
    },
    "meta": {
        "timestamp": "2026-06-12T01:42:10.915Z",
        "request_id": "ff53cb9e-5162-477d-b953-f6ea38871548"
    },
    "status": "ok",
    "message": "Scorecard retrieved successfully",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "note": "Look up a stock by its ticker (symbol=AAPL). The surprise is the actual reported EPS versus the analyst consensus for the quarter; positive percent surprise is a beat. Nasdaq provides the most recent quarters.",
        "source": "Nasdaq public earnings-surprise feed (api.nasdaq.com/api/company/{symbol}/earnings-surprise, live)",
        "service": "earningssurprise-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/scorecard": "Computed track record — beat rate, average surprise, streak (symbol=AAPL).",
            "GET /v1/surprises": "Recent quarters — actual EPS vs consensus, surprise % and beat/miss (symbol=AAPL)."
        },
        "description": "Live earnings beat/miss track record for US stocks from Nasdaq — the 'does it beat the street' view. surprises = the recent quarters with actual EPS, analyst consensus, the dollar and percent surprise and whether it was a beat, miss or in line; scorecard = the computed track record (how many quarters beat, the beat rate, average surprise, latest result and the current streak). Live, no key, nothing stored. Distinct from the earnings-calendar, analyst-estimate and financials APIs.",
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-12T01:42:11.004Z",
        "request_id": "e0b5f5b8-5455-4b27-b7f3-93061afc51a1"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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