# Earnings Release Filings

> Real-time feed of SEC 8-K earnings-release filings (item 2.02), source- agnostic and forward-compatible with future push delivery (websocket / webhook).

`GET https://api.bavest.co/v2/filings/earnings`

Group: Filings. Route id: `v2_filings_earnings`. Included in: Startup, Pro, Growth.

## Description

Real-time feed of SEC 8-K earnings-release filings (item 2.02), source-
agnostic and forward-compatible with future push delivery (websocket /
webhook). Each event is written twice: once at `stage=announced`
(lowest latency, minimal fields — typically seconds after the filing
hits EDGAR) and again at `stage=enriched` once the index page and
press-release exhibit have been hydrated.

Omit `symbol`/`isin`/`cusip` for the full firehose across all
companies. `from`/`to` filter on `filed_at`. For low-latency polling,
use `updated_since` instead of `from`/`to`: it switches the sort order
to `updated_at` ascending so a cursor never skips a row that was
updated between polls (e.g. an `announced` row that became
`enriched`). Ordered `filed_at DESC` by default, `updated_at ASC` when
`updated_since` is set.

## Authentication

Send your API key in the `x-api-key` header on every request. No key yet? Sign up at https://dashboard.bavest.co/sign-up (free trial). The examples read the key from the `BAVEST_API_KEY` environment variable.

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `symbol` | query | string | no (at most one of symbol, isin, cusip) | Optional ticker filter (e.g., `AAPL`). Omit for all securities. Provide at most one of symbol or isin. |
| `isin` | query | string | no (at most one of symbol, isin, cusip) | ISIN code (e.g., `US0378331005`). Provide exactly one of symbol or isin. Clear the symbol example before using an ISIN. |
| `cusip` | query | string | no (at most one of symbol, isin, cusip) | CUSIP code (e.g., `037833100`). Provide at most one of symbol, isin, or cusip. |
| `from` | query | string (date) | no | Start date (YYYY-MM-DD) |
| `to` | query | string (date) | no | End date (YYYY-MM-DD) |
| `updated_since` | query | string (date-time) | no | Delta-polling cursor start. Accepts an ISO-8601 date or date-time. When set, results are sorted `updated_at` ascending instead of `filed_at` descending — the recommended low-latency polling pattern, since it guarantees a cursor never skips a row that was updated between polls. |
| `limit` | query | integer (int32) | no | Maximum number of results to return (default 50, max 500) Default `50`. |
| `cursor` | query | string | no | Opaque cursor for cursor-based pagination. When provided, returns results after the cursor position. Takes precedence over offset. |

Optional, at most one of `symbol`, `isin`, `cusip`.

## Response

200 Successful response (`application/json`).

| Field | Type | Always present | Description |
|---|---|---|---|
| `data` | array of EarningsRelease | no |  |
| `data[].event_type` | string | yes | Event type discriminator. Always `earnings_release` on this endpoint; other `/v2/filings/*` endpoints use other values. Example: `earnings_release`. |
| `data[].source` | string | yes | Filing source registry. Only `sec_edgar` in v1; EU regulator feeds (RNS, EQS) are a Phase 2 commercial/licensing item. One of `sec_edgar`. Example: `sec_edgar`. |
| `data[].form_type` | string | no | Regulator form type of the underlying filing (e.g. `8-K`). Kept as a free string so non-SEC form types fit without a schema change. Example: `8-K`. |
| `data[].is_amendment` | boolean | no | True when this filing amends a prior filing. Example: `false`. |
| `data[].amends_accession_number` | string \| null | no | Accession number of the filing this amends, or null when `is_amendment` is false. |
| `data[].items` | array of string \| null | no | SEC 8-K item codes that triggered this event, e.g. `2.02` (Results of Operations and Financial Condition) or `9.01` (Financial Statements and Exhibits). Null for future EU-source events, which carry no item codes. |
| `data[].identifiers` | FilingIdentifiers | no | All known identifier forms for the filer, so consumers can key on whichever one they use internally. |
| `data[].identifiers.symbol` | string \| null | no | Ticker symbol. Example: `AAPL`. |
| `data[].identifiers.isin` | string \| null | no | ISIN code. Example: `US0378331005`. |
| `data[].identifiers.cusip` | string \| null | no | CUSIP code. Example: `37833100`. |
| `data[].identifiers.cik` | string \| null | no | SEC Central Index Key (10-digit, zero-padded) Example: `320193`. |
| `data[].identifiers.lei` | string \| null | no | Legal Entity Identifier (GLEIF). Not yet populated for SEC-sourced filings — reserved for the EU/LEI backfill phase. |
| `data[].company_name` | string \| null | no | Filer's registered company name. Example: `Apple Inc.`. |
| `data[].accession_number` | string | yes | SEC accession number (unique per filing) Example: `0000320193-26-000018`. |
| `data[].filed_at` | string (date-time) | yes | Filing timestamp reported by SEC EDGAR (ISO-8601, UTC). Example: `2026-07-30T20:30:28+00:00`. |
| `data[].updated_at` | string (date-time) | yes | When this event row was last written (ISO-8601, UTC). Sort key for `updated_since` delta polling. Example: `2026-07-30T20:30:36+00:00`. |
| `data[].report_date` | string (date) \| null | no | Reporting date as stated by the filer, when different from `filed_at`'s calendar date. Example: `2026-07-30`. |
| `data[].headline` | string \| null | no | Short human-readable summary. Null until the filing is enriched. Example: `Apple reports third quarter results`. |
| `data[].documents` | FilingDocuments \| null | no | Links to the filing's documents. `exhibits` (and therefore `press_release`, which is derived from it) is null until enrichment completes. |
| `data[].documents.filing_index` | string (uri) | no | SEC EDGAR filing index page. Known as soon as the filing is detected, independent of enrichment stage. Example: `https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany`. |
| `data[].documents.press_release` | string (uri) \| null | no | URL of the press-release exhibit (EX-99.1), when one was identified during enrichment. Null until the filing is enriched. |
| `data[].documents.exhibits` | array of FilingExhibit \| null | no | Full exhibit list. Null until the filing is enriched. |
| `data[].documents.exhibits[].type` | string | no | Exhibit type code. Example: `EX-99.1`. |
| `data[].documents.exhibits[].url` | string (uri) | no | Exhibit document URL. Example: `https://www.sec.gov/Archives/edgar/data/320193/000032019326000018/ex99_1.htm`. |
| `data[].documents.exhibits[].description` | string \| null | no | Human-readable exhibit description. Example: `Press release`. |
| `data[].period` | FilingPeriod \| null | no | The fiscal period the filing reports on. Null until the filing is enriched. |
| `data[].period.fiscal_year` | integer \| null | no | Fiscal year. Currently always null in v1 — fiscal_year/ fiscal_quarter derivation from the earnings calendar is not yet implemented (later phase). Example: `2026`. |
| `data[].period.fiscal_quarter` | integer \| null | no | Fiscal quarter (1-4). Currently always null in v1 — fiscal_year/fiscal_quarter derivation from the earnings calendar is not yet implemented (later phase). Example: `3`. |
| `data[].period.period_end` | string (date) \| null | no | Period end date. Null when no matching earnings-calendar entry was found during enrichment. Example: `2026-06-27`. |
| `meta` | object | no | Cursor pagination metadata. No `totalCount` — computing an exact total across a firehose feed is not worth the query cost. |
| `meta.pageSize` | integer | no | Page size requested (echoes `limit`) |
| `meta.hasMore` | boolean | no | Whether another page is available. |
| `meta.nextCursor` | string \| null | no | Opaque cursor for the next page, or null when `hasMore` is false. |
| `meta.time` | integer | no | Server-side processing time in milliseconds. Example: `17`. |
| `meta.parameters` | object | no | Echo of the request parameters the endpoint resolved. |

## Example request

```bash
curl 'https://api.bavest.co/v2/filings/earnings' \
  -H "x-api-key: $BAVEST_API_KEY"
```

## Example response

```json
{
  "data": [
    {
      "event_type": "earnings_release",
      "source": "sec_edgar",
      "form_type": "8-K",
      "is_amendment": false,
      "amends_accession_number": null,
      "items": [
        "2.02",
        "9.01"
      ],
      "identifiers": {
        "symbol": "TSLA",
        "isin": "US88160R1014",
        "cusip": null,
        "cik": 1318605,
        "lei": null
      },
      "company_name": "Tesla, Inc.",
      "accession_number": "0001628280-26-064366",
      "filed_at": "2026-10-02T13:04:26+00:00",
      "updated_at": "2026-10-02T14:00:58.860270+00:00",
      "report_date": "2026-10-02",
      "headline": "Document",
      "documents": {
        "filing_index": "https://www.sec.gov/Archives/edgar/data/1318605/000162828026064366/0001628280-26-064366-index.htm",
        "press_release": "https://www.sec.gov/Archives/edgar/data/1318605/000162828026064366/exhibit991111111.htm",
        "exhibits": [
          {
            "url": "https://www.sec.gov/ix?doc=/Archives/edgar/data/1318605/000162828026064366/tsla-20261002.htm",
            "type": "8-K",
            "description": "8-K"
          },
          {
            "url": "https://www.sec.gov/Archives/edgar/data/1318605/000162828026064366/exhibit991111111.htm",
            "type": "EX-99.1",
            "description": "EX-99.1"
          }
        ]
      },
      "period": {
        "fiscal_year": null,
        "fiscal_quarter": null,
        "period_end": null
      }
    },
    {
      "event_type": "earnings_release",
      "source": "sec_edgar",
      "form_type": "8-K",
      "is_amendment": false,
      "amends_accession_number": null,
      "items": [
        "2.02",
        "9.01"
      ],
      "identifiers": {
        "symbol": "TMQ",
        "isin": "CA89621C1059",
        "cusip": null,
        "cik": 1543418,
        "lei": null
      },
      "company_name": "Trilogy Metals Inc.",
      "accession_number": "0001279569-26-000946",
      "filed_at": "2026-10-02T12:39:09+00:00",
      "updated_at": "2026-10-02T13:00:50.371646+00:00",
      "report_date": "2026-10-02",
      "headline": "Exhibit 99.1",
      "documents": {
        "filing_index": "https://www.sec.gov/Archives/edgar/data/1543418/000127956926000946/0001279569-26-000946-index.htm",
        "press_release": "https://www.sec.gov/Archives/edgar/data/1543418/000127956926000946/ex991.htm",
        "exhibits": [
          {
            "url": "https://www.sec.gov/ix?doc=/Archives/edgar/data/1543418/000127956926000946/form8k.htm",
            "type": "8-K",
            "description": ""
          },
          {
            "url": "https://www.sec.gov/Archives/edgar/data/1543418/000127956926000946/ex991.htm",
            "type": "EX-99.1",
            "description": "NEWS RELEASE DATED OCTOBER 2, 2026"
          }
        ]
      },
      "period": {
        "fiscal_year": null,
        "fiscal_quarter": null,
        "period_end": "2026-08-31"
      }
    }
  ],
  "meta": {
    "pageSize": 50,
    "hasMore": true,
    "nextCursor": "eyJmaWxlZF9hdCI6ICIyMDI2LTA5LTI0VDIwOjA1OjI0KzAwOjAwIiwgImFjY2Vzc2lvbl9udW1iZXIiOiAiMDAwMTQ5MzE1Mi0yNi0wNDQxNDUifQ==",
    "parameters": {
      "limit": "50"
    },
    "time": 3627
  }
}
```

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid request parameters. Returned when required query parameters are missing, have invalid types, or violate constraints (e.g., providing both symbol and isin when they are mutually exclusive). |
| 401 | Missing or invalid API key. |
| 404 | Resource not found. |
| 429 | Rate limit exceeded. Retry after the `Retry-After` header interval. |
| 500 | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |
| 502 | Upstream data provider returned an error or is temporarily unavailable. Retry after a short delay. |
| 504 | The request timed out waiting for a response from the upstream data provider. This may occur for complex queries or during peak load. |
| default | An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value. |

- `403` from the gateway: the API key is invalid or switched off.
- `429` with message `Limit Exceeded`: the monthly quota of the key is used up. With `Too Many Requests`: the key is throttled, or this route is not in the key's plan. Wait for `Retry-After` when it is sent.

## Links

- HTML page: https://dashboard.bavest.co/docs/v2_filings_earnings
- OpenAPI: https://dashboard.bavest.co/openapi.json (YAML: https://dashboard.bavest.co/openapi.yaml)
- Authentication: https://dashboard.bavest.co/docs/authentication.md
- MCP server for AI agents: https://dashboard.bavest.co/docs/mcp.md
- All routes: https://dashboard.bavest.co/llms.txt