# `POST /ownership/initial-holdings/stats`

**Purpose:** Aggregate statistics over the Form 3 filings of one company and/or one insider, plus the ids of every holding that contributed.

**Request:**

| Field | Type | Default | Notes |
|---|---|---|---|
| `ticker` | string | — | |
| `cik` | string | — | The company's CIK, instead of `ticker`. |
| `insider_cik` | string | — | |
| `start_date`, `as_of_date` | ISO date | — | Window on `filing_date`. `as_of_date` ≤ today; `start_date` ≤ `as_of_date`. |
| `include_anomalies` | bool | `false` | |
| `relationship` | string[] | omitted | Any of `is_director`, `is_officer`, `is_ten_percent_owner`, `is_other`. OR semantics, evaluated per filing. |
| `is_derivative` | bool | omitted | Restricts the holding totals; filing counts are unaffected. |
| `exclude_likely_merged` | bool | `false` | |
| `include_unresolved_amendments` | bool | `false` | |
| `ids_page` | int ≥ 1 | 1 | Paginates `holding_ids` only. |
| `ids_page_size` | int 1–1000 | 200 | |
| `detail` | string | `"full"` | `"light"` leaves out the `start_date_applied` echo. See [Response detail](/documents/responses.md#response-detail). |

At least one of `ticker` / `cik` / `insider_cik` is required, and not both `ticker` and `cik`.

**Response:** `stats`, `start_date_applied`, `as_of_date_applied`, `anomalies_excluded_count`, `credits_used`, optional `corporate_actions`, optional `_warnings`, then `ids_page`, `ids_has_more`, `ids_next_page` (`null` on the last page), `holding_ids`.

| `stats` field | Meaning |
|---|---|
| `filing_count` | Form 3 filings in scope. |
| `no_securities_filing_count` | Of those, filings that report no holdings. |
| `distinct_insiders` | Distinct reporting owners in scope. |
| `filings_with_multiple_filers` | Joint filings in scope. |
| `holdings_count`, `holdings_count_non_derivative`, `holdings_count_derivative` | Holding rows in scope. |
| `shares_owned_total` | Sum of `shares_owned` over non-derivative rows, on the split-adjusted basis. |
| `underlying_shares_total` | Sum of `underlying_security_shares` over derivative rows, on the split-adjusted basis. |
| `earliest_filing_date`, `latest_filing_date` | Range actually covered. |
| `corporate_action_crossing` | `true` when the window spans a corporate action. |

`corporate_actions` is present when the request names a company (`ticker` or `cik`) that has corporate actions on file, except with `detail="minimal"`: an array of `{ex_date, ratio, type, event_type}`.

`_warnings` names the count and the parameter that changes it whenever holdings were excluded.

**Credits:** **40 base**, plus **ceil(n / 1000) × 5** where `n` is the number of participating holdings. Both charges are recorded as one usage entry.

**Errors:** `404 OWNERSHIP_COMPANY_NOT_FOUND` (charged), `403 PLAN_TIER_INSUFFICIENT_COVERAGE` when the company is outside your plan's coverage scope (charged), `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`.

**Example Request:**

```json
{
  "ticker": "NVDA",
  "start_date": "2024-01-01"
}
```