# 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.

**Pricing:** $0.0045 per line item

**Endpoint:** `POST /v1/data/sec/financials-as-reported/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tickers` | array | No | 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 | No | 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. |
| `periodType` | string | No | Annual (full-year figures) or Quarterly (three-month figures). Balance-sheet items are point-in-time values and come with either. Annual by default. |
| `periods` | integer | No | 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. |
| `fromYear` | integer | No | 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. |
| `concepts` | array | No | 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. |
| `concept` | string | No | 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. |
| `year` | integer | No | 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. |
| `quarter` | string | No | 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. |
| `unit` | string | No | 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. |
| `maxResults` | integer | No | 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

`?wait=true` holds the request open until the run finishes (up to 60s) and returns the rows inline: one request, no polling.

```bash
curl -X POST "https://api.mindcase.co/v1/data/sec/financials-as-reported/run?wait=true" \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/v1/data/sec/financials-as-reported/run",
    params={"wait": "true"},
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {}},
)
rows = resp.json()["data"]
```

## Longer runs

If the run is still going at the 60s ceiling you get back `{ job_id, status: "running" }` instead of rows (same if the result is over 100 rows; those come back `truncated`). Poll with that `job_id`:

```bash
# 1) check status
curl https://api.mindcase.co/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display 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 |