# `POST /ownership/institutional-holdings/security`

**Purpose:** One security's holder rows across managers — who holds it, quarter by quarter. Flat mode returns [institutional holding objects](/documents/institutional-holding-object.md) with `manager_cik` / `manager_name` and `source_urls` (`{accession, url}` for each filing the row cites; `url` may be `null`) on each row; `group_by_quarter=true` switches to one aggregate row per quarter.

**Request:**

| Field | Type | Default | Notes |
|---|---|---|---|
| `cusip` | string | — | 9 characters. Provide exactly one of `cusip` / `ticker`. |
| `ticker` | string | — | Uppercased automatically; any symbol the company has traded under. A ticker can match several CUSIPs; rows for all of them are included, `securities` lists each one, and a `_warnings` entry says how many matched. |
| `quarter` | string | omitted | `YYYYQn`. Omitted = every quarter, newest first. |
| `type` | string | omitted | As in [`POST /ownership/institutional-holdings/portfolio`](/documents/post-ownershipinstitutional-holdingsportfolio.md). |
| `activity` | string[] | omitted | As in [`POST /ownership/institutional-holdings/portfolio`](/documents/post-ownershipinstitutional-holdingsportfolio.md). |
| `group_by_quarter` | bool | `false` | `true` → one aggregate row per quarter (`period`, `holders`, `total_shares`, `total_value`, computed over live stock rows), unpaged; `type` / `activity` / `sort_by` / `page` are ignored with a warning. |
| `sort_by` | string | omitted | `period`, `d_shares`, `ticker`, `issuer_norm`, `type`, `shares`, `value`. Omitted = newest quarter first. |
| `sort_order` | `"desc"` \| `"asc"` | `"desc"` | |
| `page` | int ≥ 1 | 1 | |
| `page_size` | int 1–100 | 50 | |
| `detail` | string | `"full"` | `"light"` leaves out each holding's `submgr_breakdown` and the `types` and `group_by_quarter` echoes. With `sort_by` `issuer_norm` in flat mode, `"minimal"` returns the light view. See [Response detail](/documents/responses.md#response-detail). |

**Response:** `securities` — one entry per matched CUSIP: `cusip`, `ticker`, `current_ticker`, `ticker_status`, `issuer_norm`, `security_type`, `first_seen` / `last_seen` (first / latest quarter end the security appears in), `latest_holders` (holder count at `last_seen`); then `group_by_quarter`, `credits_used`, and either the flat fields (`types`, `transactions`, `page`, `page_size`, `total_items`, `has_more`, `next_page`) or the grouped ones (`transactions`, `total_items`, unpaged).

**Credits:** **30 per page** (flat mode); **40 flat** (`group_by_quarter=true`, unpaged).

**Errors:** `404 OWNERSHIP_SECURITY_NOT_FOUND` (charged), `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`.

**Example Request:**

```json
{
  "ticker": "AAPL",
  "quarter": "2026Q2",
  "type": "positions",
  "sort_by": "shares",
  "page_size": 20
}
```