Skip to main content

Connect SEC EDGAR

Tasks call SEC EDGAR, the US Securities and Exchange Commission's filing system, through qbash.integrations.sec_edgar. The connector looks up public companies by name, ticker or CIK. It lists a company's filings and reads them as text, pulls the financial figures companies report in XBRL and searches the full text of filings since 2001. Every method is a read.

After you connect SEC EDGAR, you can add its tools to a qbash MCP server for ChatGPT, Claude and other MCP clients, or call it from a Python task.

What the credential holds​

EDGAR is public and has no API keys. SEC's fair access policy asks every automated client to identify itself with a company or person name and a contact email, and SEC refuses requests that leave them out. The credential stores those two values, and qbash sends them with each request. SEC uses the email only to reach you if your requests cause a problem.

Add the credential in qbash​

  1. Open Connectors, then SEC EDGAR, and click Connect.
  2. Enter a company name or your own name, and a contact email.
  3. In the task editor, choose Add connector from the Package + menu and select the credential. See Task resources.

Call SEC EDGAR from a task​

This task finds a company's latest 10-K and logs the start of its text.

filings = qbash.integrations.sec_edgar.list_filings(company="AAPL", form_types=["10-K"], limit=1)
annual = filings["filings"][0]
qbash.log(f'{filings["name"]} filed its 10-K on {annual["filing_date"]}: {annual["url"]}')

page = qbash.integrations.sec_edgar.read_filing_document(url=annual["url"], max_chars=2000)
qbash.log(f'The 10-K runs to {page["total_chars"]} characters.')
qbash.log(page["text"])

Pass next_offset back as offset to read the next window.

company takes a ticker such as AAPL or BRK.B, or a CIK (SEC's company number). search_companies finds either from a name. The SDK Reference lists every method with its parameters and return values.

Read reported financial figures​

get_company_concept returns one XBRL figure across every period a company reported it, newest first. A filing repeats earlier periods for comparison, so each period keeps its latest filed value by default.

revenue = qbash.integrations.sec_edgar.get_company_concept(
    company="MSFT",
    tag="RevenueFromContractWithCustomerExcludingAssessedTax",
    form_types=["10-K"],
)

for fact in revenue["facts"][:5]:
    qbash.log(f'Fiscal year ending {fact["end"]}: ${fact["val"] / 1e9:.1f} billion')

Companies use different tags for the same figure, such as Revenues and RevenueFromContractWithCustomerExcludingAssessedTax. list_company_concepts with search="revenue" shows which ones a company reports.

get_frame compares one figure across every company for a calendar period. period is CY2024 for a year, CY2024Q4 for a quarter, or CY2024Q4I for a balance sheet value at the end of a quarter.

assets = qbash.integrations.sec_edgar.get_frame(tag="Assets", period="CY2024Q4I", limit=10)
for row in assets["values"]:
    qbash.log(f'{row["entity_name"]}: ${row["val"] / 1e9:.0f} billion')

Watch for new filings​

search_filings with no query lists the latest filings first. A scheduled task can run it each morning for the 8-Ks filed the day before.

latest = qbash.integrations.sec_edgar.search_filings(form_types=["8-K"], start_date="2026-11-05", limit=25)

for result in latest["results"]:
    qbash.log(f'{result["file_date"]} {result["companies"][0]}: items {result["items"]}')

Put a phrase in double quotes to search filing text, such as query='"going concern"'.

Add test data​

EDGAR holds every public company's filings, so a new credential reads them at once and needs no setup. Apple (AAPL, CIK 320193) and Microsoft (MSFT, CIK 789019) file 10-Ks, 10-Qs and 8-Ks and are useful to test with.

Details that affect results​

  • SEC allows 10 requests per second, and it blocks an address that goes over for about ten minutes. Every qbash task shares the same servers, so add a short pause between calls in a loop over many companies.
  • read_filing_document returns 40,000 characters at a time by default, and a 10-K runs to 300,000 or more. Each call downloads the document again, so read only the windows you need. Chat tools cap a window at 40,000 characters.
  • list_filings matches form types exactly, so pass 10-K/A to include amendments. In search_filings, 10-K also finds 10-K/A.
  • search_filings counts up to 10,000 matches and returns them 100 at a time. Narrow a broad search with form_types, company or dates.
  • search_companies reads SEC's list of companies with a listed ticker. Funds, private companies and people without a ticker can be found with search_filings or by CIK.
  • XBRL figures come in the units the company reported. Money is in USD, per-share amounts in USD/shares, and share counts in shares.
Last updated on