b872051a52
These suites turn warnings into errors, and pandas 3.1.0 adds Pandas4Warning deprecations for several patterns they use. Every change also passes with the locked pandas 3.0.6. - fred, sec: replace inplace=True sort_values/reset_index/rename/ set_index/drop with reassignment - fred balance_of_payments, sec as_filed_widget: replace fillna with a string on float columns by astype(object).where(notna, ...) - sec: build quarter start dates from ISO strings instead of parsing "2024Q2"-style strings; use the DataFrame constructor instead of DataFrame.from_records for column dicts; pad CIK lookup rows to two fields instead of constructing a ragged DataFrame - eia: read EIA workbooks with the calamine engine (xlrd is deprecated); replace the xlrd dependency with python-calamine and relock; calamine workbooks are not safe for concurrent reads, so the petroleum status report serializes its sheet reads with a lock
OpenBB SEC Provider
Free, key-less access to U.S. SEC EDGAR data for the OpenBB Platform — filings, financial statements, fund holdings, ownership, and full-text search, with a built-in OpenBB Workspace backend.
No credentials or API key required. Responses are persisted to a local disk cache so repeated queries are fast and offline-friendly.
Quick start
Launch the OpenBB Workspace backend with no prior install — uv fetches the package and runs it in one step:
uvx openbb-sec serve --host 0.0.0.0 --port 6900
Then add http://localhost:6900 as a custom backend in the OpenBB Workspace.
Installation
pip install openbb-sec
A single install brings the provider, the OpenBB Workspace dashboards, the Filing Viewer MCP, and the openbb-sec command.
Coverage
All endpoints are available under obb.sec.* in the Python/HTTP interface.
| Area | Endpoints |
|---|---|
| Filings & documents | company_filings, latest_financial_reports, filing_headers, htm_file, full_text_search, rss_litigation, exhibit |
| 10-K / 10-Q sections | company_overview, risk_factors, legal_proceedings, disclosures, segment_revenue, financial_statements |
| Proxy statement (DEF 14A) | executive_compensation, pay_versus_performance, beneficial_ownership, management_profiles |
| Funds | nport_disclosure, nport_fund_metrics |
| Reference & lookups | cik_map, symbol_map, institutions_search, sic_search, schema_files |
The SEC provider also implements standard models — financial statements (balance_sheet, income_statement, cash_flow, and their *_growth), compare_company_facts, equity_search, equity_ftd, insider_trading, form_13f, and management_discussion_analysis.
When openbb-equity / openbb-etf are installed these are reached as obb.equity.* / obb.etf.* with provider="sec"; when they are not, the same models register directly as obb.sec.*.
Basic usage
from openbb import obb
# Resolve identifiers
obb.sec.cik_map(symbol="AAPL")
obb.sec.symbol_map(query="0000320193")
# Filings and full-text search
obb.sec.company_filings(symbol="AAPL", form_type="10-K")
obb.sec.full_text_search(query="climate change", form_type="8-K")
# 10-K / 10-Q content (defaults to the latest filing)
obb.sec.risk_factors(symbol="AAPL")
obb.sec.financial_statements(symbol="AAPL", statement_type="balance")
obb.sec.segment_revenue(symbol="AAPL", calendar_year=2023)
# Proxy statement disclosures
obb.sec.executive_compensation(symbol="CAT")
obb.sec.pay_versus_performance(symbol="CAT")
# Fund holdings (N-PORT) and metrics
obb.sec.nport_disclosure(symbol="VTI")
obb.sec.nport_fund_metrics(symbol="VTI")
OpenBB Workspace
The package ships ready-to-use OpenBB Workspace dashboards (SEC Form 10-K/Q and SEC Filings), a Filing Viewer that re-serves EDGAR documents for in-app rendering, and an MCP server that exposes the open document to the Workspace agent as text.
Launch a self-contained Workspace backend:
openbb-sec serve --host 0.0.0.0 --port 6900
Cache management
The openbb-sec command also inspects and manages the disk cache:
openbb-sec info # resolved cache folder, size limit, and disk usage
openbb-sec path # print the resolved cache folder
openbb-sec clear # empty the cache
The cache folder is resolved from, in order of precedence: the --cache-dir argument, the OPENBB_SEC_CACHE_DIR environment variable, the cache_directory preference from openbb.toml / user settings, then the OpenBB default (~/OpenBBUserData/cache/sec).
| Variable | Purpose | Default |
|---|---|---|
OPENBB_SEC_CACHE_DIR |
SEC cache folder | ~/OpenBBUserData/cache/sec |
OPENBB_SEC_CACHE_SIZE_LIMIT |
Max cache size (bytes or e.g. "8GB") |
8GB |
OPENBB_SEC_REQUESTS_PER_SECOND |
EDGAR request rate | 9 |
OPENBB_SEC_MCP_HOST |
Filing Viewer MCP host | 127.0.0.1 |
OPENBB_SEC_MCP_PORT |
Filing Viewer MCP port | 7769 |
Documentation
Full documentation is available at docs.openbb.co.