> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Filings
> Search SEC filings (10-K, 10-Q, 8-K) for any US public company by stock ticker.
### Overview
The Filings endpoint allows you to fetch a list of filings for a given company.
The endpoint returns all of the filings that the company has filed with the SEC.
This includes 10-Ks, 10-Qs, 8-Ks, and more.
We have SEC filings for 10,000+ public companies.
To get started, please create an account and grab your API key at [financialdatasets.ai](https://financialdatasets.ai).
You will use the API key to authenticate your API requests.
### Coverage
| Tickers | Years of Coverage | Updated |
| ------- | ----------------- | --------- |
| 22,000+ | 30+ years | Real-time |
### Available Tickers
You can fetch a list of available tickers with a `GET` request to:
[https://api.financialdatasets.ai/filings/tickers/](https://api.financialdatasets.ai/filings/tickers/)
### Available Filing Types
You can fetch a list of valid filing types with a `GET` request to:
[https://api.financialdatasets.ai/filings/types/](https://api.financialdatasets.ai/filings/types/)
### Getting Started
There are only 3 steps for making a successful API call:
1. Add your API key to the header of the request as `X-API-KEY`.
2. Add query params like `ticker` to filter the data.
3. Execute the API request.
**Note**: You must include either the `ticker` in your query params.
### Example
```python Filings theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests
# add your API key to the headers
headers = {
"X-API-KEY": "your_api_key_here"
}
# set your query params
ticker = 'AAPL'
limit = 10
# create the URL
url = (
f'https://api.financialdatasets.ai/filings'
f'?ticker={ticker}'
f'&limit={limit}'
)
# make API request
response = requests.get(url, headers=headers)
# parse filings from the response
filings = response.json().get('filings')
```
### Filtering by Filing Type
Use the `filing_type` query param to filter filings.
* Single type: `?ticker=AAPL&filing_type=10-K`
* Multiple types: repeat the param (same pattern as multi-`item` filtering), e.g. `?ticker=AAPL&filing_type=10-Q&filing_type=10-K`
```python FilingsWithMultipleTypes theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests
headers = {"X-API-KEY": "your_api_key_here"}
url = "https://api.financialdatasets.ai/filings"
params = [
("ticker", "AAPL"),
("filing_type", "10-Q"),
("filing_type", "10-K"),
]
response = requests.get(url, headers=headers, params=params)
filings = response.json().get("filings")
```
## OpenAPI
````yaml GET /filings
openapi: 3.0.1
info:
title: Financial Datasets API
description: >-
Stock market API with real-time and historical financial data for 27,000+
tickers over 30+ years. Financial statements, equity prices, insider trades,
SEC filings, and more.
version: 1.0.0
license:
name: MIT
url: https://opensource.org/licenses/MIT
contact:
name: API Support
url: mailto:support@financialdatasets.ai
email: support@financialdatasets.ai
termsOfService: https://financialdatasets.ai/terms-of-use
servers:
- url: https://api.financialdatasets.ai/
description: Production server
security:
- X-API-KEY: []
tags:
- name: Financial Statements
description: Access to income statements, balance sheets, and cash flow statements
- name: Market Data
description: Real-time and historical price data
- name: Company Information
description: Company facts like ticker, name, and description
- name: Earnings
description: Earnings data and related information
- name: News
description: Real-time and historical news articles
- name: SEC Filings
description: SEC filings and regulatory documents
- name: Insider Trades
description: Insider trading activity and transactions
- name: Activist Ownership
description: Activist stakes from SEC Schedule 13D filings, in real time
- name: Beneficial Ownership
description: >-
Holders of more than 5% of a company's shares, from SEC Schedules 13D and
13G
- name: Insider Ownership
description: Insider ownership statements from SEC Forms 3 and 5
- name: Institutional Holdings
description: SEC-direct 13F equity holdings of institutional investment managers
- name: Index Funds
description: >-
ETF and index-fund holdings, weights, and the funds that hold a given
security
- name: Financial Metrics
description: Financial ratios, metrics, and key performance indicators
- name: Macroeconomics
description: Real-time and historical macroeconomic data like interest rates
- name: KPIs
description: Sector-specific operational KPIs extracted from earnings releases.
paths:
/filings:
get:
tags:
- SEC Filings
summary: Get SEC filings
description: Get SEC filings for a company.
operationId: getFilings
parameters:
- name: cik
in: query
description: The Central Index Key (CIK) of the company.
required: false
schema:
type: string
- name: ticker
in: query
description: The ticker symbol.
required: false
schema:
type: string
- name: filing_type
in: query
description: >-
Filter by one or more filing types. Repeat the query parameter to
pass multiple values (e.g. filing_type=10-Q&filing_type=10-K).
required: false
schema:
type: array
items:
type: string
enum:
- 10-K
- 10-Q
- 8-K
- 20-F
- 6-K
style: form
explode: true
- name: limit
in: query
description: 'The maximum number of filings to return (default: 10).'
required: false
schema:
type: integer
minimum: 1
default: 10
responses:
'200':
description: SEC filings response
content:
application/json:
schema:
$ref: '#/components/schemas/FilingsResponse'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'402':
$ref: '#/components/responses/PaymentRequiredError'
'404':
$ref: '#/components/responses/NotFoundError'
components:
schemas:
FilingsResponse:
type: object
properties:
filings:
type: array
items:
$ref: '#/components/schemas/Filing'
Filing:
type: object
properties:
cik:
type: integer
description: The Central Index Key (CIK) of the company.
accession_number:
type: string
description: The accession number of the filing.
filing_type:
type: string
description: The type of the SEC filing (e.g., 10-Q, 8-K).
report_date:
type: string
format: date
description: The date of the report.
filing_date:
type: string
format: date
description: The date the filing was submitted to the SEC.
ticker:
type: string
description: The ticker symbol.
url:
type: string
format: uri
description: The URL of the SEC filing.
ErrorResponse:
type: object
properties:
error:
type: string
description: A short error message.
message:
type: string
description: A more detailed error message.
responses:
BadRequestError:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Bad Request
message: Invalid request parameters
UnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Unauthorized
message: Invalid API key provided
PaymentRequiredError:
description: The request requires a paid subscription
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Payment Required
message: >-
This endpoint requires a paid subscription. Please upgrade your
plan.
NotFoundError:
description: The specified resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
error: Not Found
message: Ticker XXXX not found
securitySchemes:
X-API-KEY:
type: apiKey
name: X-API-KEY
description: API key for authentication.
in: header
````