DEV Community: Maciej Józefowicz

A Developer's Guide to Visualizing Tesla's Financial Data with XBRL

Maciej Józefowicz — Wed, 17 Sep 2025 10:42:17 +0000

Tesla, Inc., led by Elon Musk, is more than just a car company; it's a major force in the technology and energy sectors. Its performance and strategic decisions have a significant impact on the market, influencing everything from supply chains to investor sentiment in renewable energy and artificial intelligence. The company's frequent announcements and Musk's public statements make it one of the most-watched stocks in the world. For investors, analysts, and anyone interested in the future of technology and transportation, having access to detailed, accurate financial data on Tesla is not just useful—it's essential. Structured financial data allows for a clear view of the company's health and trajectory, cutting through the noise of daily news cycles.

Analyzing a company's financial statements is essential for understanding its performance, but manually extracting data from SEC filings can be a slow process. XBRL (eXtensible Business Reporting Language) data provides a structured, machine-readable format that is ideal for automated analysis.

This guide demonstrates how to use FinFeedAPI to access aggregated XBRL data from Tesla's 10-K filings. You will see how to write a Python script to fetch key financial metrics, process the data, and create several visualizations to analyze trends in revenue, expenses, and profitability.

This guide covers:

Fetching aggregated XBRL financial data for a specific company.
Processing and structuring time-series financial data with pandas.
Visualizing revenue, cost of revenue, and net income trends.
Creating a pie chart to show the distribution of operating expenses.
Calculating and plotting gross and net margin percentages over time.

What you need:

Python 3.x with pandas and matplotlib.
The api-bricks-sec-api-rest library.
Your personal FinFeedAPI key.

1. Environment Setup
First, you need to install the FinFeedAPI client library.

pip install api-bricks-sec-api-rest

Next, prepare your Python script by importing the necessary libraries and configuring the API client with your key.

# Import necessary libraries
import pandas as pd
import matplotlib.pyplot as plt
import re
import api_bricks_sec_api_rest

# --- API Configuration ---
# IMPORTANT: Replace "YOUR_API_KEY_HERE" with your actual key.
API_KEY = "YOUR_API_KEY_HERE"
api_client_config = api_bricks_sec_api_rest.Configuration()
api_client_config.api_key['Authorization'] = API_KEY
api_client = api_bricks_sec_api_rest.ApiClient(configuration=api_client_config)

# --- Plotting Configuration ---
plt.style.use('seaborn-v0_8-darkgrid')
plt.rcParams['figure.figsize'] = (14, 7)

2. Fetching Aggregated XBRL Data
The /v1/xbrl/facts/aggregated endpoint is a powerful tool for this type of analysis. It returns a clean, time-series set of financial facts for a given company and form type, which saves you from having to parse the raw XBRL from each filing individually.

Let's use this endpoint to get the financial data from Tesla's (CIK: 1318605) 10-K filings.

# Initialize the XBRL API client
xbrl_api = api_bricks_sec_api_rest.XBRLApi(api_client)

# Define the target CIK and form type
target_cik = 1318605
target_form_type = "10-K"

# Fetch the aggregated financial facts
try:
    aggregated_facts = xbrl_api.v1_xbrl_facts_aggregated_get(
        cik=target_cik,
        form_type=target_form_type
    )
    # Convert the results to a pandas DataFrame
    df_aggregated = pd.DataFrame.from_records([vars(x) for x in aggregated_facts])
    print(f"Successfully fetched {len(df_aggregated)} aggregated financial facts for CIK {target_cik}.")
except api_bricks_sec_api_rest.ApiException as e:
    print(f"Exception when calling XBRLApi: {e}")
    df_aggregated = pd.DataFrame()

3. Processing and Structuring the Data
The API returns the data in a "long" format. To make it easier to work with, we'll pivot the DataFrame so that each financial metric is a row and each time period is a column. We will also clean the data to ensure it's in a numeric format suitable for plotting.

if not df_aggregated.empty:
    # Pivot the table
    df_aggregated = df_aggregated.pivot(index='fact', columns='period', values='value')

    # Function to extract dates and sort columns chronologically
    def sort_columns_by_date(df):
        def get_end_date(col_name):
            try:
                # Extracts date from a string like '2022-01-01T00:00:00Z/2022-12-31T00:00:00Z'
                match = re.search(r'/(\d{4}-\d{2}-\d{2})', col_name)
                if match:
                    return pd.to_datetime(match.group(1))
            except (ValueError, TypeError):
                return pd.NaT
            return pd.NaT

        sorted_columns = sorted(df.columns, key=get_end_date)
        return df[sorted_columns]

    df_aggregated = sort_columns_by_date(df_aggregated)

    # Clean numeric data
    for col in df_aggregated.columns:
        df_aggregated[col] = pd.to_numeric(df_aggregated[col].astype(str).str.replace(r'[$,]', '', regex=True), errors='coerce')

    print("Transformed and Cleaned Data Head:")
    print(df_aggregated.head())

4. Visualizing Financial Performance
With the data cleaned and structured, we can now create several visualizations to analyze Tesla's performance.

Revenue, Cost of Revenue, and Net Income
This bar chart shows the relationship between revenues, the cost to generate them, and the resulting net income or loss for each period.

if 'Revenues' in df_aggregated.index and 'CostOfRevenue' in df_aggregated.index:
    # Select the relevant data
    plot_data = df_aggregated.loc[['Revenues', 'CostOfRevenue', 'NetIncomeLoss']].T / 1e9

    # Create the bar chart
    plot_data.plot(kind='bar', figsize=(14, 7))
    plt.title(f'Tesla (CIK: {target_cik}) - Revenue, Cost, and Net Income (Form {target_form_type})')
    plt.ylabel('Amount (in billions USD)')
    plt.xlabel('Fiscal Period')
    plt.xticks(rotation=45, ha='right')
    plt.grid(True, axis='y', linestyle='--')
    plt.legend(title='Financial Metric')
    plt.show()

Distribution of Operating Expenses
A pie chart is a good way to see how a company's operating expenses are distributed. Here, we look at the most recent period available.

op_expense_metrics = ['ResearchAndDevelopmentExpense', 'SellingGeneralAndAdministrativeExpense']
if all(metric in df_aggregated.index for metric in op_expense_metrics):
    # Select the last period for the pie chart
    last_period = df_aggregated.columns[-1]
    expense_data = df_aggregated.loc[op_expense_metrics, last_period]

    # Create the pie chart
    expense_data.plot(kind='pie', autopct='%1.1f%%', startangle=90, figsize=(8, 8))
    plt.title(f'Distribution of Operating Expenses for Period Ending {last_period.split("/")[-1]}')
    plt.ylabel('') # Hide the y-label
    plt.show()

Gross Margin and Net Margin Analysis
Finally, we can calculate and plot the gross and net margins to see how profitability has changed over time.

if 'Revenues' in df_aggregated.index and 'CostOfRevenue' in df_aggregated.index:
    # Calculate margins
    gross_margin = (df_aggregated.loc['Revenues'] - df_aggregated.loc['CostOfRevenue']) / df_aggregated.loc['Revenues'] * 100
    net_margin = df_aggregated.loc['NetIncomeLoss'] / df_aggregated.loc['Revenues'] * 100
    margin_df = pd.DataFrame({'Gross Margin (%)': gross_margin, 'Net Margin (%)': net_margin})

    # Create the line chart
    margin_df.plot(kind='line', marker='o', figsize=(14, 7))
    plt.title(f'Tesla (CIK: {target_cik}) - Profitability Margins (Form {target_form_type})')
    plt.ylabel('Margin (%)')
    plt.xlabel('Fiscal Period')
    plt.xticks(rotation=45, ha='right')
    plt.grid(True)
    plt.axhline(0, color='red', linestyle='--', linewidth=0.8) # Add a line at 0%
    plt.legend()
    plt.show()

Final Thoughts
This guide showed how to use FinFeedAPI's aggregated XBRL endpoint to perform a quick but insightful analysis of a company's financial performance. By fetching structured data directly, you can bypass the complexities of parsing HTML or raw XBRL and move straight to analysis and visualization. You can extend this script to compare multiple companies, track different financial metrics, or integrate the data with other market information.

A Developer's Guide to Visualizing Apple's 10-K Financial Data

Maciej Józefowicz — Mon, 08 Sep 2025 10:00:21 +0000

Analyzing a company's financial performance over time is a common task for investors and analysts. A company's annual 10-K report is a primary source for this information, but the data is often presented in large tables that can be hard to compare year-over-year.

This guide shows how to programmatically access SEC filings to extract and visualize financial data. Using Apple Inc. as an example, you will see how to retrieve several years of 10-K filings, extract the financial performance tables, and create a stacked bar chart to compare revenue from different product and service categories.

This guide covers:

Fetching metadata for a specific company's 10-K filings.
Extracting the content of a specific item from a filing.
Parsing HTML tables into a structured format using pandas.
Cleaning and preparing the data for visualization.
Creating a stacked bar chart to show financial trends.

What you need:

Python 3.x with pandas and matplotlib.
The api-bricks-sec-api-rest library.
Your personal FinFeedAPI key.

1. Environment Setup
First, install the FinFeedAPI client library.

pip install api-bricks-sec-api-rest

Next, import the necessary libraries and configure the API client with your key.

# Import necessary libraries
import pandas as pd
import matplotlib.pyplot as plt
import api_bricks_sec_api_rest

# --- API Configuration ---
API_KEY = "YOUR_API_KEY_HERE"  # <--- REPLACE THIS WITH YOUR ACTUAL KEY!
api_client_config = api_bricks_sec_api_rest.Configuration()
api_client_config.api_key['Authorization'] = API_KEY
api_client = api_bricks_sec_api_rest.ApiClient(configuration=api_client_config)

# --- Plotting Configuration ---
plt.style.use('seaborn-v0_8-darkgrid')
plt.rcParams['figure.figsize'] = (14, 7)

2. Fetching Filing Metadata
Start by retrieving the metadata for Apple's 10-K filings for the desired date range. This gives you the accession_number for each filing, which is needed to extract the content.

# Initialize the API client for filing metadata
filing_metadata_api = api_bricks_sec_api_rest.FilingMetadataApi(api_client)

# Fetch metadata for Apple's (CIK: 320193) 10-K filings
filings_data = filing_metadata_api.v1_filings_get(
    filling_date_start="2020-01-01",
    filling_date_end="2025-05-07",
    form_type="10-K",
    cik=320193
)

# Create and sort a DataFrame with the filing metadata
df_filings = pd.DataFrame.from_records(
    [vars(x) for x in filings_data], 
    columns=['accession_number', 'filing_date']
)
df_filings = df_filings.sort_values(by='filing_date', ascending=True)

3. Extracting Content from a Filing
With the accession_number of a specific filing, you can extract the content of Item 7, "Management's Discussion and Analysis of Financial Condition and Results of Operations." This section typically contains the tables with financial performance data.

# Initialize the API client for content extraction
content_extraction_api = api_bricks_sec_api_rest.ContentExtractionApi(api_client)

# Get the accession number of the most recent filing
latest_accession_number = df_filings.iloc[-1]['accession_number']

# Extract the HTML content of Item 7
item7_html = content_extraction_api.v1_extractor_item_get(
    accession_number=latest_accession_number,
    item_number="7",
    type="html"
)

4. Reading and Cleaning Financial Tables
The extracted content is in HTML format. You can use pandas' read_html function to automatically parse all the tables from this HTML into a list of DataFrames.

# Read all tables from the HTML string
tables = pd.read_html(item7_html)

# The second table is usually the main financial statement
financial_statements_raw = tables[1]

# Clean the DataFrame by removing unnecessary columns and empty rows
df_cleaned = financial_statements_raw.drop(financial_statements_raw.columns[[0, 1]], axis=1)
mask = (df_cleaned.iloc[1:, :].isna()).all(axis=0)
financial_statements = df_cleaned.drop(df_cleaned.columns[mask], axis=1).fillna('')

5. Preparing Data for Visualization
The data needs to be rearranged to be suitable for a stacked bar chart. This involves selecting the correct rows and columns and then transposing the DataFrame so that the years become the index.

# Select the rows and columns with the revenue data
revenue_data = financial_statements.iloc[[1,2,3,4,5,6], [0,2,8,14]]

# Set the first row as the header
revenue_data.columns = revenue_data.iloc[0]
revenue_data = revenue_data[1:]

# Set the product/service categories as the index
revenue_data = revenue_data.set_index(revenue_data.columns[0])

# Transpose the DataFrame to have years as the index
df_plot = revenue_data.transpose()

6. Visualizing Financial Performance
Finally, create a stacked bar chart to visualize the data. This chart will show the total net sales for each year, broken down by product and service category.

import matplotlib.ticker as ticker

# Create the stacked bar chart
ax = df_plot.plot(kind='bar', stacked=True, figsize=(10, 7))

# Set titles and labels
ax.set_title("Apple - Products and Services Performance", fontsize=16, fontweight='bold')
ax.set_xlabel('Year', fontsize=12)
ax.set_ylabel('Total Net Sales (in millions USD)', fontsize=12)
plt.xticks(rotation=0)

# Add a legend
ax.legend(title='Product/Service Category', loc='upper left')

# Add values to each bar segment
for container in ax.containers:
    ax.bar_label(container, labels=[f'{v:,.0f}' for v in container.datavalues], label_type='center', fontsize=8, color='white')

plt.tight_layout()
plt.show()

Final Thoughts
This guide showed a complete process for turning raw data from an SEC filing into a clear visualization of a company's financial performance. You can adapt this workflow to analyze other companies, different financial metrics, or other sections of the filings. By automating the data extraction and visualization process, you can more efficiently analyze financial reports and identify trends.

Analyzing SEC Filing Patterns with SEC API

Maciej Józefowicz — Thu, 28 Aug 2025 13:43:55 +0000

Filings submitted to the U.S. Securities and Exchange Commission (SEC) are a key source of information about public companies. Analyzing this data can reveal patterns in corporate behavior and market trends, but the sheer volume of filings makes manual review difficult.

This guide shows how to use the FinFeedAPI to programmatically access and analyze SEC filing data. We will cover methods for looking at broad trends using filing metadata and then show how to get specific information from within the documents themselves.

This guide covers:

Fetching filing metadata based on criteria like form type and date.
Analyzing filing frequency over time and the distribution of different event items.
Extracting the structured content from a specific filing.
Searching for keywords inside the full text of documents.

What you need:

Python 3.x with pandas and matplotlib.
The api-bricks-sec-api-rest library.
Your personal FinFeedAPI key.

1. Environment Setup
First, you need to install the FinFeedAPI client library if it is not already on your system.

pip install api-bricks-sec-api-rest

Next, prepare your Python script by importing the necessary libraries and configuring the API client with your key.

# Import necessary libraries
import pandas as pd
import matplotlib.pyplot as plt
from datetime import datetime
import api_bricks_sec_api_rest

# --- API Configuration ---
# !!! IMPORTANT: Insert your API Key below !!!
API_KEY = "YOUR_API_KEY_HERE"  # <--- REPLACE THIS WITH YOUR ACTUAL KEY!
api_client_config = api_bricks_sec_api_rest.Configuration()
api_client_config.api_key['Authorization'] = API_KEY
api_client = api_bricks_sec_api_rest.ApiClient(configuration=api_client_config)

# --- Plotting Configuration ---
plt.style.use('seaborn-v0_8-darkgrid')
plt.rcParams['figure.figsize'] = (12, 6)

2. Fetching and Analyzing Filing Metadata
The /v1/filings endpoint lets you retrieve metadata about filings. This is useful for high-level analysis without needing to process the full content of each document.

Let's fetch all Form 8-K filings submitted in the first quarter of 2024 to see some trends. The code below handles pagination to retrieve all records in the specified period.

# Define parameters for the API call
start_date_q1_2024 = "2024-01-01"
end_date_q1_2024 = "2024-03-31"
target_form_type = "8-K"
results_limit = 200  # Maximum results per page

filing_metadata_api = api_bricks_sec_api_rest.FilingMetadataApi(api_client)
all_metadata = []
page_number = 1

while True:
    print(f"Fetching metadata for {target_form_type} filings (page {page_number})...")
    try:
        metadata_list = filing_metadata_api.v1_filings_get(
            form_type=target_form_type,
            filling_date_start=start_date_q1_2024,
            filling_date_end=end_date_q1_2024,
            page_size=results_limit,
            page_number=page_number
        )
        if metadata_list:
            all_metadata.extend(metadata_list)
            if len(metadata_list) < results_limit:
                print("  Last page reached.")
                break
            page_number += 1
        else:
            print(f"  No more data found on page {page_number}.")
            break
    except api_bricks_sec_api_rest.ApiException as e:
        print(f"Exception when calling API: {e}")
        break

# Create DataFrame after fetching all data
filings_df = pd.DataFrame.from_records([vars(x) for x in all_metadata])

Filings Per Month
With the metadata loaded into a DataFrame, we can plot the number of 8-K filings submitted each month.

if not filings_df.empty:
    filings_df['filing_date'] = pd.to_datetime(filings_df['filing_date'], errors='coerce')
    filings_df_cleaned = filings_df.dropna(subset=['filing_date']).set_index('filing_date')

    if not filings_df_cleaned.empty:
        filings_by_month = filings_df_cleaned.resample('ME').size()

        filings_by_month.plot(kind='bar', color='skyblue', edgecolor='black')
        plt.title(f'Number of {target_form_type} Filings in Q1 2024 (by Month)')
        plt.xlabel('Month')
        plt.ylabel('Number of Filings')
        plt.xticks(rotation=45, ha='right')
        plt.show()

Most Common 8-K Items
We can also analyze the items field to see which types of corporate events were most frequently reported.

if not filings_df.empty and 'items' in filings_df.columns:
    all_items = filings_df['items'].str.split(',').explode()
    item_counts = all_items.value_counts()

    item_counts.plot(kind='bar', color='skyblue', edgecolor='black')
    plt.title('Distribution of Items in 8-K Filings')
    plt.xlabel('Item Number')
    plt.ylabel('Number of Occurrences')
    plt.xticks(rotation=45, ha='right')
    plt.show()

3. Extracting Specific Filing Content
Once you identify a filing of interest from its metadata, you can retrieve its content.

The /v1/extractor endpoint gets the full, structured content of a filing.

The /v1/extractor/item endpoint gets the text of a single item within a filing.

Here is how you can extract the items from the first filing in our dataset.

if not filings_df.empty:
    example_accession_number = filings_df['accession_number'].iloc[0]
    print(f"\nAttempting to extract structure for filing: {example_accession_number}")

    content_extraction_api = api_bricks_sec_api_rest.ContentExtractionApi(api_client)
    try:
        extracted_data = content_extraction_api.v1_extractor_get(
            accession_number=example_accession_number
        )
        if extracted_data:
            print(f"Found {len(extracted_data.items)} items.")
            # Display details of the first item
            first_item = extracted_data.items[0]
            print(f"  Item Number: {first_item.item_number}")
            print(f"  Item Title: {first_item.item_title}")
            print(f"  Content Preview: {first_item.content[:250]}...")

    except api_bricks_sec_api_rest.ApiException as e:
        print(f"Exception when extracting content: {e}")

4. Performing a Full-Text Search
For topic-based discovery, the /v1/full-text endpoint allows you to search for keywords within the documents. This is a good way to find filings related to a specific theme that is not captured in the metadata.

For example, let's find 10-K filings from 2025 that mention "artificial intelligence."

print("\nPerforming full-text search...")

full_text_api = api_bricks_sec_api_rest.FullTextSearchApi(api_client)
try:
    search_results = full_text_api.v1_full_text_get(
        form_type="10-K",
        filling_date_start="2025-01-01",
        filling_date_end="2025-12-31",
        text_contains="artificial intelligence",
        page_size=10
    )
    if search_results:
        search_df = pd.DataFrame.from_records([vars(x) for x in search_results])
        print("Full-Text Search Results Sample:")
        print(search_df[['company_name', 'filing_date']].head())

except api_bricks_sec_api_rest.ApiException as e:
    print(f"Exception during full-text search: {e}")

Final Thoughts
This guide showed several methods for working with SEC filing data using the FinFeedAPI. You can begin with broad, metadata-based analysis to identify trends and then use the extractor and full-text search endpoints to get more specific information. This workflow lets you move from a high-level view of filing activity to a detailed look at the content inside the documents.

From here, you could build more advanced applications, such as applying natural language processing (NLP) to extracted text or correlating filing data with market prices.

A Guide to Analyzing Risk Factor Length in 10-K Filings with FinFeedAPI

Maciej Józefowicz — Thu, 14 Aug 2025 15:31:31 +0000

The "Risk Factors" section, known as Item 1A in Form 10-K annual reports, details the challenges and uncertainties a company faces. A simple quantitative method to gauge perceived risk is to analyze the length of this section over time. An increase in length might correspond with periods of greater uncertainty or new regulations.

This guide shows you how to:

Get metadata for 10-K filings over several years.
Extract the text content of the "Risk Factors" section for each filing.
Measure the length of the extracted content.
Analyze how the median length of Item 1A changes over the years.

This analysis can be intensive in its use of an API because it requires fetching the content for many individual filings.

What you need:

Python 3.x with pandas and matplotlib.
The api-bricks-sec-api-rest library.
Your personal FinFeedAPI key.

1. Environment Setup
First, you need to install the FinFeedAPI client library if it is not already on your system.


pip install api-bricks-sec-api-rest

Next, prepare your Python script. This includes importing the required libraries and configuring the API client with your key.

# Import necessary libraries
import pandas as pd
import matplotlib.pyplot as plt
import time
import re
import api_bricks_sec_api_rest

# --- API Configuration ---
# IMPORTANT: Replace "YOUR_API_KEY_HERE" with your actual key.
API_KEY = "YOUR_API_KEY_HERE"
api_client_config = api_bricks_sec_api_rest.Configuration()
api_client_config.api_key['Authorization'] = API_KEY
api_client = api_bricks_sec_api_rest.ApiClient(configuration=api_client_config)

# --- Analysis Parameters ---
# Years to analyze
START_YEAR = 2018
END_YEAR = 2023

# Max filings per year to analyze (to limit API calls in this demo)
MAX_FILINGS_PER_YEAR = 20 

# Delay between extractor calls (seconds)
API_DELAY = 0.3

# --- Plotting Configuration ---
plt.style.use('seaborn-v0_8-darkgrid')
plt.rcParams['figure.figsize'] = (14, 7)

2. Fetching 10-K Filings Metadata
The first step is to get a list of 10-K filings for each year in your chosen range. This gives you the accession_number for each filing, which is needed to extract its content.

# Initialize the FilingMetadataApi
filing_metadata_api = api_bricks_sec_api_rest.FilingMetadataApi(api_client)
all_10k_metadata = []

for year in range(START_YEAR, END_YEAR + 1):
    print(f"\nFetching 10-K metadata for year: {year}")
    year_start = f"{year}-01-01"
    year_end = f"{year+1}-12-30" 

    filings_this_year = []
    # Fetch a sample of filings for the year
    try:
        page_data = filing_metadata_api.v1_filings_get(
            form_type="10-K",
            filling_date_start=year_start,
            filling_date_end=year_end,
            page_size=MAX_FILINGS_PER_YEAR
        )
        if page_data:
            filings_this_year.extend(page_data)
    except api_bricks_sec_api_rest.ApiException as e:
        print(f"Exception when fetching metadata: {e}")

    all_10k_metadata.extend(filings_this_year)
    print(f"Finished fetching for {year}. Total records so far: {len(all_10k_metadata)}")

# Create DataFrame from metadata
if all_10k_metadata:
    metadata_df = pd.DataFrame.from_records([vars(f) for f in all_10k_metadata])
    metadata_df['filing_date'] = pd.to_datetime(metadata_df['filing_date'], errors='coerce')
    metadata_df['year'] = metadata_df['filing_date'].dt.year
else:
    metadata_df = pd.DataFrame()

3. Extracting Item 1A Content and Calculating Length
Now, loop through the metadata, call the /v1/extractor/item endpoint for each filing, and calculate the length of the returned text. A small delay is added between calls to manage the request rate.

results = [] 

if not metadata_df.empty:
    content_extraction_api = api_bricks_sec_api_rest.ContentExtractionApi(api_client)
    print(f"\nExtracting Item 1A content for {len(metadata_df)} filings...")

    for index, row in metadata_df.iterrows():
        acc_no = row['accession_number']
        year = row['year']
        print(f"  Processing {acc_no} (Year: {year})...")

        item_content = None
        try:
            content = content_extraction_api.v1_extractor_item_get(
                accession_number=acc_no,
                item_number="1A"
            )
            if content is not None:
                item_content = content
        except api_bricks_sec_api_rest.ApiException as e:
            print(f"    Could not extract Item 1A for {acc_no}.")

        time.sleep(API_DELAY)

        # Calculate length if content was found
        if item_content:
            length_chars = len(item_content)
            length_words = len(re.findall(r'\S+', item_content))
            results.append({
                'year': year,
                'accession_number': acc_no,
                'length_chars': length_chars,
                'length_words': length_words
            })
        else:
             results.append({ 'year': year, 'accession_number': acc_no, 'length_chars': None, 'length_words': None })


    length_df = pd.DataFrame(results)
    print("\nFinished extraction and length calculation.")
else:
    length_df = pd.DataFrame()

4. Analyzing Length Trends Over Time
The final step is to analyze the collected data. We will group the results by year and calculate the median word count. The median is used instead of the average to reduce the effect of outliers.

if not length_df.empty:
    length_df_cleaned = length_df.dropna(subset=['length_words'])

    if not length_df_cleaned.empty:
        # Calculate median length per year
        median_length_words = length_df_cleaned.groupby('year')['length_words'].median()
        count_per_year = length_df_cleaned.groupby('year').size()

        # Create the plot
        plt.figure(figsize=(14, 7))
        plt.plot(median_length_words.index, median_length_words.values, marker='o', linestyle='-', color='blue')
        plt.title('Median Length of Item 1A (Risk Factors) in 10-K Filings Over Time')
        plt.ylabel('Median Word Count')
        plt.xlabel('Year')
        plt.grid(True, linestyle='--', alpha=0.7)

        # Add count annotations
        for year, count in count_per_year.items():
             if year in median_length_words.index:
                  plt.text(year, median_length_words[year], f' n={count}', verticalalignment='bottom')

        plt.xticks(median_length_words.index.astype(int))
        plt.tight_layout()
        plt.show()

The plot shows the trend in the median length of the Risk Factors section, with annotations indicating how many filings were analyzed for each year.

Final Thoughts
This guide showed a quantitative method for analyzing the "Risk Factors" section of 10-K filings. We fetched metadata, used the /v1/extractor/item endpoint to get the text of Item 1A, calculated its length, and then visualized the trend over time.

This type of analysis can be a useful addition to qualitative reading, but it has limitations:

The analysis depends on the successful extraction of Item 1A.
Length is a proxy and does not capture the severity or type of risks discussed.
The results are sensitive to the sample of companies analyzed.

Even with these points, this method provides a programmatic way to measure one aspect of corporate risk disclosure.

A Guide to Tracking Keyword Trends in SEC Filings with SEC API

Maciej Józefowicz — Thu, 07 Aug 2025 14:16:39 +0000

Monitoring how often certain keywords appear in SEC filings can show what topics are gaining importance for public companies. By tracking terms like "artificial intelligence," "inflation," or "cybersecurity," your application can surface emerging trends and shifts in market focus.

This guide presents a method for using the FinFeedAPI's /v1/full-textsearch endpoint to perform this kind of analysis. You will see how to search for filings containing specific keywords over monthly periods, get an accurate count of those filings, and then plot the results to visualize the trends.

This guide covers:

How to set up a list of keywords for tracking.
A method to search filings by month and get a full count of keyword mentions.
How to plot the frequency of these mentions over time.

What you need:

Python 3.x with pandas and matplotlib.
The api-bricks-sec-api-restlibrary.
Your personal FinFeedAPI key.

1. Environment Setup
First, you need to install the FinFeedAPI client library if it is not already on your system.

pip install api-bricks-sec-api-rest

Next, prepare your Python script by importing the necessary libraries and configuring the API client with your key.

# Import necessary libraries
import pandas as pd
import matplotlib.pyplot as plt
from datetime import datetime, timedelta
import time
import api_bricks_sec_api_rest

# --- API Configuration ---
# IMPORTANT: Replace "YOUR_API_KEY_HERE" with your actual key.
API_KEY = "YOUR_API_KEY_HERE"
api_client_config = api_bricks_sec_api_rest.Configuration()
api_client_config.api_key['Authorization'] = API_KEY
api_client = api_bricks_sec_api_rest.ApiClient(configuration=api_client_config)

# --- Plotting Configuration ---
plt.style.use('seaborn-v0_8-darkgrid')
plt.rcParams['figure.figsize'] = (15, 8)

2. Searching Filings for Keywords Over Time
The main part of this process is a loop that queries the /v1/full-textendpoint for each keyword over a series of months. To get an accurate count, the code must handle pagination by repeatedly calling the API for the same period until all pages of results have been retrieved.

This method can be intensive in its use of the API, so a small delay is added between page requests to manage the rate of calls.

# --- Analysis Parameters ---
# Keywords/phrases to track
KEYWORDS_TO_TRACK = [
    "artificial intelligence",
    "inflation",
    "supply chain",
    "cybersecurity",
    "ESG" # Environmental, Social, Governance
]

# Time range for analysis
START_YEAR = 2025
END_YEAR = 2025

# Filing type to search within (e.g., '10-K')
TARGET_FORM_TYPE = "10-K"

# --- Data Collection ---
keyword_trends_monthly = {}
page_size = 200
delay_between_pages_seconds = 0.5

# Initialize the FullTextSearchApi
full_text_api = api_bricks_sec_api_rest.FullTextSearchApi(api_client)

for keyword in KEYWORDS_TO_TRACK:
    print(f"\nTracking keyword: '{keyword}'")
    keyword_trends_monthly[keyword] = {}
    for year in range(START_YEAR, END_YEAR + 1):
        for month in range(1, 13):
            start_date_str = f"{year}-{month:02d}-01"
            if month == 12:
                end_date_str = f"{year}-12-31"
            else:
                next_month_date = datetime(year, month + 1, 1)
                end_date_str = (next_month_date - timedelta(days=1)).strftime(f"{year}-%m-%d")

            print(f"  Searching in period: {start_date_str} to {end_date_str}")

            total_count_for_period = 0
            page_number = 1

            while True: # Loop to fetch all pages
                try:
                    results = full_text_api.v1_full_text_get(
                        form_type=TARGET_FORM_TYPE,
                        filling_date_start=start_date_str,
                        filling_date_end=end_date_str,
                        text_contains=keyword,
                        page_size=page_size,
                        page_number=page_number
                    )

                    if results and isinstance(results, list) and len(results) > 0:
                        total_count_for_period += len(results)
                        page_number += 1
                        time.sleep(delay_between_pages_seconds)
                    else:
                        break # No more results, exit the page loop

                except Exception as e:
                    print(f"    An error occurred while fetching page {page_number}: {e}")
                    break

            date_key = f"{year}-{month:02d}"
            keyword_trends_monthly[keyword][date_key] = total_count_for_period
            print(f"  Total count for '{keyword}' in {date_key}: {total_count_for_period}")

# Convert the results dictionary to a DataFrame
trends_df_monthly = pd.DataFrame(keyword_trends_monthly)
trends_df_monthly.index = pd.to_datetime(trends_df_monthly.index)
trends_df_monthly = trends_df_monthly.sort_index()

print("\nKeyword Trend Data (Full Count, by Month):")
print(trends_df_monthly)

3. Visualizing Keyword Trends
After collecting the data, you can plot it to see how the discussion of each topic has changed over time. A line chart is a good way to compare the trends for different keywords.

if not trends_df_monthly.empty:
    plt.figure(figsize=(15, 8))

    for keyword in trends_df_monthly.columns:
        plt.plot(trends_df_monthly.index, trends_df_monthly[keyword], marker='o', linestyle='-', label=keyword)

    plt.title(f'Keyword Mentions in {TARGET_FORM_TYPE or "All"} Filings Over Time (Monthly)')
    plt.xlabel('Month')
    plt.ylabel(f'Number of Filings Found')
    plt.legend(title="Keywords")
    plt.grid(True, linestyle='--', alpha=0.7)
    plt.xticks(rotation=45, ha='right')
    plt.ylim(bottom=0)
    plt.tight_layout()
    plt.show()
else:
    print("No monthly trend data collected to visualize.")

Final Thoughts
This guide presented a method for using the FinFeedAPI's full-text search to quantify and track keyword trends in SEC filings. The key to getting accurate counts is to handle the API's pagination correctly by fetching all pages of results for each search.

A few points to keep in mind for your own applications:

API Usage: This method makes many API calls, especially with a long list of keywords or a wide date range. Be aware of any rate limits or costs associated with your API subscription.
Execution Time: The process can take a while to complete because of the number of calls and the added delay between them.
Keyword Choice: The quality of the results depends on selecting good keywords. You might want to include variations or related terms in your searches.

This approach gives you a way to analyze the changing themes and priorities discussed in corporate disclosures.

Tracking Keyword Trends in SEC Filings with Full-Text Search

Maciej Józefowicz — Mon, 21 Jul 2025 09:33:25 +0000

This guide covers:

How to set up a list of keywords for tracking.
A method to search filings by month and get a full count of keyword mentions.
How to plot the frequency of these mentions over time.

What you need:

Python 3.x with pandas and matplotlib.
The api-bricks-sec-api-rest library.
Your personal FinFeedAPI key.

1. Environment Setup
First, you need to install the FinFeedAPI client library if it is not already on your system.

pip install api-bricks-sec-api-rest

Next, prepare your Python script by importing the necessary libraries and configuring the API client with your key.

# Import necessary libraries
import pandas as pd
import matplotlib.pyplot as plt
from datetime import datetime, timedelta
import time
import api_bricks_sec_api_rest

# --- API Configuration ---
# IMPORTANT: Replace "YOUR_API_KEY_HERE" with your actual key.
API_KEY = "YOUR_API_KEY_HERE"
api_client_config = api_bricks_sec_api_rest.Configuration()
api_client_config.api_key['Authorization'] = API_KEY
api_client = api_bricks_sec_api_rest.ApiClient(configuration=api_client_config)

# --- Plotting Configuration ---
plt.style.use('seaborn-v0_8-darkgrid')
plt.rcParams['figure.figsize'] = (15, 8)

2. Searching Filings for Keywords Over Time
The main part of this process is a loop that queries the/v1/full-textendpoint for each keyword over a series of months. To get an accurate count, the code must handle pagination by repeatedly calling the API for the same period until all pages of results have been retrieved.

This method can be intensive in its use of the API, so a small delay is added between page requests to manage the rate of calls.

# --- Analysis Parameters ---
# Keywords/phrases to track
KEYWORDS_TO_TRACK = [
    "artificial intelligence",
    "inflation",
    "supply chain",
    "cybersecurity",
    "ESG" # Environmental, Social, Governance
]

# Time range for analysis
START_YEAR = 2025
END_YEAR = 2025

# Filing type to search within (e.g., '10-K')
TARGET_FORM_TYPE = "10-K"

# --- Data Collection ---
keyword_trends_monthly = {}
page_size = 200
delay_between_pages_seconds = 0.5

# Initialize the FullTextSearchApi
full_text_api = api_bricks_sec_api_rest.FullTextSearchApi(api_client)

for keyword in KEYWORDS_TO_TRACK:
    print(f"\nTracking keyword: '{keyword}'")
    keyword_trends_monthly[keyword] = {}
    for year in range(START_YEAR, END_YEAR + 1):
        for month in range(1, 13):
            start_date_str = f"{year}-{month:02d}-01"
            if month == 12:
                end_date_str = f"{year}-12-31"
            else:
                next_month_date = datetime(year, month + 1, 1)
                end_date_str = (next_month_date - timedelta(days=1)).strftime(f"{year}-%m-%d")

            print(f"  Searching in period: {start_date_str} to {end_date_str}")

            total_count_for_period = 0
            page_number = 1

            while True: # Loop to fetch all pages
                try:
                    results = full_text_api.v1_full_text_get(
                        form_type=TARGET_FORM_TYPE,
                        filling_date_start=start_date_str,
                        filling_date_end=end_date_str,
                        text_contains=keyword,
                        page_size=page_size,
                        page_number=page_number
                    )

                    if results and isinstance(results, list) and len(results) > 0:
                        total_count_for_period += len(results)
                        page_number += 1
                        time.sleep(delay_between_pages_seconds)
                    else:
                        break # No more results, exit the page loop

                except Exception as e:
                    print(f"    An error occurred while fetching page {page_number}: {e}")
                    break

            date_key = f"{year}-{month:02d}"
            keyword_trends_monthly[keyword][date_key] = total_count_for_period
            print(f"  Total count for '{keyword}' in {date_key}: {total_count_for_period}")

# Convert the results dictionary to a DataFrame
trends_df_monthly = pd.DataFrame(keyword_trends_monthly)
trends_df_monthly.index = pd.to_datetime(trends_df_monthly.index)
trends_df_monthly = trends_df_monthly.sort_index()

print("\nKeyword Trend Data (Full Count, by Month):")
print(trends_df_monthly)

if not trends_df_monthly.empty:
    plt.figure(figsize=(15, 8))

    for keyword in trends_df_monthly.columns:
        plt.plot(trends_df_monthly.index, trends_df_monthly[keyword], marker='o', linestyle='-', label=keyword)

    plt.title(f'Keyword Mentions in {TARGET_FORM_TYPE or "All"} Filings Over Time (Monthly)')
    plt.xlabel('Month')
    plt.ylabel(f'Number of Filings Found')
    plt.legend(title="Keywords")
    plt.grid(True, linestyle='--', alpha=0.7)
    plt.xticks(rotation=45, ha='right')
    plt.ylim(bottom=0)
    plt.tight_layout()
    plt.show()
else:
    print("No monthly trend data collected to visualize.")

The chart will show a separate line for each keyword, making it easy to spot which topics are becoming more or less common in company filings.

A few points to keep in mind for your own applications:

API Usage: This method makes many API calls, especially with a long list of keywords or a wide date range. Be aware of any rate limits or costs associated with your API subscription.
Execution Time: The process can take a while to complete because of the number of calls and the added delay between them.
Keyword Choice: The quality of the results depends on selecting good keywords. You might want to include variations or related terms in your searches.

This approach gives you a way to analyze the changing themes and priorities discussed in corporate disclosures.

How to Detect Corporate Events with 8-K Filings | FinFeedAPI Guide

Maciej Józefowicz — Sun, 13 Jul 2025 13:24:34 +0000

For any developer building a financial application, the ability to programmatically detect and react to corporate events is a significant advantage. Form 8-K filings are the SEC's mechanism for reporting unscheduled, material events—information that can directly impact a company's stock price and market sentiment. Manually tracking these filings is impossible at scale, which is why automating the process is so valuable.

By fetching and parsing 8-K data, your application can:

Generate Trading Signals: Events like the announcement of a merger (Item 1.01), unexpected executive departures (Item 5.02), or bankruptcy proceedings (Item 1.03) can serve as powerful inputs for algorithmic trading strategies.
Improve Risk Management: Automatically flag companies in a portfolio that report events related to financial obligations or non-reliance on previously issued financial statements (Item 4.02).
Create Smarter News Feeds: Build a real-time news feed that goes beyond headlines, providing users with alerts based on the specific substance of an SEC filing.
Conduct Quantitative Analysis: Aggregate event data over time to find correlations between certain types of events and future stock performance.

This guide walks you through building such a system using Python and the FinFeedAPI. You will see how to fetch 8-K filings, filter them for a specific event type, examine how often that event occurs, and then pull the exact text describing it.

This guide covers:

Fetching 8-K filings that report a specific event.
Analyzing the frequency of that event over time.
Extracting the detailed text associated with the event.

What you need:

Python 3.x with pandas and matplotlib.
The api-bricks-sec-api-rest library.
Your FinFeedAPI key.

1. Environment Setup
First, you need to install the FinFeedAPI client library.

pip install api-bricks-sec-api-rest

Next, prepare your Python script. This includes importing the required libraries and configuring the API client with your key. For this example, we will track Item 5.02, which relates to the departure or appointment of directors and certain officers.

# Import necessary libraries
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib.dates as mdates
from datetime import datetime
import api_bricks_sec_api_rest

# --- API Configuration ---
# IMPORTANT: Replace "YOUR_API_KEY_HERE" with your actual key.
API_KEY = "YOUR_API_KEY_HERE"
api_client_config = api_bricks_sec_api_rest.Configuration()
api_client_config.api_key['Authorization'] = API_KEY
api_client = api_bricks_sec_api_rest.ApiClient(configuration=api_client_config)

# --- Analysis Parameters ---
# Define the event item number to track
TARGET_EVENT_ITEM = "5.02" # Example: Track executive/director changes

# Define time range (e.g., look back one year)
end_date = datetime.now().strftime('%Y-%m-%d')
start_date = (datetime.now() - pd.DateOffset(years=1)).strftime('%Y-%m-%d')

# --- Plotting Configuration ---
plt.style.use('seaborn-v0_8-darkgrid')
plt.rcParams['figure.figsize'] = (14, 7)

Fetching 8-K Filings for a Specific Event The most direct way to find filings related to a specific event is to use the items_containparameter in the /v1/filings endpoint. This allows you to filter for 8-Ks that list your target item number.

The following code fetches all 8-K filings from the last year that contain Item 5.02.

# Initialize the FilingMetadataApi
filing_metadata_api = api_bricks_sec_api_rest.FilingMetadataApi(api_client)

print(f"Fetching 8-K filings containing Item '{TARGET_EVENT_ITEM}'...")

event_filings = []
current_page = 1
page_size = 200

while True:
    try:
        page_data = filing_metadata_api.v1_filings_get(
            form_type="8-K",
            filling_date_start=start_date,
            filling_date_end=end_date,
            items_contain=TARGET_EVENT_ITEM, # Direct filter
            page_size=page_size,
            page_number=current_page
        )
        if page_data:
            event_filings.extend(page_data)
            print(f"  Fetched page {current_page}, {len(page_data)} records. Total: {len(event_filings)}")
            if len(page_data) < page_size:
                print("  Last page reached.")
                break
            current_page += 1
        else:
            print(f"  No more data found.")
            break
    except api_bricks_sec_api_rest.ApiException as e:
        print(f"API Exception occurred: {e}")
        break

# Process results into a DataFrame
if event_filings:
    event_filings_df = pd.DataFrame.from_records([vars(f) for f in event_filings])
    event_filings_df['filing_date'] = pd.to_datetime(event_filings_df['filing_date'], errors='coerce')
    print(f"\nFound {len(event_filings_df)} filings containing Item {TARGET_EVENT_ITEM}.")
else:
    print(f"\nNo filings found for Item {TARGET_EVENT_ITEM}.")
    event_filings_df = pd.DataFrame()

An alternative, more thorough method is to fetch all 8-K filings in a period and then use the /v1/extractor endpoint on each one to check its items. This requires more API calls but can be more reliable if the items_contain filter is not specific enough for your needs. For the rest of this guide, we will use the results from the direct filtering method above.

3. Analyze Event Frequency
With a list of relevant filings, you can analyze how often this event occurs. A bar chart showing the number of event filings per month is a good way to visualize this.

if not event_filings_df.empty:
    event_filings_df = event_filings_df.dropna(subset=['filing_date'])
    if not event_filings_df.empty:
        # Resample by month and count the number of filings
        events_by_month = event_filings_df.set_index('filing_date').resample('ME').size()

        # Create the plot
        plt.figure(figsize=(14, 7))
        events_by_month.plot(kind='bar', color='purple', edgecolor='black')
        plt.title(f'Frequency of 8-K Filings with Item {TARGET_EVENT_ITEM} (Monthly)')
        plt.xlabel('Month')
        plt.ylabel('Number of Filings')
        plt.xticks(rotation=45, ha='right')
        plt.grid(True, axis='y', linestyle='--', alpha=0.7)
        plt.tight_layout()
        plt.show()
else:
    print("No event filings data available to analyze frequency.")

This code groups the filings by month and plots the count, giving you a clear view of when the target event was most frequently reported.

4. Extract Specific Event Details

The final step is to get the actual text describing the event. Using the accession_number from one of the filings you found, you can call the /v1/extractor/item endpoint to get the content for just that item.

if not event_filings_df.empty:
    # Select the most recent event filing
    event_to_extract = event_filings_df.sort_values('filing_date', ascending=False).iloc[0]
    acc_no = event_to_extract['accession_number']

    print(f"\nExtracting details for Item '{TARGET_EVENT_ITEM}' from filing: {acc_no}")

    # Initialize the ContentExtractionApi
    content_extraction_api = api_bricks_sec_api_rest.ContentExtractionApi(api_client)

    try:
        event_content = content_extraction_api.v1_extractor_item_get(
            accession_number=acc_no,
            item_number=TARGET_EVENT_ITEM
        )
        if event_content:
            print(f"\nContent for Item {TARGET_EVENT_ITEM} (first 1000 chars):\n")
            print(event_content[:1000] + "...")
    except api_bricks_sec_api_rest.ApiException as e:
        print(f"API Exception when extracting item: {e}")
else:
    print("\nNo filings identified to extract details from.")

This code selects the latest filing from our list and retrieves the specific text related to Item 5.02, giving you the direct information about the officer change.

Final Thoughts
This guide showed how to use the FinFeedAPI to build a workflow for detecting and analyzing specific corporate events from 8-K filings. By filtering for item numbers, you can turn unstructured regulatory documents into a structured feed of events. This method can be adapted to track any of the various 8-K item types, providing timely information for your financial applications.

A guide to Company Filings: CIK-based Analysis with FinFeedAPI

Maciej Józefowicz — Tue, 08 Jul 2025 10:32:50 +0000

When you're building a financial app, your users don't want to dig through mountains of data—they want info on the specific companies they're tracking. Using a company's CIK is the most direct way to deliver that.

Filtering by CIK lets your app:

Create company-specific views: Pull together all the 10-Ks, 8-Ks, and other filings for a single stock.
Send targeted alerts: Let users know the moment a company they follow files something important.
Enable competitor analysis: Grab data for a handful of companies in the same industry so your users can compare them.

This guide will walk you through how to do it with the FinFeedAPI.

A Guide to Company Filings: CIK-Based Analysis

When examining public companies, it is a frequent need to concentrate on a single entity. Instead of searching through all market-wide filings, you can separate the documents of one specific company. This method uses the Central Index Key (CIK), a unique number the SEC assigns to each registrant.

This guide will show you how to use a company's CIK with the FinFeedAPI to build a detailed overview of its filing activity.

This guide covers:

Retrieving a company's filings using its CIK.
Plotting a timeline of major reports (10-K, 10-Q, 8-K).
Examining the frequency of different form types.
Getting the content of specific sections, like "Risk Factors," from a filing.

What you need:

Python 3.x and experience with pandas and matplotlib.
The api-bricks-sec-api-rest Python library.
Your personal FinFeedAPI key.

1. Environment Setup

The first action is to install the FinFeedAPI client library if it is not already on your system.

pip install api-bricks-sec-api-rest

Then, import the necessary libraries and configure your API client. This example uses Apple Inc., which has a CIK of 320193.

# Import necessary libraries
import pandas as pd
import matplotlib.pyplot as plt
import matplotlib.dates as mdates
from datetime import datetime
import api_bricks_sec_api_rest

# --- API Configuration ---
# IMPORTANT: Replace "YOUR_API_KEY_HERE" with your actual FinFeedAPI key.
API_KEY = "YOUR_API_KEY_HERE"
api_client_config = api_bricks_sec_api_rest.Configuration()
api_client_config.api_key['Authorization'] = API_KEY
api_client = api_bricks_sec_api_rest.ApiClient(configuration=api_client_config)

# --- Target Company ---
# Example CIKs: Apple (320193), Microsoft (789019), Google (1652044)
TARGET_CIK = 320193 

# --- Plotting Configuration ---
plt.style.use('seaborn-v0_8-darkgrid')
plt.rcParams['figure.figsize'] = (15, 7)

This cell sets up the environment. It defines the CIK for the target company (Apple) and initializes the API client with a key.

2. Retrieving All Filings for a CIK

To get a full history, you must query the /v1/filings endpoint and manage paged results. The API returns information in pages, with up to 200 records per page. The code below will request each page until all filings for the target company over the last five years are retrieved.

# Define time range and initialize API instances
end_date = datetime.now().strftime('%Y-%m-%d')
start_date = (datetime.now() - pd.DateOffset(years=5)).strftime('%Y-%m-%d')
filing_metadata_api = api_bricks_sec_api_rest.FilingMetadataApi(api_client)

print(f"Fetching all filings for CIK {TARGET_CIK} from {start_date} to {end_date}...")

company_filings = []
current_page = 1
page_size = 200 # Max page size

while True:
    try:
        page_data = filing_metadata_api.v1_filings_get(
            cik=TARGET_CIK,
            filling_date_start=start_date,
            filling_date_end=end_date,
            page_size=page_size,
            page_number=current_page
        )

        if page_data:
            company_filings.extend(page_data)
            print(f"  Fetched page {current_page}, {len(page_data)} records. Total: {len(company_filings)}")
            if len(page_data) < page_size:
                print("  Last page reached.")
                break
            current_page += 1
        else:
            print(f"  No more data found on page {current_page}.")
            break

    except api_bricks_sec_api_rest.ApiException as e:
        print(f"API Exception occurred: {e}")
        break

# Process the results into a DataFrame
if company_filings:
    company_filings_df = pd.DataFrame.from_records([vars(f) for f in company_filings])
    company_filings_df['filing_date'] = pd.to_datetime(company_filings_df['filing_date'], errors='coerce')
    print(f"\nSuccessfully fetched {len(company_filings_df)} total filings for CIK {TARGET_CIK}.")
    print("\nSample of fetched data:")
    print(company_filings_df[['filing_date', 'form', 'accession_number', 'primary_doc_description']].head())
else:
    print(f"\nNo filings found for CIK {TARGET_CIK} in the specified date range.")
    company_filings_df = pd.DataFrame() # Create empty DataFrame to avoid errors

The code here calls the API in a loop, incrementing the page_number with each call, until all filings for the specified CIK and date range are obtained. The results are then loaded into a pandas DataFrame.

3. Plotting the Filing Timeline

A timeline plot displays when a company makes its important reports. You can create a scatter plot that shows the filing dates for major form types like 10-K (annual), 10-Q (quarterly), and 8-K (current events).

if not company_filings_df.empty:
    # Filter for major form types
    major_forms = ['10-K', '10-Q', '8-K']
    timeline_df = company_filings_df[company_filings_df['form'].isin(major_forms)].copy()
    timeline_df = timeline_df.dropna(subset=['filing_date'])

    if not timeline_df.empty:
        # Create the plot
        fig, ax = plt.subplots(figsize=(18, 8))
        colors = {'10-K': 'red', '10-Q': 'blue', '8-K': 'green'}
        markers = {'10-K': 'o', '10-Q': 's', '8-K': '^'}

        for form_type in major_forms:
            subset = timeline_df[timeline_df['form'] == form_type]
            if not subset.empty:
                ax.scatter(subset['filing_date'], subset['form'],
                           label=form_type,
                           color=colors[form_type],
                           marker=markers[form_type],
                           s=80, alpha=0.7)

        # Formatting the plot
        ax.set_title(f'Filing Timeline for CIK {TARGET_CIK}')
        ax.set_xlabel('Filing Date')
        ax.set_ylabel('Form Type')
        ax.legend(title="Form Types")
        ax.grid(True, axis='x', linestyle='--', alpha=0.6)

        # Improve date formatting on x-axis
        ax.xaxis.set_major_locator(mdates.YearLocator())
        ax.xaxis.set_major_formatter(mdates.DateFormatter('%Y'))
        plt.setp(ax.xaxis.get_majorticklabels(), rotation=45, ha='right')

        plt.tight_layout()
        plt.show()
    else:
        print("No 10-K, 10-Q, or 8-K filings found for timeline visualization.")

This code filters the DataFrame for the three major form types and then uses matplotlib to create a scatter plot. Each point on the plot represents a single filing, showing its type and date of submission.

4. Examining Form Type Frequency

You can see which forms the company files most often. A bar chart can show this distribution.

if not company_filings_df.empty:
    form_counts = company_filings_df['form'].value_counts()

    # Plot the top N form types
    top_n = 15
    plt.figure(figsize=(12, 6))
    form_counts.head(top_n).plot(kind='bar', color='teal', edgecolor='black')
    plt.title(f'Top {top_n} Most Frequent Form Types for CIK {TARGET_CIK}')
    plt.xlabel('Form Type')
    plt.ylabel('Number of Filings')
    plt.xticks(rotation=45, ha='right')
    plt.grid(True, axis='y', linestyle='--', alpha=0.7)
    plt.tight_layout()
    plt.show()

The value_counts() method in pandas is used to count the occurrences of each form type. The code then plots the top 15 most frequent forms.

5. Getting Specific Content from a Filing

This section demonstrates getting the content of the "Risk Factors" section (Item 1A) from the company's most recent 10-K filing. This shows how to get the actual content using metadata like the accession_number.

if not company_filings_df.empty:
    # Find the most recent 10-K filing
    latest_10k_list = company_filings_df[company_filings_df['form'] == '10-K'].sort_values('filing_date', ascending=False)

    if not latest_10k_list.empty:
        latest_10k_accession_number = latest_10k_list.iloc[0]['accession_number']
        print(f"\nAttempting to extract 'Item 1A' (Risk Factors) from latest 10-K: {latest_10k_accession_number}")

        content_extraction_api = api_bricks_sec_api_rest.ContentExtractionApi(api_client)
        try:
            risk_factors_content = content_extraction_api.v1_extractor_item_get(
                accession_number=latest_10k_accession_number,
                item_number="1A" # Standard item number for Risk Factors
            )
            if risk_factors_content:
                print("\nSuccessfully extracted Risk Factors (Item 1A). Preview:")
                print(risk_factors_content[:1000] + "...")
            else:
                print("Failed to extract content for Item 1A.")
        except api_bricks_sec_api_rest.ApiException as e:
            print(f"API Exception when extracting Item 1A: {e}")
    else:
        print("\nNo 10-K filings found in the fetched data to extract from.")

This code snippet first identifies the most recent 10-K from the DataFrame. It then uses that filing's accession_number to call the /v1/extractor/item endpoint, requesting the content for item_number="1A".

Final Thoughts

By using a company's CIK, you can retrieve its entire filing history with the FinFeedAPI. This guide showed how to get this data, plot key reporting timelines and frequencies, and then get the content of specific sections. This method is a fundamental technique for any detailed analysis of a single public company.