Real-Time Filing Stream API
The Stream API provides a real-time feed of the latest filings submitted to the SEC EDGAR database via a WebSocket connection. This push-based technology ensures immediate delivery of metadata for each new filing as it becomes publicly available. The metadata includes over 20 filing properties, such as EDGAR form type, Central Index Key (CIK) of the filer, associated ticker symbols, publication date and time, URLs to the primary filing document as well as URLs to all exhibits and XBRL files, and information on all referenced entities, among other details.
Data is transmitted in a structured JSON format, and the API supports all programming languages and frameworks capable of managing WebSocket connections. These include Python, Node.js, Java, C, C#, C++, Go, Rust, and React, ensuring accessibility for developers and analysts across diverse technology stacks.
1
[
2
{
3
// Microsoft's 10-Q filing for Q1 2024
4
accessionNo: "0000950170-24-048288",
5
formType: "10-Q",
6
periodOfReport: "2024-03-31",
7
filedAt: "2024-04-25T16:06:24-04:00",
8
ticker: "MSFT",
9
cik: "789019",
10
companyName: "MICROSOFT CORP (Filer)",
11
linkToFilingDetails: "sec.gov/Archive ... 4048288/msft-20240331.htm",
12
entities: [ ... ], // entities associated with filing: CIK, EIN, state of incorp., fiscal year, and more
13
documentFormatFiles: [ ... ], // files and exhibits attached to filing: URL, type, size
14
dataFiles: [ ... ], // XBRL data files
15
// ... more fields
16
},
17
// ... more filings
18
]
The Stream API is desgined to be used in conjunction with our stack of SEC-data APIs, and is typically deployed in the first phase of a filing acquisition, transformation, and analysis workflow. For instance, if you're tracking the buy/sell activities of institutional investment managers as reported in 13F filings, the Stream API provides, among other details, the accession number of such filings. Upon receiving this information, you can utilize our 13F Holdings API to access the holdings data in a structured JSON format by entering the filing's accession number. This enables you to instantly identify the fund's most recently bought and sold positions shortly after the filing is published. Similarly, for monitoring insider trading activities as disclosed in Form 4 filings, you can use the filing's accession number to access standardized Form 4 data in JSON format via our Insider Trading API. This enables real-time tracking of the volume of shares insiders have bought or sold.
Use Cases
The Stream API opens up a wide array of use cases, especially in quantitative finance and trading, compliance monitoring, legal analysis, and data analytics. Use cases include:
Real-time Trading Strategies: Traders can leverage the API to develop algorithms that react instantly to new filings, extracting alpha signals to make informed trades before the broader market has time to respond. Examples include merger arbitrage, replicating institutional investment manager activities from 13F disclosures, real-time sentiment analysis, and event-driven trading strategies.
Risk Management: By monitoring filings in real-time, financial institutions can quickly assess changes in the risk profiles of their investments or potential investments, adjusting their strategies accordingly.
Exchange Compliance: Regulatory bodies and exchange operators can use the API to monitor listed companies for compliance with filing requirements, identifying discrepancies or delays in real-time.
News Reporting and Journalism: News agencies and journalists can use the Stream API to monitor filings for breaking news or investigative stories. For example, a news agency covering the financial sector can receive instant alerts on filings indicating significant corporate events such as mergers, new debt issuances, executive changes, or financial distress.API Endpoint
WebSocket endpoint: wss://stream.sec-api.io?apiKey=YOUR_API_KEY
Keeping Client-Server Connections Alive: To ensure uninterrupted client-server connections, our servers issue a ping message every 25 seconds. If a pong response from the client is not received within 5 seconds, the server will terminate the connection. This mechanism, inherent to the WebSocket protocol, typically necessitates no additional client-side implementation. However, while most libraries manage ping/pong exchanges automatically, others might necessitate manual handling for those seeking customized keepalive behaviors beyond the default settings.
Authentication
To access the streaming server, you must have an API key and an active subscription to one of our plans. You can find your API key in your account profile. To connect, simply substitute YOUR_API_KEY in the endpoint URL with your actual API key.
Message Format
The Stream API communicates with clients by dispatching messages in string format. It is common for some filings, such as Form 4 filings which invariably reference at least two entities, and other types that mention multiple entities, to be released simultaneously. In such cases, despite a single accession number being assigned to the filing, separate metadata objects are generated for each referenced entity. Consequently, the message's filings array may encompass several filings published concurrently. Messages are composed of a stringified JSON array encapsulating filing metadata objects.
Upon the release of a new filing, our servers instantly transmit a message to the connected WebSocket client. This message is formatted as a stringified JSON array, containing one or more filing metadata objects. Each metadata object within the array is structured as a JSON object and includes the following keys detailing the filing's metadata:
id(string) - System-internal unique ID of the filing object. A filing might reference multiple entities, for example, in case of Form 4 filings which reference at least one reporting person and one issuer company. In such cases, multiple filing objects are created, each with a unique ID, but all with the sameaccessionNo.accessionNo(string) - Accession number of filing, e.g. 0000028917-20-000033.formType(string) - EDGAR filing form type, e.g10-Kor10-K/A. All 150+ form types including SEC correspondences are covered. A complete list of all form types is available here.filedAt(string) - Represents theAcceptedattribute of a filing in ISO 8601 format, and shows the date and time the filing was accepted by the EDGAR system. A filing also contains aFiling Dateattribute that only shows the date. TheAcceptedandFiling Dateattribute do not have to represent the the same date. Format:YYYY-MM-DD HH:mm:SS TZ, e.g. 2019-12-06T14:41:26-05:00. The timezone is always in Eastern Time (ET) and the time is in 24-hour format. During daylight savings time (summer), the timezone offset is -04:00, and during standard time (winter), the offset is -05:00.cik(string) - CIK of the filing issuer with leading0removed, e.g.28917.ticker(string) - Ticker symbol of the filing company, e.g.AMOT. A ticker is not available when non-publicly traded companies report filings, for example, in case of mutual funds or asset-backed securities.companyName(string) - Name of primary filing company or person, e.g. Allied Motion Technologies Inc.companyNameLong(string) - Long version of company name including the filer type (Issuer, Filer, Reporting), e.g. ALLIED MOTION TECHNOLOGIES INC (0000046129) (Issuer)description(string) - Description of the form, e.g. Statement of changes in beneficial ownership of securities. Includes the item numbers reported in 8-K, 8-K/A, D, D/A, ABS-15G, ABS-15G/A, 1-U and 1-U/A filings, e.g. Form 8-K - Current report - Item 1.03 Item 3.03 Item 5.02 Item 9.01".linkToFilingDetails(string) - URL of the actual filing content on sec.gov. Use this link in combination with our Filing Download API to download the filing content.linkToTxt(string) - URL of the plain text .TXT version of the filing. The content of this file includes the entire filing and its exhibits and can exceed several 100MB in size.linkToHtml(string) - URL of the index page (also known as filing detail page) of the filing, e.g. "sec.gov/Archives/.../0001803599-24-000156-index.htm".periodOfReport(string, if reported) - Period of report in the formatYYYY-MM-DD, e.g. 2021-06-08. TheperiodOfReporthas different meanings depending on the form type. For example, in Form 10-K filings, it represents the fiscal year end date. In Form 4 filings, it represents the transaction date, and in Form 13F filings, it represents the quarter end date.effectivenessDate(string, if reported) - Effectiveness date in the formatYYYY-MM-DD, e.g. 2021-06-08. TheeffectivenessDateis only reported on certain form types, such as EFFECT, 18-K, TA-1, and more.registrationForm(string, if reported) - Registration form type as reported on EFFECT forms, e.g. S-1.referenceAccessionNo(string, if reported) - Reference accession number as reported on EFFECT forms, e.g. 0001213900-22-001446.items(array of strings, if reported) - Items represents an array of item strings as reported on form 8-K, 8-K/A, D, D/A, ABS-15G, ABS-15G/A, 1-U, 1-U/A. For example:["Item 3.02: Unregistered Sales of Equity Securities", "Item 9.01: Financial Statements and Exhibits"]groupMembers(array, if reported) - Group members represents an array of member strings as reported on SC 13G, SC 13G/A, SC 13D, SC 13D/A filings, e.g.[ "c N. LITOWITZMAGNETAR CAPITAL PARTNERS LPSUPERNOVA MANAGEMENT LLC" ]entities(array) - A list of all entities referred to in the filing. The first item in the array always represents the filing issuer. Each array element is an object with the following keys:companyName(string) - Company name of the entity, e.g. DILLARD'S, INC. (Issuer)cik(string) - CIK of the entity. Leading0are not removed here, e.g. 0000028917irsNo(string, optional) - IRS number of the entity, e.g. 710388071stateOfIncorporation(string, optional) - State of incorporation of entity, e.g. ARfiscalYearEnd(string, optional) - Fiscal year end of the entity, e.g. 0201sic(string, optional) - SIC of the entity, e.g. 5311 Retail-Department Storestype(string, optional) - Type of the filing being filed. Same asformType, e.g. 4act(string, optional) - The SEC act pursuant to which the filing was filed, e.g. 34fileNo(string, optional) - Filer number of the entity, e.g. 001-06140filmNo(string, optional) - Film number of the entity, e.g. 20575664
documentFormatFiles(array) - An array listing all primary files of the filing, including its exhibits. The first item of the array always represents the filing itself. The last item of the array always represents the text .TXT version of the filing. All other items can represent exhibits, press releases, PDF documents, presentations, graphics, XML files, and more. An array item is represented as follows:sequence(string, optional) - The sequence number of the file indicating the order of the files in the filing, e.g. 1.description(string, optional) - Description of the file, e.g. EXHIBIT 31.1.documentUrl(string) - URL to the file on SEC.gov. The URL includes the file extension, such as .HTML, .PDF, .TXT, .XML, etc.type(string, optional) - Type of the file, e.g. EX-32.1, GRAPHIC or 10-Q.size(string, optional) - Size of the file in bytes, e.g. 6627216.
dataFiles(array) - List of data files primarily used for XBRL filings. Each item has the following fields:sequence(string) - Sequence number of the file indicating its order in the filing, e.g. 1.description(string) - Description of the file, e.g. XBRL INSTANCE DOCUMENTdocumentUrl(string) - URL to the file on SEC.gov. The URL includes the file extension, such as .XSD or .XML.type(string, optional) - Type of the file, e.g. EX-101.INS, EX-101.DEF or EX-101.PREsize(string, optional) - Size of the file in bytes, e.g. 6627216
seriesAndClassesContractsInformation(array) - List of series and classes/contracts information.series(string) - Series ID, e.g. S000001297.name(string) - Name of entity, e.g. PRUDENTIAL ANNUITIES LIFE ASSUR CORP VAR ACCT B CL 1 SUB ACCTSclassesContracts(array) - List of classes/contracts. Each list item has the following keys:classContract(string) - Class/Contract ID, e.g. C000011787.name(string) - Name of class/contract, e.g. Class L.ticker(string) - Ticker of the class/contract, e.g. URTLX.
Message Example
The following example illustrates a message dispatched by the Stream API upon the release of a new filing. The message represents a JSON array containing the metadata object of a single EDGAR filing.
1
[{
2
"id": "3f1416b68de0b25cfaa0bf21842d3691",
3
"accessionNo": "0001185348-20-000015",
4
"cik": "1185348",
5
"ticker": "PRAA",
6
"companyName": "PRA GROUP INC",
7
"companyNameLong": "PRA GROUP INC (Filer)",
8
"formType": "8-K",
9
"description": "Form 8-K - Current report",
10
"filedAt": "2020-06-09T08:05:40-04:00",
11
"linkToTxt": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/0001185348-20-000015.txt",
12
"linkToHtml": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/0001185348-20-000015-index.htm",
13
"linkToXbrl": "",
14
"linkToFilingDetails": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/praa20208k1011.htm",
15
"entities": [
16
{
17
"companyName": "PRA GROUP INC (Filer)",
18
"cik": "0001185348",
19
"irsNo": "753078675",
20
"stateOfIncorporation": "DE",
21
"fiscalYearEnd": "1231",
22
"type": "8-K",
23
"act": "34",
24
"fileNo": "000-50058",
25
"filmNo": "20950914",
26
"sic": "7320 Services-Consumer Credit Reporting, Collection Agencies"
27
}
28
],
29
"documentFormatFiles": [
30
{
31
"sequence": "1",
32
"description": "8-K",
33
"documentUrl": "https://www.sec.gov/ix?doc=/Archives/edgar/data/1185348/000118534820000015/praa20208k1011.htm",
34
"type": "8-K",
35
"size": "45666"
36
},
37
{
38
"sequence": "2",
39
"description": "EXHIBIT 99.1",
40
"documentUrl": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/exhibit9911.htm",
41
"type": "EX-99.1",
42
"size": "18598"
43
},
44
{
45
"sequence": " ",
46
"description": "Complete submission text file",
47
"documentUrl": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/0001185348-20-000015.txt",
48
"type": " ",
49
"size": "210865"
50
}
51
],
52
"dataFiles": [
53
{
54
"sequence": "3",
55
"description": "XBRL TAXONOMY EXTENSION SCHEMA DOCUMENT",
56
"documentUrl": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/praa-20200609.xsd",
57
"type": "EX-101.SCH",
58
"size": "4471"
59
},
60
{
61
"sequence": "4",
62
"description": "XBRL TAXONOMY EXTENSION CALCULATION LINKBASE DOCUMENT",
63
"documentUrl": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/praa-20200609_cal.xml",
64
"type": "EX-101.CAL",
65
"size": "638"
66
},
67
{
68
"sequence": "5",
69
"description": "XBRL TAXONOMY EXTENSION DEFINITION LINKBASE DOCUMENT",
70
"documentUrl": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/praa-20200609_def.xml",
71
"type": "EX-101.DEF",
72
"size": "1488"
73
},
74
{
75
"sequence": "6",
76
"description": "XBRL TAXONOMY EXTENSION LABEL LINKBASE DOCUMENT",
77
"documentUrl": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/praa-20200609_lab.xml",
78
"type": "EX-101.LAB",
79
"size": "26147"
80
},
81
{
82
"sequence": "7",
83
"description": "XBRL TAXONOMY EXTENSION PRESENTATION LINKBASE DOCUMENT",
84
"documentUrl": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/praa-20200609_pre.xml",
85
"type": "EX-101.PRE",
86
"size": "13594"
87
},
88
{
89
"sequence": "14",
90
"description": "EXTRACTED XBRL INSTANCE DOCUMENT",
91
"documentUrl": "https://www.sec.gov/Archives/edgar/data/1185348/000118534820000015/praa20208k1011_htm.xml",
92
"type": "XML",
93
"size": "4191"
94
}
95
]
96
}]