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

# SEC Financials As Reported API

> Financial statement line items as reported to the SEC (one row per company, concept and period), with the XBRL concept, label, value and filing. Pass US tickers (SEC filers only), or pick one concept and a period to rank all companies.

`POST /v1/data/sec/financials-as-reported/run`

**Pricing:** $0.0045 per line item ($4.50 per 1,000).

## Ways to call it

* **By ticker**: set `tickers` (optional: `statement`, `concepts`, `periodType`, `periods`, `fromYear`, `maxResults`)
* **All companies**: set `concept` (optional: `year`, `quarter`, `unit`, `maxResults`)

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**tickers** `string[]`

One or more US stock tickers or SEC CIK numbers, e.g. AAPL, MSFT, BRK-B, 320193. SEC data covers US-listed companies only: non-US listings (RELIANCE.NS) and market indices (NIFTY, SENSEX) are refused with a clear error. One request reads them all.

**statement** `string`

A ready-made set of concepts to pull, e.g. Income statement = revenue, costs, operating income, net income and 17 more. Combines with Concepts: you get the set plus any concepts you pick. Left empty: Core, or only your picked Concepts if you pick any. "Only the concepts I pick" needs at least one concept.

Allowed values: `core` (Core (9 headline metrics)), `incomeStatement` (Income statement (21)), `balanceSheet` (Balance sheet (38)), `cashFlow` (Cash flow (16)), `perShare` (Per share, share counts and cover page (10)), `all` (All 85 curated concepts), `custom` (Only the concepts I pick).

**periodType** `string` (default: annual)

Annual (full-year figures) or Quarterly (three-month figures). Balance-sheet items are point-in-time values and come with either. Annual by default.

Allowed values: `annual` (Annual), `quarterly` (Quarterly).

**periods** `integer` (default: 12)

Number of most recent periods to return for each company and concept, e.g. 12 = the last 12 years with Annual, the last 12 quarters with Quarterly. Default 12.

Min `1`; max `200`.

**fromYear** `integer`

Only periods ending in this year or later, e.g. 2020. Leave empty for no lower bound (SEC XBRL data starts around 2009). Applies before Periods.

Min `2008`; max `2100`.

**concepts** `string[]`

A concept is the standard XBRL name for one financial line item, e.g. Revenues, NetIncomeLoss, Assets or EarningsPerShareDiluted. Pick from the 85 curated concepts; through the API any other XBRL tag a company reports also works, e.g. ifrs-full:Revenue or a company's own custom tag. Added on top of Statement.

85 allowed values, for example `Revenues` (Revenue (Revenues)), `RevenueFromContractWithCustomerExcludingAssessedTax` (Revenue from contracts with customers (RevenueFromContractWithCustomerExcludingAssessedTax)), `SalesRevenueNet` (Net sales, pre-2018 tag (SalesRevenueNet)), `RevenuesNetOfInterestExpense` (Revenue net of interest expense (banks) (RevenuesNetOfInterestExpense)), `CostOfRevenue` (Cost of revenue (CostOfRevenue)), `CostOfGoodsAndServicesSold` (Cost of goods and services sold (CostOfGoodsAndServicesSold)), `GrossProfit` (Gross profit (GrossProfit)), `OperatingExpenses` (Operating expenses, total (OperatingExpenses)), `ResearchAndDevelopmentExpense` (Research and development expense (ResearchAndDevelopmentExpense)), `SellingGeneralAndAdministrativeExpense` (Selling, general and administrative expense (SellingGeneralAndAdministrativeExpense)). Fetch the full list with `GET /v1/data/sec/financials-as-reported?expand=options`.

**concept** `string`

All companies mode: the one line item to rank every SEC filer by, e.g. Revenues, NetIncomeLoss or Assets. Pick from the 85 curated concepts; through the API any other us-gaap or dei concept name also works. A concept SEC has no figures for returns no rows.

85 allowed values, for example `Revenues` (Revenue (Revenues)), `RevenueFromContractWithCustomerExcludingAssessedTax` (Revenue from contracts with customers (RevenueFromContractWithCustomerExcludingAssessedTax)), `SalesRevenueNet` (Net sales, pre-2018 tag (SalesRevenueNet)), `RevenuesNetOfInterestExpense` (Revenue net of interest expense (banks) (RevenuesNetOfInterestExpense)), `CostOfRevenue` (Cost of revenue (CostOfRevenue)), `CostOfGoodsAndServicesSold` (Cost of goods and services sold (CostOfGoodsAndServicesSold)), `GrossProfit` (Gross profit (GrossProfit)), `OperatingExpenses` (Operating expenses, total (OperatingExpenses)), `ResearchAndDevelopmentExpense` (Research and development expense (ResearchAndDevelopmentExpense)), `SellingGeneralAndAdministrativeExpense` (Selling, general and administrative expense (SellingGeneralAndAdministrativeExpense)). Fetch the full list with `GET /v1/data/sec/financials-as-reported?expand=options`.

**year** `integer`

All companies mode: the calendar year, e.g. 2023. SEC lines each company's fiscal year up with the closest calendar year. Left empty: the latest full calendar year.

Min `2009`; max `2100`.

**quarter** `string` (default: full)

All companies mode: the whole year or one calendar quarter. Balance-sheet items and share counts are read as of the period end (for Full year, Dec 31). Full year by default.

Allowed values: `full` (Full year), `Q1` (Q1 (Jan to Mar)), `Q2` (Q2 (Apr to Jun)), `Q3` (Q3 (Jul to Sep)), `Q4` (Q4 (Oct to Dec)).

**unit** `string`

All companies mode: the unit the values are reported in. Left empty: USD, or USD per share for EPS and dividends per share, or shares for share counts. Companies that report in another unit are not included.

Allowed values: `USD`, `USD/shares` (USD per share), `shares` (Shares), `EUR`, `pure` (Pure number).

**maxResults** `integer` (default: 50)

How many rows to return in total. Defaults to 50; use 0 for all with Tickers. All companies returns the largest companies first, up to 1000 per run (0 is not allowed there).

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/sec/financials-as-reported/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "tickers": [
      "AAPL",
      "MSFT",
      "BRK-B"
    ],
    "statement": "custom",
    "periods": 1,
    "concepts": [
      "RevenueFromContractWithCustomerExcludingAssessedTax",
      "Revenues",
      "NetIncomeLoss"
    ]
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/sec/financials-as-reported/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "tickers": [
        "AAPL",
        "MSFT",
        "BRK-B"
    ],
    "statement": "custom",
    "periods": 1,
    "concepts": [
        "RevenueFromContractWithCustomerExcludingAssessedTax",
        "Revenues",
        "NetIncomeLoss"
    ]
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/sec/financials-as-reported/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "tickers": [
    "AAPL",
    "MSFT",
    "BRK-B"
  ],
  "statement": "custom",
  "periods": 1,
  "concepts": [
    "RevenueFromContractWithCustomerExcludingAssessedTax",
    "Revenues",
    "NetIncomeLoss"
  ]
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one line item, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `factId` | Fact ID | text |
| `ticker` | Ticker | text |
| `cik` | Cik | text |
| `companyName` | Company Name | text |
| `statement` | Statement | text |
| `concept` | Concept | text |
| `label` | Label | text |
| `taxonomy` | Taxonomy | text |
| `value` | Value | number |
| `unit` | Unit | text |
| `periodStart` | Period Start | date |
| `periodEnd` | Period End | date |
| `durationDays` | Duration Days | number |
| `periodType` | Period Type | text |
| `fiscalYear` | Fiscal Year | number |
| `fiscalPeriod` | Fiscal Period | text |
| `form` | Form | text |
| `filedDate` | Filed Date | date |
| `accessionNumber` | Accession Number | text |
| `frame` | Frame | text |
| `filingUrl` | Filing URL | url |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "sec/financials-as-reported",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "fiscalYear": 2025,
      "durationDays": 363,
      "taxonomy": "us-gaap",
      "companyName": "Apple Inc.",
      "value": 416161000000,
      "fiscalPeriod": "FY",
      "periodType": "annual",
      "accessionNumber": "0000320193-25-000079",
      "statement": "incomeStatement",
      "filingUrl": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm",
      "frame": "CY2025",
      "label": "Revenue from Contract with Customer, Excluding Assessed Tax",
      "filedDate": "2025-10-31",
      "periodStart": "2024-09-29",
      "unit": "USD",
      "form": "10-K",
      "ticker": "AAPL",
      "factId": "0000320193:us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax:USD:2024-09-29:2025-09-27",
      "concept": "RevenueFromContractWithCustomerExcludingAssessedTax",
      "cik": "0000320193",
      "periodEnd": "2025-09-27"
    }
  ]
}
```

## Related APIs

For the cash flow statement laid out by period use [`sec/cashflow-as-reported`](https://docs.mindcase.co/apis/sec/cashflow-as-reported); for headline KPIs and guidance from earnings releases use [`sec/kpi-guidance`](https://docs.mindcase.co/apis/sec/kpi-guidance); for non-US tickers use [`yahoo-finance/income-statements`](https://docs.mindcase.co/apis/yahoo-finance/income-statements).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.