Real-Time Filing Stream API

The Stream API delivers a push-based feed of newly published SEC EDGAR filings over a WebSocket connection at wss://stream.sec-api.io. Rather than repeatedly requesting an endpoint to check for updates, you keep one connection open and the server transmits a message the moment a new filing becomes publicly available. Each message is a JSON array of filing metadata objects, where every object carries the form type (formType), the filer's CIK (cik), the acceptance timestamp (filedAt), and links to the filing documents.

Because delivery is immediate as filings are released, this is the appropriate mechanism for low-latency monitoring. The feed covers all 150+ EDGAR form types, so any new submission from any filer arrives without you needing to specify which company or form type you are waiting for.

The Stream API includes the company's stock ticker on every filing message (ticker), for example MSFT for Microsoft or JPM for JPMorgan Chase. As filings stream in, you compare the ticker field of each message against the symbol you are tracking and keep the ones that match; the most recent matches are the company's latest submissions, ordered by the acceptance timestamp (filedAt).

The Stream API is a forward-looking feed of newly published filings, so it surfaces submissions from the moment you connect onward rather than returning a historical archive. If you need filings a company submitted before you started listening, that is a query against a historical filings endpoint rather than the real-time stream.

Every filing message from the Stream API carries the filer's Central Index Key with the leading zeros removed (cik), for example 789019 for Microsoft. To track a company by its CIK, compare the cik field of each incoming message against the identifier you hold and keep the matches. The CIK also appears, with leading zeros preserved, on each referenced entity inside the filing (entities.cik), so a company named anywhere in a multi-entity filing can be matched there as well.

Using the CIK rather than the ticker is the reliable approach for filers that have no publicly traded symbol, such as mutual funds, asset-backed securities issuers, or private entities, because the ticker field is empty for those filers while the CIK is always present.

Material corporate events are disclosed on Form 8-K, the current report. On the Stream API, watch the form type field of each incoming message (formType) and keep the messages where it equals 8-K (or 8-K/A for an amended current report). Each such message identifies the filer by name and CIK (companyName, cik) and includes a description of the report (description).

The specific events being reported are listed on the 8-K itself: the item strings appear in the items array (items), for example Item 2.02: Results of Operations and Financial Condition or Item 5.02: Departure of Directors or Certain Officers, and the same item numbers are also summarized in the description field. Filtering for 8-K gives you every material event announcement as it is accepted by EDGAR.

Insider buying and selling is reported on Form 4, the statement of changes in beneficial ownership. On the Stream API, watch the form type field of each message (formType) and keep the messages where it equals 4 (or 4/A for an amended Form 4). Each Form 4 message names both the company whose shares were traded and the insider who traded them.

The Stream API delivers only the filing metadata, not the parsed transaction figures. To see how many shares were bought or sold and at what price, take the accession number from the message (accessionNo) and pass it to the Insider Trading API at /insider-trading, which returns the standardized Form 4 transaction data in JSON. Combining the two lets you monitor insider trades market-wide and pull the trade details shortly after each filing is published.

Each filing message from the Stream API includes a direct URL to the primary filing document on SEC.gov in the filing-details link field (linkToFilingDetails). This points at the actual content document, for example the 8-K body or the prospectus, with its file extension such as .htm or .pdf.

This URL can be opened directly to read the filing, and it is also the link to use with the Filing Download API at /filing-reader (the SEC Filings Render API) when you want to download or render the document programmatically. Two related links are also provided: the index page that lists every document in the submission (linkToHtml) and the complete plain-text submission file (linkToTxt).

The acceptance time is the filedAt field on each Stream API filing message. It corresponds to the Accepted attribute that EDGAR records for a filing, given in ISO 8601 format with both date and time, for example 2020-06-09T08:05:40-04:00. The time is in 24-hour format and the timezone is always Eastern Time: the offset is -04:00 during daylight saving time in summer and -05:00 during standard time in winter.

Note that EDGAR also records a separate Filing Date attribute that carries only a date and need not match the date portion of filedAt. The Stream API exposes the Accepted timestamp through filedAt, which is the precise moment the submission was accepted.

Every Stream API filing message carries a document-format files array (documentFormatFiles) that lists all primary files of the submission. The first item is always the filing itself and the last item is the complete text submission; the items in between can be exhibits, press releases, PDF documents, presentations, graphics, and XML files. Each entry gives the file's location (documentFormatFiles.documentUrl), its description (documentFormatFiles.description, for example EXHIBIT 99.1), its type (documentFormatFiles.type, for example EX-99.1 or GRAPHIC), and its sequence number (documentFormatFiles.sequence).

Iterating over this array gives you the full set of attachments for a newly published filing, with a downloadable URL for each. XBRL financial data files are listed separately in the data files array (dataFiles) rather than here.

XBRL financial data files are listed in the data files array on each Stream API filing message (dataFiles). Each entry provides a downloadable URL (dataFiles.documentUrl), a description (dataFiles.description, for example XBRL INSTANCE DOCUMENT or XBRL TAXONOMY EXTENSION SCHEMA DOCUMENT), the file type (dataFiles.type, for example EX-101.INS, EX-101.SCH, or EX-101.PRE), and its size in bytes (dataFiles.size).

As soon as a message arrives, iterate over dataFiles and download the URLs you need. The array is empty for filings that carry no XBRL data, such as many Form 4 and letter filings, so check whether it has entries before processing it.

On a Form 4 message from the Stream API, the entities array (entities) lists every party referenced in the filing. The first element is always the issuer company whose shares were traded, identified by name and CIK (entities[0].companyName, entities[0].cik) and usually marked with (Issuer) in the name. The reporting person, the insider who made the trade, follows as a later element, identified the same way and marked with (Reporting) in the name.

For example, a Form 4 for Wingstop lists Wingstop Inc. (Issuer) first and the reporting individual Kruguer Lawrence (Reporting) after it. To retrieve the parsed transaction details for that insider, take the accession number (accessionNo) and pass it to the Insider Trading API at /insider-trading.

A single SEC submission can reference more than one entity. When it does, the Stream API generates a separate filing metadata object for each referenced entity. Every one of those objects carries the same accession number (accessionNo) because they describe the same submission, but each has its own distinct system-internal identifier (id). Form 4 filings always do this, since they reference at least one issuer and one reporting person, and other multi-entity filings behave the same way.

To handle this correctly, treat the accession number as the identifier of the underlying filing and the id field as the identifier of the individual message. Deduplicate on accessionNo when you only need the filing once; keep the per-entity objects separate when you need the metadata of each referenced entity.

Industry classification is carried on each referenced entity inside a Stream API filing message, in the entity's SIC field (entities.sic). The Standard Industrial Classification code identifies the company's industry and is reported with its description, for example 5812 Retail-Eating Places for a restaurant company or 2834 Pharmaceutical Preparations for a drug maker.

The first element of the entities array is the filing issuer, so reading entities[0].sic gives the industry of the company that filed. This field is optional and may be absent on some entity entries, such as reporting persons on a Form 4, so check that it is present before using it.

The state of incorporation is carried on each referenced entity inside a Stream API filing message, in the entity's state-of-incorporation field (entities.stateOfIncorporation). It holds a two-letter code, for example DE for Delaware or NJ for New Jersey.

The first element of the entities array represents the filing issuer, so entities[0].stateOfIncorporation gives the incorporation state of the company that filed. This field is optional and may be absent on some entity entries, so check that it is present before relying on it.

On an 8-K message from the Stream API, the specific events are listed in the items array (items). Each entry is an item string such as Item 2.02: Results of Operations and Financial Condition for an earnings release or Item 5.02: Departure of Directors or Certain Officers for an executive change. The same item numbers are also folded into the form description (description), for example Form 8-K - Current report - Item 7.01.

Reading the items array tells you exactly which 8-K events a filing covers. The same field is populated for related form types that report item numbers, including 8-K/A, D, D/A, ABS-15G, 1-U, and their amendments.

Quarterly earnings are announced on Form 8-K under Item 2.02, Results of Operations and Financial Condition. On the Stream API, keep the messages where the form type (formType) is 8-K and the items array (items) contains an entry for Item 2.02: Results of Operations and Financial Condition. Each such message identifies the company by name and CIK (companyName, cik) and records the acceptance time (filedAt).

The earnings release itself is usually attached as an exhibit. Look in the document-format files array (documentFormatFiles) for an entry of type EX-99.1 and use its URL (documentFormatFiles.documentUrl) to retrieve the press release. Filtering this way surfaces each earnings announcement at the instant the 8-K is accepted by EDGAR.

Merger and acquisition activity is disclosed on a set of dedicated EDGAR form types. On the Stream API, watch the form type field (formType) for these forms, for example SC14D9C for a written communication relating to a third-party tender offer, the SC TO-T and SC 14D9 families for tender offer statements and solicitation/recommendation statements, and 8-K filings carrying item Item 1.01: Entry into a Material Definitive Agreement or item Item 2.01: Completion of Acquisition or Disposition of Assets in the items array (items).

Each matching message names the parties through the entities array (entities), where a target company is often marked (Subject) in its name (entities.companyName) and the filer is marked (Filed by). The attached communication documents are reachable through the document-format files array (documentFormatFiles.documentUrl).

The form type field on each Stream API message (formType) tells you whether a filing is an original or an amendment. An amended form has a form type ending in /A, for example 10-K/A for an amended annual report, 8-K/A for an amended current report, or 4/A for an amended Form 4. A form type without the /A suffix is an original filing.

To separate the two as messages arrive, check whether the value of formType ends with /A. The base form type before the suffix tells you what kind of filing was amended, so 10-K/A is an amendment to the same disclosure category as a plain 10-K.

Institutional investment manager holdings are disclosed on Form 13F. On the Stream API, keep the messages where the form type (formType) is in the 13F family, such as 13F-HR for a holdings report or 13F-HR/A for an amendment. Each message identifies the filing manager by name and CIK (companyName, cik) and records the quarter the report covers in the period field (periodOfReport).

The Stream API delivers only the filing metadata, not the position-level holdings. To get the detailed positions, take the accession number from the message (accessionNo) and pass it to the 13F Holdings API at /form-13f/holdings, which returns the manager's reported holdings in structured JSON. Chaining the two lets you identify a fund's most recently disclosed positions shortly after the 13F is published.

Each Stream API filing message carries the SEC accession number of the submission in the accession-number field (accessionNo), for example 0001140361-05-004060. For a Form 4 message, this is the identifier of the insider filing, but the stream itself provides only the metadata, not the parsed transaction figures.

To get the fully parsed insider trading details, pass that accession number to the Insider Trading API at /insider-trading. That endpoint returns the standardized Form 4 data in JSON, including the reporting person, the issuer, and the non-derivative and derivative transactions with share counts and prices. Using the stream to receive the accession number and the Insider Trading API to expand it is the intended real-time insider-tracking workflow.

The period-of-report field on a Stream API message (periodOfReport) is a date in YYYY-MM-DD format, but what that date represents depends on the form type (formType). For a Form 10-K annual report it is the fiscal year end date. For a Form 4 insider filing it is the transaction date. For a Form 13F fund holdings report it is the quarter end date.

Because the meaning is form-specific, always interpret periodOfReport together with formType rather than treating it as a single fixed concept. The field is only present when a period is reported for that form type, so it can be absent on some messages.

Securities offerings are disclosed through prospectus filings under Rule 424. On the Stream API, watch the form type field (formType) for the 424 family, for example 424B2 for a prospectus filed under Rule 424(b)(2), commonly used for pricing supplements on debt and note issuances, and 424B3 for a prospectus filed under Rule 424(b)(3). Each message names the issuer by company name and CIK (companyName, cik) and includes a form description (description, for example Form 424B2 - Prospectus [Rule 424(b)(2)]).

The prospectus document itself is reachable through the filing-details link (linkToFilingDetails), and any pricing supplement or related exhibits are listed in the document-format files array (documentFormatFiles). Filtering for the 424 forms surfaces each new offering as the prospectus is accepted by EDGAR.

When a registration statement becomes effective, EDGAR records an EFFECT form, and the Stream API delivers it as a message with the form type (formType) set to EFFECT. These messages carry dedicated fields describing the effectiveness: the date the registration became effective (effectivenessDate), the time of day (effectivenessTime, for example 16:00:00), the registration form type that became effective (registrationForm, for example S-1), and the accession number of the original registration statement being made effective (referenceAccessionNo).

To track effectiveness in real time, keep messages where formType is EFFECT and read those fields. The referenceAccessionNo lets you tie the effectiveness notice back to the registration statement it applies to.

The ticker field on a Stream API message (ticker) holds the stock symbol of the filing company, but it is only populated for publicly traded companies. When the field is empty, the filer is an entity that has no publicly traded stock, such as a mutual fund, an asset-backed securities issuer, a private company, or a special-purpose entity.

For those filers you should match and identify the entity by its Central Index Key instead, using the message-level CIK (cik) or the CIK on each referenced entity (entities.cik). The CIK is always present, so it is the reliable identifier when ticker is blank.

The entities array on each Stream API message (entities) lists every entity referenced in the filing. For a submission that covers many related entities, such as a shelf prospectus filed jointly by a parent company and dozens of its subsidiaries, every one of those entities appears as an element of entities, each with its company name (entities.companyName), CIK (entities.cik), state of incorporation (entities.stateOfIncorporation), SEC file number (entities.fileNo), and other identifiers.

The first element is always the filing issuer; the remaining elements are the other referenced entities. Iterating over the full entities array gives you every company named in that single submission.

Each entry in the document-format files array of a Stream API message carries a size field (documentFormatFiles.size) giving the file size in bytes, for example 100484. Reading this value for every entry lets you rank the attachments and decide which to download first, for instance fetching the small primary document before a large graphic or the full text submission.

XBRL data files report their size the same way in the data files array (dataFiles.size). Note that the size field is optional and can be blank for some entries, such as the rendered XML version of a Form 4, so handle a missing value before sorting.

Each Stream API filing message includes a link to the plain-text version of the complete submission in the text-link field (linkToTxt). This .txt file contains the entire filing together with all of its exhibits in a single document.

Be aware that this file can be very large, exceeding several hundred megabytes for filings with many or large exhibits, because it bundles everything in one place. The same complete submission text file is also listed as the last entry of the document-format files array (documentFormatFiles), described as Complete submission text file.

Each Stream API filing message includes a link to the filing's index page in the HTML-link field (linkToHtml). This index page, also called the filing detail page, lists every document that belongs to the submission and ends in -index.htm, for example a URL of the form .../0001185348-20-000015-index.htm.

Opening this URL shows the directory of all files in the filing. If you instead want machine-readable entries for each document, the document-format files array (documentFormatFiles) and the data files array (dataFiles) on the same message already provide a downloadable URL for every file.

The Stream API is reached over a WebSocket connection at the endpoint wss://stream.sec-api.io. Authentication is done by including your API key as the apiKey query parameter on that endpoint URL, substituting your actual key into wss://stream.sec-api.io?apiKey=YOUR_API_KEY. Accessing the streaming server requires an API key and an active subscription; the key is available in your sec-api.io account profile.

Any programming language or framework able to manage WebSocket connections can connect, including Python, Node.js, Java, C, C#, C++, Go, Rust, and React. Once connected, the server pushes a stringified JSON array of filing metadata objects each time a new filing is released.

The Stream API server keeps connections alive with the WebSocket ping/pong mechanism. It issues a ping message every 25 seconds, and if it does not receive a pong response from the client within 5 seconds it terminates the connection. This keeps the connection open even during quiet periods when no new filings are being published.

In most cases no extra client-side work is needed, because the majority of WebSocket libraries answer pings with pongs automatically. If your library does not handle ping/pong on its own, or you want customized keepalive behavior, you must respond to each ping with a pong within the 5-second window yourself to avoid being disconnected.

Mutual fund structure is carried on the series-and-classes information array of a Stream API message (seriesAndClassesContractsInformation). Each element represents a fund series, with its series identifier (seriesAndClassesContractsInformation.series, for example S000001297) and series name (seriesAndClassesContractsInformation.name).

Within each series, the classes/contracts array (seriesAndClassesContractsInformation.classesContracts) lists the individual share classes. Each class entry gives its class/contract identifier (seriesAndClassesContractsInformation.classesContracts.classContract, for example C000011787), its class name (seriesAndClassesContractsInformation.classesContracts.name, for example Class L), and its ticker symbol (seriesAndClassesContractsInformation.classesContracts.ticker, for example URTLX). This array is empty for filers that are not organized into fund series and classes.