SEC EDGAR

io.b3os/sec-edgar 1.0.0 · finance, filings, open-data · MIT

US public company filings from the SEC's EDGAR system (no key): find a company's CIK by name or ticker, read its profile and latest filings, full-text search filings by phrase, form type, company and date, and read reported XBRL financial facts (revenue, net income, assets, shares, ...) across periods. The connection only holds the User-Agent the SEC asks for (your name and email).

Every call's result carries upstream_status and timing: validate_ms, inject_ms, render_ms, upstream_ms, map_ms and total_ms. upstream is the service's time; the others are B3OS's own (call actions). The snippets below show no timing values, because a fixture records none.

Connection

sec, type none: SEC EDGAR identity.

The SEC's fair access policy asks automated clients to send a User-Agent with a company or person name and a contact email, for example "Acme Research ops@acme.example", and to stay under 10 requests per second.

How to get one: www.sec.gov.

Connection params (no secret): user_agent.

Store the credential once as a vault connection for this pack and key, then name its id in a call's connections. Leave the key out and B3OS uses the project's newest connection for the pack and key without a subject (connections).

Hosts it reaches: efts.sec.gov, data.sec.gov.

Actions

search-companies

Search companies. Companies, funds and people that file with the SEC, matched by name or ticker as you type (for example apple or AAPL), best match first, with CIK and tickers.

Ref io.b3os/sec-edgar/search-companies@1.0.0 · effect read · connection sec · MCP tool sec-edgar__search-companies

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/sec-edgar/search-companies@1",      "input": {"query": "apple"},      "connections": {"sec": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/sec-edgar/search-companies@1",  input: { query: "apple" },  connections: { sec: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },});console.log(result.output);

python
from b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/sec-edgar/search-companies@1",    "input": {"query": "apple"},    "connections": {"sec": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},})print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "sec-edgar__search-companies",    "arguments": {"query": "apple"}  }}

Output, labeled fixture: Search companies (response recorded 2026-10-26). From the bundle's fixtures/search-companies.json, not a live call.

json
{  "total": 230,  "companies": [    {"cik": 320193, "name": "Apple Inc. (AAPL)", "tickers": "AAPL"},    {      "cik": 1134982,      "name": "Apple iSports Group, Inc. (AAPI)",      "tickers": "AAPI"    },    {      "cik": 1418121,      "name": "Apple Hospitality REIT, Inc. (APLE)",      "tickers": "APLE"    },    {"cik": 1215379, "name": "APPLE JIM B", "tickers": null}  ]}

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

get-company

Get company and recent filings. A filer's profile (name, tickers, exchanges, industry SIC code, filer category, fiscal year end, state of incorporation, business address, former names) and its most recent filings, newest first, with form type, dates, primary document and a link to the filing index.

Ref io.b3os/sec-edgar/get-company@1.0.0 · effect read · connection sec · MCP tool sec-edgar__get-company

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/sec-edgar/get-company@1",      "input": {"cik": 320193, "limit": 4},      "connections": {"sec": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/sec-edgar/get-company@1",  input: { cik: 320193, limit: 4 },  connections: { sec: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },});console.log(result.output);

python
from b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/sec-edgar/get-company@1",    "input": {"cik": 320193, "limit": 4},    "connections": {"sec": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},})print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "sec-edgar__get-company",    "arguments": {"cik": 320193, "limit": 4}  }}

Output, labeled fixture: Get company and recent filings (response recorded 2026-10-26). From the bundle's fixtures/get-company.json, not a live call.

json
{  "cik": 320193,  "name": "Apple Inc.",  "tickers": ["AAPL"],  "exchanges": ["Nasdaq"],  "sic": "3571",  "sic_description": "Electronic Computers",  "entity_type": "operating",  "category": "Large accelerated filer",  "fiscal_year_end": "0926",  "state_of_incorporation": "CA",  "website": null,  "business_address": "ONE APPLE PARK WAY, CUPERTINO, CA 95014",  "former_names": ["APPLE INC", "APPLE COMPUTER INC"],  "recent_filings": [    {      "accession_number": "0001140361-26-040540",      "form": "4",      "filing_date": "2026-10-22",      "report_date": "2026-10-20",      "primary_document": "xslF345X06/form4.xml",      "description": "FORM 4",      "index_url": "https://www.sec.gov/Archives/edgar/data/320193/0001140361-26-040540-index.htm"    },    {      "accession_number": "0001140361-26-040127",      "form": "4",      "filing_date": "2026-10-19",      "report_date": "2026-10-15",      "primary_document": "xslF345X06/form4.xml",      "description": "FORM 4",      "index_url": "https://www.sec.gov/Archives/edgar/data/320193/0001140361-26-040127-index.htm"    },    {      "accession_number": "0001140361-26-040126",      "form": "4",      "filing_date": "2026-10-19",      "report_date": "2026-10-15",      "primary_document": "xslF345X06/form4.xml",      "description": "FORM 4",

The first 40 of 53 lines; the fixture file has the rest.

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

search-filings

Full-text search filings. EDGAR full-text search over filings since 2001: an exact phrase in quotes or words, optionally only some form types (10-K, 10-Q, 8-K, S-1, DEF 14A, ...), companies (CIKs) and a filing date range. Without a query it lists a company's filings of a form, newest first. 100 hits per page; page with from.

Ref io.b3os/sec-edgar/search-filings@1.0.0 · effect read · connection sec · MCP tool sec-edgar__search-filings

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/sec-edgar/search-filings@1",      "input": {        "query": "\"supply chain\"",        "forms": ["10-K"],        "start_date": "2026-01-01",        "end_date": "2026-10-01"      },      "connections": {"sec": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/sec-edgar/search-filings@1",  input: {    query: "\"supply chain\"",    forms: ["10-K"],    start_date: "2026-01-01",    end_date: "2026-10-01",  },  connections: { sec: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },});console.log(result.output);

python
from b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/sec-edgar/search-filings@1",    "input": {        "query": "\"supply chain\"",        "forms": ["10-K"],        "start_date": "2026-01-01",        "end_date": "2026-10-01",    },    "connections": {"sec": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},})print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "sec-edgar__search-filings",    "arguments": {      "query": "\"supply chain\"",      "forms": ["10-K"],      "start_date": "2026-01-01",      "end_date": "2026-10-01"    }  }}

Output, labeled fixture: Full-text search filings (response recorded 2026-10-26). From the bundle's fixtures/search-filings.json, not a live call.

json
{  "total": 4375,  "total_is_lower_bound": false,  "hits": [    {      "accession_number": "0001193125-26-082824",      "form": "10-K",      "file_date": "2026-02-27",      "period_ending": "2025-12-31",      "companies": ["Yum China Holdings, Inc.  (YUMC)  (CIK 0001673358)"],      "ciks": ["0001673358"],      "document": "0001193125-26-082824:yumc-ex21_1.htm",      "file_type": "EX-21.1",      "file_description": "EX-21.1",      "index_url": "https://www.sec.gov/Archives/edgar/data/1673358/0001193125-26-082824-index.htm"    },    {      "accession_number": "0001193125-26-062321",      "form": "10-K",      "file_date": "2026-02-23",      "period_ending": "2025-12-28",      "companies": ["DOMINOS PIZZA INC  (DPZ)  (CIK 0001286681)"],      "ciks": ["0001286681"],      "document": "0001193125-26-062321:dpz-20251228.htm",      "file_type": "10-K",      "file_description": "10-K",      "index_url": "https://www.sec.gov/Archives/edgar/data/1286681/0001193125-26-062321-index.htm"    },    {      "accession_number": "0001193125-26-037138",      "form": "10-K",      "file_date": "2026-02-04",      "period_ending": "2025-12-31",      "companies": ["MANHATTAN ASSOCIATES INC  (MANH)  (CIK 0001056696)"],      "ciks": ["0001056696"],      "document": "0001193125-26-037138:manh-20251231.htm",      "file_type": "10-K",      "file_description": "10-K",      "index_url": "https://www.sec.gov/Archives/edgar/data/1056696/0001193125-26-037138-index.htm"    }

The first 40 of 42 lines; the fixture file has the rest.

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of:

get-concept

Get XBRL financial facts. Every value a company reported for one XBRL concept, newest first: for example us-gaap Revenues, RevenueFromContractWithCustomerExcludingAssessedTax, NetIncomeLoss, Assets or EarningsPerShareDiluted, or dei EntityCommonStockSharesOutstanding. Each fact has its period, value, fiscal year and period, form and filing date; the same period appears again when later filings repeat it.

Ref io.b3os/sec-edgar/get-concept@1.0.0 · effect read · connection sec · MCP tool sec-edgar__get-concept

bash
curl -s https://beta-api.b3os.org/v1/actions/call \  -H "Authorization: Bearer $B3OS_API_KEY" \  -H "Content-Type: application/json" \  -d '{      "ref": "io.b3os/sec-edgar/get-concept@1",      "input": {        "cik": 320193,        "tag": "RevenueFromContractWithCustomerExcludingAssessedTax",        "limit": 3      },      "connections": {"sec": "conn_01m5t6cbgdjs1ketgcqwa2sne8"}    }'

ts
import { B3OS } from "@b3os/sdk";const b3os = new B3OS();const result = await b3os.actions.call({  ref: "io.b3os/sec-edgar/get-concept@1",  input: {    cik: 320193,    tag: "RevenueFromContractWithCustomerExcludingAssessedTax",    limit: 3,  },  connections: { sec: "conn_01m5t6cbgdjs1ketgcqwa2sne8" },});console.log(result.output);

python
from b3os import B3OSb3os = B3OS()result = b3os.actions.call({    "ref": "io.b3os/sec-edgar/get-concept@1",    "input": {        "cik": 320193,        "tag": "RevenueFromContractWithCustomerExcludingAssessedTax",        "limit": 3,    },    "connections": {"sec": "conn_01m5t6cbgdjs1ketgcqwa2sne8"},})print(result["output"])

json
{  "method": "tools/call",  "params": {    "name": "sec-edgar__get-concept",    "arguments": {      "cik": 320193,      "tag": "RevenueFromContractWithCustomerExcludingAssessedTax",      "limit": 3    }  }}

Output, labeled fixture: Get XBRL financial facts (response recorded 2026-10-26). From the bundle's fixtures/get-concept.json, not a live call.

json
{  "cik": 320193,  "entity_name": "Apple Inc.",  "tag": "RevenueFromContractWithCustomerExcludingAssessedTax",  "label": "Revenue from Contract with Customer, Excluding Assessed Tax",  "description": "Amount, excluding tax collected from customer, of revenue from satisfaction of performance obligation by transferring promised good or service to customer. Tax collected from customer is tax assessed by governmental authority that is both imposed on and concurrent with specific revenue-producing transaction, including, but not limited to, sales, use, value added and excise.",  "unit": "USD",  "facts": [    {      "start": "2017-12-31",      "end": "2018-03-31",      "value": 61137000000,      "fiscal_year": 2019,      "fiscal_period": "Q2",      "form": "10-Q",      "filed": "2019-05-01",      "frame": null,      "accession_number": "0000320193-19-000066"    },    {      "start": "2017-10-01",      "end": "2018-03-31",      "value": 149430000000,      "fiscal_year": 2019,      "fiscal_period": "Q2",      "form": "10-Q",      "filed": "2019-05-01",      "frame": null,      "accession_number": "0000320193-19-000066"    },    {      "start": "2017-10-01",      "end": "2017-12-30",      "value": 88293000000,      "fiscal_year": 2019,      "fiscal_period": "FY",      "form": "10-K",      "filed": "2019-10-31",      "frame": "CY2017Q4",      "accession_number": "0000320193-19-000119"

The first 40 of 43 lines; the fixture file has the rest.

When the service answers with an error, the call fails with upstream_error and pack_error.code is one of: