# `POST /ownership/stats`

**Purpose:** Aggregate statistics over one company and/or one insider, plus the ids of every transaction 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 `transaction_date`; `as_of_date` also excludes filings submitted after it. `as_of_date` ≤ today; `start_date` ≤ `as_of_date`. |
| `transaction_code` | string[] | omitted | ≤ 20 entries. |
| `method` | `"ad"` \| `"ps"` | `"ad"` | `ad` splits on `acquired_disposed_code`. `ps` treats P as a buy and S as a sell, and narrows the scope to those two codes. |
| `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 | |
| `exclude_likely_merged` | bool | `false` | |
| `include_unresolved_amendments` | bool | `false` | |
| `ids_page` | int ≥ 1 | 1 | Paginates `transaction_ids` only. |
| `ids_page_size` | int 1–1000 | 200 | |
| `detail` | string | `"full"` | `"light"` leaves out the `method_applied` and `start_date_applied` echoes. 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`, `method_applied`, `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), `transaction_ids`.

Key names inside `stats` follow `method`: `acquired` / `disposed` for `ad`, `bought` / `sold` for `ps`.

| `stats` field | Meaning |
|---|---|
| `value_acquired`, `value_disposed`, `net_value` | Cash value totals. Transactions with no cash value contribute 0. |
| `shares_acquired`, `shares_disposed`, `net_shares` | Share totals on the split-adjusted basis, excluding rows where `principal_amount_not_shares` is `true`. |
| `avg_price_acquired`, `avg_price_disposed` | Total value ÷ total split-adjusted shares over the transactions that have a cash value, on the same basis as `shares_*`. `null` when there are none. |
| `txn_count`, `txn_count_acquired`, `txn_count_disposed` | Counts. |
| `txn_count_with_value` | Transactions carrying a non-zero cash value. |
| `no_value_txn_count` | Transactions with no cash value. |
| `ad_code_missing_count` | Transactions counted in neither direction. |
| `principal_amount_txn_count` | Debt-principal rows excluded from `shares_*` and `avg_price_*`. |
| `distinct_insiders` | Distinct reporting owners in scope. |
| `filings_with_multiple_filers` | Joint filings in scope. |
| `max_txn_value_acquired`, `max_txn_value_disposed` | Largest single transaction per side. `null` when the side is empty. |
| `avg_value_per_txn_acquired`, `avg_value_per_txn_disposed` | Mean over transactions that have a cash value. |
| `earliest_transaction_date`, `latest_transaction_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 transactions were excluded, skipped, or carry no value.

**Credits:** **40 base**, plus **ceil(n / 1000) × 5** where `n` is the number of participating transactions. 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": "2025-01-01",
  "as_of_date": "2025-12-31",
  "method": "ps"
}
```