Securities and Exchange Commission (SEC)

As the name suggests, the endpoints in this section pertain to data from the Securities and Exchange Commission (SEC). Parsed data is available for the most popular and significant form types in the SEC.

Introduction

The APIs in this section provide historical data access through queries and real-time data streaming through subscription connections. For details about the request and response structures, reference the respective GraphQL documentation for that form type in the GraphQL Documentation section.

GraphQL queries require the API key to be set in the headers of each request and subscriptions require them to be set with an initial payload in the connection_init websocket message. For examples of queries and subscriptions, checkout the Quickstart section.

Additionally, user's can learn the various endpoints and test the APIs in the GraphQL playground. To get to the playground pertaining to the data you want, please reference the Playground section.

Pagination

All query endpoints have an identical <endpoint>_count endpoint which can be used to obtain the number of available records for a set of filtering options. The results from the <endpoint>_count endpoint can then be used for pagination purposes in subsequent queries by incrementing the offset value in other non-count query endpoints until all possible values for a query have been retrieved by the client.

Query results are limited to 10 records per page and subscription results are broadcast to clients as they become available and so pagination does not apply to subscription endpoints.

This number may change in the future without prior notice so it is best to use the length of the values returned instead of relying on the static number, especially given that it is possible to create queries that may return less than 10 results in total.

Filtering

Most attributes support filtering. Numeric, date, and datetime values support all equality operators such as >, >=, ==, <=, and < with datetime values specified according to the RFC3339 specification and date values specified in the YYYY-mm-dd format. Datetime values are all in the UTC timezone.

String values can be filtered using regular expressions. Queries support PostgreSQL regex syntax and support the full-suite of regex functionality available in PostgreSQL. Subscriptions use perl-style regex syntax and do not support look-ahead or look-behind patterns for performance reasons. Additionally, regex timeouts are implemented to guarantee service availability. Please see Important Considerations for details about timeouts and other important information when querying.

Important Considerations

All subscriptions must send a keep-alive message to our servers or the connection is at risk of being closed if it is idle for more than an hour. We recommend an interval of once every minute (60s).

Queries must execute in less than 5 seconds or else they will be timed out and an error will be returned to the client. Queries related to retrieving the count of values such as in <endpoint>_count type endpoints must execute in less than 30 seconds or else they will be timed out and an error will be returned to the client. Subscriptions have 1 second per filtered attribute to match the inputted regex pattern or else a regex timeout error will be returned to the client's stream. These safeguards are implemented to prevent abuse of our systems.

Given the availability of regex pattern matching, this means that queries and subscriptions can filter for multiple values in a single request using the | (OR) operator in your pattern. We recommend limiting the number of | clauses to ensure timely delivery of data and to avoid service disruptions.

For a full list of possible errors that can be returned and what they mean, check out the Errors section.

Additionally, it is also important to note that some filing form types like insider transactions may show duplicated data due to a filing being generated for both the issuer entity and the transacting entity. In general, it is best to filter for data in a specific filing in all form types by filtering for both the entity_cik and filing_accession_number which should be available in nearly all the endpoints. When filtering for all data pertaining for a specific entity, the entity_cik attribute alone can be used. Generally, filtering only by the filing_accession_number attribute should be avoided to prevent duplicate values from showing up in your results.

To understand what the attributes of certain endpoints mean, you must reference the SEC XML Specifications for the specific form type and the actual published document to determine the attributes of interest in the endpoints. The attributes in endpoints for forms that undergo multiple revisions are consolidated across all revisions under a single endpoint to improve the developer experience. Therefore, some attributes may not be available in the most recent XML specifications and older versions of the specification will need to be referenced and cross-referenced with the actual publication of the filing in normal format to understand what data they represent. This should only be necessary for lesser known attributes and data pertaining to more popular attributes and endpoints should be self-explanatory.

Playground

This section contains the links to GraphQL playgrounds that can be used for testing, understanding the documentation, and structuring queries and subscriptions for your services. To authenticate your requests, please insert {"api-key": "<YOUR API KEY>"} in the HTTP Headers section on the bottom.

Metadata - Filings, Entities, and Publicly-Listed Securities

This API contains metadata information regarding entities, their associated filings, and their publicly-listed securities. Information in this API is useful for filtering the interested filings the clients wants, retrieving their associated accession numbers and using them to create new requests in the other available APIs.

Form 3, 3/A, 4, 4/A, 5, 5/A - Insider Transactions

These APIs contain data about the insider transactions of entities.

Form 10-Q, 10-Q/A, 10-K, 10-K/A, 20-F, 20-F/A, 40-F, 40-F/A - Annual and Quarterly Company Financial Reports

These APIs contain data about the quarterly and annual financial report of both domestic and international companies whose securities trade within the US.

10-Q and 10-K reports correspond to domestic companies. 20-F and 40-F reports correspond to international companies.

Form 13F-HR, 13F-HR/A, 13F-NT, 13F-NT/A - Institutional Holdings Reports

These APIs contain data about the institutional holdings of securities by entities. Information such as the holdings of Berkshire Hathaway and many of investment managers are available in these APIs.

Form N-MFP, N-MFP/A, N-MFP1, N-MFP1/A, N-MFP2, N-MFP2/A - Monthly Reports of Money Market Funds

These APIs contain data about the monthly reports of money market funds and their holdings.

Form NPORT-P, NPORT-P/A, NPORT-NP, NPORT-NP/A - Monthly Reports of Funds Other than Money Market Funds

These APIs contain data about the monthly reports of funds other than money market funds and their holdings.

Form D, D/A - Notice of Sale of Securities

This API contains data about the issuer's offering of securities such as in the case of diluting shares to raise capital for purchases.

Form 144, 144/A - Notice of Proposed Sale of Securities

This API contains data about the issuer's proposed sale of securities such as in the case of diluting shares to raise capital.

Form N-PX, N-PX/A - Annual Report of Proxy Voting Record of Registered Management Company

This API contains data about the issuer's proxy voting record and the matters for which the issuer's shareholders voted on, the registrants' cast votes and the outcome of each vote.

GraphQL Documentation

Errors

Whenever a request is unsuccessful, BeamAPI will return an error response with an error code and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

GraphQL Query Error Codes

{
    "data": null,
    "extensions": {
        "request-id": "e5a32713-5022-4aec-9312-9a70b7099d42"
    },
    "errors": [
        {
            "message": "Invalid credentials. Make sure you are using a valid api key.",
            "locations": [
                {
                    "line": 2,
                    "column": 3
                }
            ],
            "path": [
                "filing"
            ],
            "extensions": {
                "code": "api/invalid-credentials-error"
            }
        }
    ]
}

GraphQL Subscription Error Codes

{
    "data": null,
    "errors": [
        {
            "message": "Invalid credentials. Make sure you are using a valid api key.",
            "locations": [
                {
                    "line": 2,
                    "column": 3
                }
            ],
            "path": [
                "filing"
            ],
            "extensions": {
                "code": "api/invalid-credentials-error"
            }
        }
    ]
}