Messages
Message reference for the SEC Filings WebSocket stream.
Messages
Filing IN
Every message of type fillings represents a single SEC filing discovered by our crawler.
{
"type": "fillings",
"is_historical": true,
"discovered_time": "2024-02-25T12:34:56.123456Z",
"form": "10-K",
"description": "ACME CORP 10-K annual report.",
"filling_date": "2024-02-24",
"accepted_time": "2024-02-25T12:00:00Z",
"accession_no": "0000123456-24-000001",
"cik": 123456
}Message variables
| Variable | Type | Description |
|---|---|---|
type | string | Message type, always fillings. |
is_historical | bool | true for backlog messages sent immediately after you connect, false for new real-time filings. |
discovered_time | datetime | Timestamp (UTC, RFC3339 with nanoseconds) when the filing was first seen by FinFeed. |
form | string | SEC form code (e.g. 10-K, 8-K). |
description | string | Human-readable title published by the SEC. |
filling_date | date | Filing date (YYYY-MM-DD) reported by the issuer. |
accepted_time | datetime | Date and time when the filing was accepted by the SEC. |
accession_no | string | SEC accession number. |
cik | integer | Central Index Key of the issuer. |
:::tip Backlog + Real-time
You always receive the backlog first so that your application starts from a coherent state. The backlog normally covers the last few hundred filings and is delivered as fast as possible. After that the is_historical flag switches to false and new filings arrive in real-time with ~100 ms latency.
:::
Reconnect IN
The server may instruct all connected clients to reconnect when maintenance is required. When you receive a reconnect message you must reconnect within the indicated time window.
{
"type": "reconnect",
"within_seconds": 10,
"before_time": "2024-08-06T19:19:09.7035429Z"
}| Variable | Description |
|---|---|
type | Message type, always reconnect. |
within_seconds | Number of seconds in which you should perform the reconnection. |
before_time | Absolute UTC time before which the reconnection must be completed. |
Heartbeat IN
Heartbeat messages are emitted every second only if you requested them in the Hello message ("heartbeat": true). They allow you to distinguish between no data and no connection.
{
"type": "heartbeat"
}Error IN
When the server encounters a problem with the message you sent (e.g. malformed JSON or invalid API key) it returns an error message and closes the connection.
{
"type": "error",
"message": "Invalid API key"
}Endpoints
WebSocket endpoint provides real-time SEC filings streaming. After establishing a WebSocket connection with us, you can optionally send a Hello message to enable Heartbeat messages.
Introduction
Use the FinFeedAPI SEC MCP server to search filings, extract item text, download filing files, and convert XBRL into JSON.