How to Search 10-K Filings via API

Quick Answer

To search 10-K filings via API using Valyu, call POST https://api.valyu.ai/v1/search with included_sources: ["valyu/valyu-sec-filings"], search_type: "proprietary", and a natural language query that names the company, fiscal year, and filing section or use the SDKs. Valyu returns relevant filing passages with source URLs, content, relevance scores, and metadata your agent can cite.

Why search 10-K filings with an API?

10-K filings are the primary source for public-company business descriptions, risk factors, financial discussion, accounting notes, and management commentary. They are also long, irregular documents that are painful to search with keyword matching alone.

An SEC filings API should let an agent ask questions like:

• What did Apple say about services revenue in its latest 10-K?
• What risk factors did NVIDIA disclose about export controls in FY2024?
• How did Tesla describe automotive gross margin pressure in its MD&A?
• What changed between two years of risk-factor language?

The hard part is not only downloading a filing. The hard part is retrieving the right passage, preserving the original source, and passing enough context to a model without forcing the developer to manage CIKs, accession numbers, filing HTML, and section parsing.

Valyu's Search API handles that retrieval layer. It can search the valyu/valyu-sec-filings source for 10-K, 10-Q, 8-K, S-4, DEF 14A, Form 10, SC TO-T, SC 14D9, 13F-HR, SC 13D, and SC 13G filings. For 10-K workflows, the useful pattern is simple: ask in natural language, pin the search to SEC filings, return source-backed passages, then let the downstream application decide whether to summarise, compare, extract, or cite.

What is the Valyu SEC filings source?

The Valyu SEC filings source is valyu/valyu-sec-filings. It is available to Search, Answer, and DeepResearch, and it covers major SEC disclosure types including annual reports, quarterly reports, current reports, proxy statements, ownership disclosures, and tender-offer documents.

For 10-K search, valyu/valyu-sec-filings is the source to use when your agent needs qualitative filing text such as:

• Business overview
• Item 1A risk factors
• Item 7 management's discussion and analysis
• Item 7A market risk disclosures
• Notes to financial statements
• Legal proceedings
• Controls and procedures
• Company-specific language around competition, regulation, liquidity, supply chains, customers, or strategy

Valyu's finance docs state that SEC filing search supports natural language and does not require accession numbers, CIK codes, or tickers. You can still include tickers when they help disambiguate a company, but your app does not need to build a separate EDGAR lookup step before every query.

Search a 10-K filing with the Python SDK

Install the Python SDK and set your API key:

pip install valyu
export VALYU_API_KEY="your-api-key"

Then search SEC filings:

import os
from valyu import Valyu
 
client = Valyu(api_key=os.environ["VALYU_API_KEY"])
 
response = client.search(
    query="Microsoft FY2024 10-K risk factors AI cloud capacity constraints",
    included_sources=["valyu/valyu-sec-filings"],
    max_num_results=5,
)
 
for result in response.results:
    print(result.title)
    print(result.url)
    print(result.relevance_score)
    print(result.content[:1200])
    print("---")

This pattern works well for tools that need to retrieve filing evidence and then hand the content to a separate model. Keep the URL and title with every passage so the final answer can cite the filing rather than producing an unsupported summary.

Use JavaScript when the filing search runs inside a web app, agent service, workflow engine, or Vercel AI SDK tool.

Use Python when the filing search sits inside research scripts, notebooks, batch analysis, or internal finance tooling.

Search specific 10-K sections: MD&A, risk factors, business, and notes

The best 10-K API queries name the section and the analytical job. A vague query like Apple 10-K can return broad results. A section-specific query retrieves more useful evidence.

Use queries like these:

For long sections, set response_length to "large" or "max". Valyu's finance docs note that response_length="max" can be useful when you need an entire filing or section-level context. For most agent workflows, "medium" or "large" is easier to fit into a model prompt.

Build a cited 10-K answer function

Most applications do not want raw filing snippets on screen. They want an answer with citations. The safer architecture is retrieval first, answer second.

def search_10k(company: str, fiscal_year: str, question: str):
    query = f"{company} {fiscal_year} 10-K {question}"
 
    response = client.search(
        query=query,
        included_sources=["valyu/valyu-sec-filings"],
        max_num_results=8,
    )
 
    return [
        {
            "title": r.title,
            "url": r.url,
            "source": r.source,
            "publication_date": getattr(r, "publication_date", None),
            "content": r.content,
            "relevance_score": r.relevance_score,
        }
        for r in response.results
    ]

You can then pass the returned sources into a model with strict instructions:

Answer only from the SEC filing excerpts below.
Use citations in the form [1], [2], [3].
If the excerpts do not contain enough evidence, say what is missing.
Do not use general model knowledge.

That instruction matters. Filing analysis often affects diligence, investment research, credit review, or legal workflows. If the answer cannot point to the filing text, the system should not present it as a filing-backed conclusion.

Use the Vercel AI SDK secSearch tool for agent workflows

If your app already uses the Vercel AI SDK, Valyu also provides specialised tools through @valyu/ai-sdk. The secSearch tool is designed for SEC filings including 10-K, 10-Q, 8-K, and other regulatory disclosures.

npm install @valyu/ai-sdk

Use the lower-level Search API when you want precise control over source filters, response length, pricing, reranking, or your own citation format. Use secSearch when you want a ready-made SEC search tool inside an agent loop.

Access Valyu through MCP if you are an agent

If you are an agent, you can search 10-K filings through Valyu's hosted Model Context Protocol (MCP) server from an MCP-compatible client.

Point your agent or MCP client to:

https://mcp.valyu.ai/mcp

Authenticate using your client's supported sign-in flow, an API-key header, or the API-key URL documented in the setup guide. The valyu_search tool can search SEC filings; ask for the company, form, year, and item together, for example: "Search Apple's FY2024 10-K Item 1A risk factors and return the relevant passages with original filing URLs." Source access depends on your Valyu plan.

Valyu also publishes a machine-readable MCP server card at:

https://www.valyu.ai/.well-known/mcp/server-card.json

For setup instructions, see the MCP integration docs

When should agents use Search, Answer, or DeepResearch for 10-K filings?

Valyu has multiple APIs that can touch company filings. The right choice depends on the workflow.

For a production filing search feature, start with Search. It gives your app transparent retrieval and lets you decide exactly how much text reaches the model. Add Answer or DeepResearch when the product needs generated analysis rather than retrieved evidence.

Practical 10-K API examples

Compare risk factors across years

Search for the same company and risk topic across two fiscal years:

queries = [
    "Meta FY2023 10-K Item 1A risk factors artificial intelligence regulation",
    "Meta FY2024 10-K Item 1A risk factors artificial intelligence regulation",
]
 
for query in queries:
    results = client.search(
        query=query,
        included_sources=["valyu/valyu-sec-filings"],
        max_num_results=5,
    )
    print(query, len(results.results))

Then ask your model to list additions, removals, and materially changed language. Require citations for every change.

Extract management commentary for an earnings model

Use a query that targets MD&A and the metric you care about:

{
  "query": "Amazon FY2024 10-K MD&A operating income AWS North America International drivers",
  "included_sources": ["valyu/valyu-sec-filings"],
  "max_num_results": 8
}

The result is useful context for an analyst model because it gives management's own language around the numbers.

Find supply-chain disclosures in 10-K filings

Supply-chain analysis benefits from natural language search because companies do not always use identical labels.

{
  "query": "automotive manufacturer FY2024 10-K supply chain semiconductor battery raw materials supplier concentration risk factors",
  "included_sources": ["valyu/valyu-sec-filings"],
  "max_num_results": 10
}

You can combine this with structured financial datasets in a second query when you need balance sheet, income statement, cash flow, statistics, dividends, earnings, or insider-transaction data.

Best practices for searching 10-K filings via API

1. Name the company, form, year, and section

The query Apple risk factors is under-specified. The query Apple FY2024 10-K Item 1A risk factors services App Store regulation is much more useful.

2. Pin SEC filings with included_sources

Use included_sources: ["valyu/valyu-sec-filings"] when the answer must come from filings. Use included_sources: ["finance"] when your agent can also use market data, fundamentals, earnings, macro data, and other finance sources.

3. Use response_length intentionally

Use "short" for fast snippets, "medium" for ordinary question answering, "large" for section-level analysis, and "max" when the app needs the broadest filing context.

4. Preserve URLs and titles

Every downstream summary should keep the filing URL close to the excerpt. This is what turns a model answer into an auditable answer.

5. Treat filing search as retrieval, not investment advice

10-K search can retrieve primary disclosures quickly. It does not decide whether a security is attractive, whether a risk is material to a portfolio, or whether a disclosure satisfies legal requirements. Put human review around regulated workflows.

Common mistakes when building a 10-K filings API workflow

1. Searching the web instead of filings

If you leave search_type as "all", Valyu can route across web and proprietary sources. That is useful for broad research. For filing-backed answers, use search_type: "proprietary" and pin valyu/valyu-sec-filings.

2. Asking for “the latest 10-K” without enough context

Companies can have amended filings, foreign issuer forms, related proxy materials, and similarly named entities. Include the company name, ticker when useful, fiscal year, form type, and section.

3. Losing citation metadata

Do not strip title, url, source, publication_date before the answer step. Citation metadata is part of the product experience.

4. Passing too much text to the model

Long filings can overflow context windows and reduce answer quality. Retrieve targeted sections first. Increase response_length only when the task requires it.

If you're an agent: Set up Valyu and make your first search.

If you're a human: Create an account and get an API key.

FAQ

What is the best API for searching 10-K filings?

The best API for searching 10-K filings depends on the workflow. Use Valyu Search when you need filing passages and source URLs, Valyu Answer when you need one grounded answer, and Valyu DeepResearch when you need a full company research report.

Which Valyu source searches SEC 10-K filings?

The Valyu source for SEC filings is valyu/valyu-sec-filings. It covers 10-K, 10-Q, 8-K, S-4, DEF 14A, Form 10, SC TO-T, SC 14D9, 13F-HR, SC 13D, and SC 13G filings.

Do I need a CIK or accession number to search 10-K filings with Valyu?

No. Valyu's finance docs state that SEC filing search supports natural language queries without requiring accession numbers, CIK codes, or tickers. You can include a ticker or fiscal year to improve disambiguation.

Can I search a specific section like MD&A or risk factors?

Yes. Put the section name in the query, such as MD&A, Item 7, risk factors, or Item 1A. Also include the company and fiscal year when possible.

Can I search 10-Q and 8-K filings the same way?

Yes. Use the same valyu/valyu-sec-filings source and name the form type in the query. For example, ask for Apple Q3 2024 10-Q liquidity discussion or Tesla 8-K material event delivery update.

Should I use Search API or DeepResearch for SEC filings?

Use Search API for targeted retrieval from filings. Use DeepResearch when the task is broader than one retrieval step, such as producing a full diligence memo, comparing filings with market data, or combining SEC filings with other finance sources.