Filings
Earnings Release Filings
/v2/filings/earningsReal-time feed of SEC 8-K earnings-release filings (item 2.02). Each event first appears at stage=announced
(lowest latency, minimal fields — typically seconds after the filing
hits EDGAR) and is updated to stage=enriched once additional filing details are available.
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.
Included in: Startup, Pro, Growth.
Authentication
Send your API key in the x-api-key header on every request to https://api.bavest.co. The samples read it from the BAVEST_API_KEY environment variable. Get an API key · Authentication guide
Parameters
Optional, at most one of symbol, isin, cusip.
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| symbol | query | string | no (at most one of symbol, isin, cusip) | Optional ticker filter (e.g., |
| isin | query | string | no (at most one of symbol, isin, cusip) | ISIN code (e.g., |
| cusip | query | string | no (at most one of symbol, isin, cusip) | CUSIP code (e.g., |
| 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 |
| limit | query | integer (int32) | no | Maximum number of results to return (default 50, max 500) Default |
| cursor | query | string | no | Opaque cursor for cursor-based pagination. When provided, returns results after the cursor position. Takes precedence over offset. |
Try it
Optional ticker filter (e.g., `AAPL`). Omit for all securities. Provide at most one of symbol or isin.
ISIN code (e.g., `US0378331005`). Provide exactly one of symbol or isin. Clear the symbol example before using an ISIN.
GET /v2/filings/earnings
Sent only to api.bavest.co for this request; not stored.
Response 200
Successful response · application/json
dataarray of EarningsReleaseevent_typestringrequiredEvent type discriminator. Always
earnings_releaseon this endpoint; other/v2/filings/*endpoints use other values.Example
earnings_releasesourcestringrequiredFiling source registry. Currently
sec_edgar.One of
sec_edgarExample
sec_edgarform_typestringRegulator 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-Kis_amendmentbooleanTrue when this filing amends a prior filing.
Example
falseamends_accession_numberstring | nullAccession number of the filing this amends, or null when
is_amendmentis false.itemsarray of string | nullSEC 8-K item codes that triggered this event, e.g.
2.02(Results of Operations and Financial Condition) or9.01(Financial Statements and Exhibits). Null when item codes are unavailable.identifiersFilingIdentifiersAll known identifier forms for the filer, so consumers can key on whichever one they use internally.
company_namestring | nullFiler's registered company name
Example
Apple Inc.accession_numberstringrequiredSEC accession number (unique per filing)
Example
0000320193-26-000018filed_atstring (date-time)requiredFiling timestamp reported by SEC EDGAR (ISO-8601, UTC).
Example
2026-07-30T20:30:28+00:00updated_atstring (date-time)requiredWhen this event row was last written (ISO-8601, UTC). Sort key for
updated_sincedelta polling.Example
2026-07-30T20:30:36+00:00report_datestring (date) | nullReporting date as stated by the filer, when different from
filed_at's calendar date.Example
2026-07-30headlinestring | nullShort human-readable summary. Null until the filing is enriched.
Example
Apple reports third quarter resultsdocumentsFilingDocuments | nullLinks to the filing's documents.
exhibits(and thereforepress_release, which is derived from it) is null until enrichment completes.periodFilingPeriod | nullThe fiscal period the filing reports on. Null until the filing is enriched.
metaobjectCursor pagination metadata. No
totalCount— computing an exact total across a firehose feed is not worth the query cost.pageSizeintegerPage size requested (echoes
limit)hasMorebooleanWhether another page is available
nextCursorstring | nullOpaque cursor for the next page, or null when
hasMoreis falsetimeintegerServer-side processing time in milliseconds
Example
17parametersobjectEcho of the request parameters the endpoint resolved
Errors
- 400Invalid 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).
- 401Missing or invalid API key.
- 404Resource not found.
- 429Rate limit exceeded. Retry after the `Retry-After` header interval.
- 500An unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value.
- 502Upstream data provider returned an error or is temporarily unavailable. Retry after a short delay.
- 504The request timed out waiting for a response from the upstream data provider. This may occur for complex queries or during peak load.
- defaultAn unexpected error occurred on the server. If the issue persists, contact support with the X-Request-Id header value.

