> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.b3os.org/llms.txt
> Use this file to discover all available pages before exploring further.

# SEC EDGAR

The io.b3os/sec-edgar pack: 4 actions with call snippets, fixture outputs, connection setup and error codes, generated from version 1.0.0.

`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](/actions/call)). 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](https://www.sec.gov/os/accessing-edgar-data).

Connection params (no secret): `user_agent`.

Store the credential once as a [vault connection](/vault) 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](/actions/call#connections)).

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

## Actions

| Action | Effect | MCP tool | Title |
|---|---|---|---|
| [`search-companies`](/actions/catalog/sec-edgar#sec-edgar-search-companies) | read | `sec-edgar__search-companies` | Search companies |
| [`get-company`](/actions/catalog/sec-edgar#sec-edgar-get-company) | read | `sec-edgar__get-company` | Get company and recent filings |
| [`search-filings`](/actions/catalog/sec-edgar#sec-edgar-search-filings) | read | `sec-edgar__search-filings` | Full-text search filings |
| [`get-concept`](/actions/catalog/sec-edgar#sec-edgar-get-concept) | read | `sec-edgar__get-concept` | Get XBRL financial facts |

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`

**curl**

```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"}
        }'
    ```
  **TypeScript**

```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**

```python
    from b3os import B3OS

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

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

    Expose the pack as tools with `--packs sec-edgar` on the local server or `?packs=sec-edgar` on the remote URL, and the agent calls `sec-edgar__search-companies` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

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`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `not_found` | 404 | no | No such company, filing or XBRL concept at the SEC. |
| `forbidden` | 403 | no | The SEC refused the request: check that the connection's User-Agent names you and an email address, and stay under 10 requests per second. |
| `rate_limited` | 429 | yes | The SEC is rate limiting this address (more than 10 requests per second). |

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`

**curl**

```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"}
        }'
    ```
  **TypeScript**

```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**

```python
    from b3os import B3OS

    b3os = 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"])
    ```
  **MCP**

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

    Expose the pack as tools with `--packs sec-edgar` on the local server or `?packs=sec-edgar` on the remote URL, and the agent calls `sec-edgar__get-company` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

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`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `not_found` | 404 | no | No such company, filing or XBRL concept at the SEC. |
| `forbidden` | 403 | no | The SEC refused the request: check that the connection's User-Agent names you and an email address, and stay under 10 requests per second. |
| `rate_limited` | 429 | yes | The SEC is rate limiting this address (more than 10 requests per second). |

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`

**curl**

```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"}
        }'
    ```
  **TypeScript**

```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**

```python
    from b3os import B3OS

    b3os = 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"])
    ```
  **MCP**

```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"
        }
      }
    }
    ```

    Expose the pack as tools with `--packs sec-edgar` on the local server or `?packs=sec-edgar` on the remote URL, and the agent calls `sec-edgar__search-filings` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

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`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `not_found` | 404 | no | No such company, filing or XBRL concept at the SEC. |
| `forbidden` | 403 | no | The SEC refused the request: check that the connection's User-Agent names you and an email address, and stay under 10 requests per second. |
| `rate_limited` | 429 | yes | The SEC is rate limiting this address (more than 10 requests per second). |

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`

**curl**

```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"}
        }'
    ```
  **TypeScript**

```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**

```python
    from b3os import B3OS

    b3os = 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"])
    ```
  **MCP**

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

    Expose the pack as tools with `--packs sec-edgar` on the local server or `?packs=sec-edgar` on the remote URL, and the agent calls `sec-edgar__get-concept` with the action's input. The tool uses your newest connection for each key without a `subject`. Without exposing the pack, `actions_call` takes the same input with `ref`.

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`](/errors#upstream_error) and `pack_error.code` is one of:

| `pack_error.code` | Service status | Retryable | Message |
|---|---|---|---|
| `not_found` | 404 | no | No such company, filing or XBRL concept at the SEC. |
| `forbidden` | 403 | no | The SEC refused the request: check that the connection's User-Agent names you and an email address, and stay under 10 requests per second. |
| `rate_limited` | 429 | yes | The SEC is rate limiting this address (more than 10 requests per second). |