> ## 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. # Items > Get specific sections and items from SEC filings, like Item 1A Risk Factors or Item 7 MD&A. ### Overview The Items endpoint allows you to retrieve the raw text from the sections (called items) from a given 10-K, 10-Q, or 8-K filing. This lets you easily extract data from a filing without having to parse the entire document on your own. For 8-K filings, items may include an `exhibits` array when exhibits are present. Use the `include_exhibits` parameter to retrieve the raw text content of linked exhibits. ### 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/) ### Valid Item Types You can fetch a list of valid item types for 10-K, 10-Q, and 8-K filings with a `GET` request to: [https://api.financialdatasets.ai/filings/items/types/](https://api.financialdatasets.ai/filings/items/types/) You can optionally filter by filing type using the `filing_type` query parameter: * `https://api.financialdatasets.ai/filings/items/types/?filing_type=10-K` - returns only 10-K item types * `https://api.financialdatasets.ai/filings/items/types/?filing_type=10-Q` - returns only 10-Q item types * `https://api.financialdatasets.ai/filings/items/types/?filing_type=8-K` - returns only 8-K item types The response includes the item name, title, and description for each valid item type. 8-K item names follow the SEC's numbering scheme in the format `Item-X.XX`, for example `Item-1.01`, `Item-2.02`, `Item-5.02`, `Item-8.01`, and `Item-9.01`. ### Filtering by item Use the `item` query parameter (repeatable) to return only the items you need. This works for all three filing types. Because a given 8-K contains only the items the company chose to report, requesting an item that is not in the filing returns a `404` that names the missing items and the items the filing does contain (see [Error handling](#error-handling)). ### Examples ```python 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' filing_type = '10-K' year = 2023 # create the URL url = ( f'https://api.financialdatasets.ai/filings/items' f'?ticker={ticker}' f'&filing_type={filing_type}' f'&year={year}' ) # make API request response = requests.get(url, headers=headers) # parse filings from the response items = response.json().get('items') ``` ```python 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' filing_type = '10-Q' year = 2023 quarter = 1 # create the URL url = ( f'https://api.financialdatasets.ai/filings/items' f'?ticker={ticker}' f'&filing_type={filing_type}' f'&year={year}' f'&quarter={quarter}' ) # make API request response = requests.get(url, headers=headers) # parse filings from the response items = response.json().get('items') ``` ```python 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 (all required) ticker = 'AAPL' filing_type = '8-K' accession_number = '0001277902-25-000182' include_exhibits = True # create the URL url = ( f'https://api.financialdatasets.ai/filings/items' f'?ticker={ticker}' f'&filing_type={filing_type}' f'&accession_number={accession_number}' f'&include_exhibits={include_exhibits}' ) # make API request response = requests.get(url, headers=headers) # parse filings from the response items = response.json().get('items') ``` ```python 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' filing_type = '10-K' year = 2023 # create the URL url = ( f'https://api.financialdatasets.ai/filings/items' f'?ticker={ticker}' f'&filing_type={filing_type}' f'&year={year}' f'&item=Item-1' # Item 1 f'&item=Item-7A' # Item 7A ) # 8-K filings can be filtered the same way, e.g.: # &item=Item-2.02&item=Item-9.01 # make API request response = requests.get(url, headers=headers) # parse items from the response items = response.json().get('items') ``` ### Asynchronous requests (202 Accepted) Most requests return data immediately. The first request for a filing we haven't processed yet can take longer. If your filing isn't ready within \~10 seconds, the API returns `202 Accepted` with a `result_url` to poll. Your request is never dropped. ```http theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} HTTP/1.1 202 Accepted Location: https://api.financialdatasets.ai/filings/items/requests/1c2f0a4e-... Retry-After: 30 Content-Type: application/json { "status": "processing", "request_id": "1c2f0a4e-...", "result_url": "https://api.financialdatasets.ai/filings/items/requests/1c2f0a4e-...", "estimated_ready_at": "2026-07-13T18:30:45Z", "accession_number": "0001277902-25-000182", "message": "We are processing this filing. Poll result_url for the result, or retry this request after the estimated ready time." } ``` Poll `result_url` with the same `X-API-KEY` header. Each poll returns one of three responses: | Response | Meaning | What to do | | ------------------------------- | -------------------------------- | ------------------------------------------------------------- | | `{"status": "processing", ...}` | Still preparing the filing | Wait `Retry-After` seconds, then poll again | | The filing items payload | Ready | Done. You are billed once, on this response | | `{"status": "failed", ...}` | The filing could not be prepared | Re-request `GET /filings/items` with your original parameters | ```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} sequenceDiagram participant You participant Financial Datasets You->>Financial Datasets: GET /filings/items?ticker=AAPL&... Financial Datasets-->>You: 202 Accepted (result_url) You->>Financial Datasets: GET result_url Financial Datasets-->>You: 200 {"status": "processing"} Note over You: wait Retry-After seconds You->>Financial Datasets: GET result_url Financial Datasets-->>You: 200 filing items (billed once) ``` **Example with polling (Python):** ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} import time import requests def get_filing_items(url, headers): response = requests.get(url, headers=headers) if response.status_code == 202: result_url = response.json()["result_url"] while True: time.sleep(int(response.headers.get("Retry-After", 30))) response = requests.get(result_url, headers=headers) body = response.json() if body.get("status") == "processing": continue if body.get("status") == "failed": raise RuntimeError(body["message"]) break # body is the filing items payload return response.json() ``` **Good to know:** * Most filings are ready within 30 seconds. If a filing can't be prepared within 5 minutes, polling returns `failed`. * You are only billed when data is delivered. A 202, a processing poll, or a failed request never costs anything. * Retrying your original request URL also works: once the filing is ready, the same request returns it immediately. The `result_url` is simply the version that can also tell you definitively that a filing failed. ### Error handling Requests with mismatched parameters fail immediately with a `400` instead of being accepted for processing. The error message always names the correct value so you can fix the request in one step. | Status | Error | Meaning | What to do | | ---------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `Filing type mismatch` | The accession number belongs to a different form type than `filing_type` | Retry with the `filing_type` named in the message | | `400` | `Filing company mismatch` | The accession number belongs to a different company than `ticker` | Retry with the `ticker` named in the message | | `404` | `Filing not found` | The accession number does not exist on SEC EDGAR for this ticker | Verify the accession number and ticker | | `404` | `Items not found in filing` | At least one requested `item` is not in this filing (common for 8-Ks, which contain only the items the company reported) | The message lists the items the filing does contain. Retry with those, or drop the `item` filter to get all items. You are not billed | | `404` | `No data found` | The filing exists but contains no extractable items | Nothing to retry. You are not billed | | `200` `{"status": "failed"}` | Returned by `result_url` | The filing could not be prepared | Re-request `GET /filings/items` with your original parameters | ```json 400 Filing type mismatch theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "error": "Filing type mismatch", "message": "Accession number 0001277902-25-000182 is a 10-K, not a 8-K. Retry with filing_type=10-K.", "accession_number": "0001277902-25-000182" } ``` ```json 404 Items not found in filing theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} { "error": "Items not found in filing", "message": "The following requested item(s) do not exist in this filing: Item 2.02. Items present in this filing: Item 5.02, Item 9.01.", "accession_number": "0001277902-25-000182" } ``` ## OpenAPI ````yaml GET /filings/items 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/items: get: tags: - SEC Filings summary: Get SEC filing items description: Get the raw text Items from an SEC filing. operationId: getFilingItems parameters: - name: ticker in: query description: The ticker symbol. required: true schema: type: string - name: filing_type in: query description: The type of filing. required: true schema: type: string enum: - 10-K - 10-Q - 8-K - name: year in: query description: The year of the filing. required: true schema: type: integer - name: quarter in: query description: The quarter of the filing if 10-Q. required: false schema: type: integer - name: item in: query description: The item to get. required: false schema: type: string enum: - Item-1 - Item-1A - Item-1B - Item-2 - Item-3 - Item-4 - Item-5 - Item-6 - Item-7 - Item-7A - Item-8 - Item-9 - Item-9A - Item-9B - Item-10 - Item-11 - Item-12 - Item-13 - Item-14 - Item-15 - Item-16 - Item-1.01 - Item-1.02 - Item-1.03 - Item-1.04 - Item-2.01 - Item-2.02 - Item-2.03 - Item-2.04 - Item-2.05 - Item-2.06 - Item-3.01 - Item-3.02 - Item-3.03 - Item-4.01 - Item-4.02 - Item-5.01 - Item-5.02 - Item-5.03 - Item-5.04 - Item-5.05 - Item-5.06 - Item-5.07 - Item-5.08 - Item-6.01 - Item-6.02 - Item-6.03 - Item-6.04 - Item-6.05 - Item-7.01 - Item-8.01 - Item-9.01 - name: accession_number in: query description: The accession number of the filing if 8-K. required: false schema: type: string - name: include_exhibits in: query description: >- Whether to include the raw text from linked exhibits. Only applicable for 8-K filings. When true, exhibit objects will include the 'text' field containing the full exhibit content. required: false schema: type: boolean default: false responses: '200': description: SEC filing items response content: application/json: schema: $ref: '#/components/schemas/FilingItemsResponse' '202': description: >- The filing is still being prepared. Poll the result_url from the response body to retrieve the result. You are not billed for this response. headers: Location: description: 'Same as result_url: the URL to poll for the result.' schema: type: string Retry-After: description: Suggested number of seconds to wait before polling. schema: type: integer example: 30 content: application/json: schema: $ref: '#/components/schemas/FilingItemsAccepted' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' components: schemas: FilingItemsResponse: type: object properties: resource: type: string description: The resource type identifier. ticker: type: string description: The ticker symbol of the company. cik: type: string description: The Central Index Key (CIK) of the company. filing_type: type: string description: The type of filing. accession_number: type: string description: The accession number of the filing. year: type: integer description: The year of the filing. quarter: type: integer description: The quarter of the filing. items: type: array items: $ref: '#/components/schemas/FilingItem' FilingItemsAccepted: type: object properties: status: type: string enum: - processing description: Always 'processing' on a 202 response. request_id: type: string format: uuid description: Identifier for this request; useful when contacting support. result_url: type: string description: The URL to poll for the result. estimated_ready_at: type: string format: date-time description: When the filing is expected to be ready. accession_number: type: string description: The accession number of the filing being prepared. message: type: string description: Human-readable description of what to do next. FilingItem: type: object properties: number: type: string description: The item number. name: type: string description: The item name. text: type: string description: The item text. exhibits: type: array description: >- An array of exhibits linked to this item. Only present for 8-K filings when exhibits exist. items: $ref: '#/components/schemas/Exhibit' ErrorResponse: type: object properties: error: type: string description: A short error message. message: type: string description: A more detailed error message. Exhibit: type: object properties: number: type: string description: The exhibit number (e.g., '99.1'). description: type: string description: The description of the exhibit. url: type: string format: uri description: The URL to the exhibit document on the SEC website. text: type: string description: >- The raw text content of the exhibit. Only included when 'include_exhibits' parameter is set to true. 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 ````