# `POST /screener/initial-holdings`

**Purpose:** Full-library screening of initial holdings (Form 3). Holding-level conditions plus company-level aggregate gates; returns the matching holdings. Requires **Pro or higher**.

**Request:**

| Field | Type | Default | Notes |
|---|---|---|---|
| `start_date`, `as_of_date` | ISO date | — | Window on `filing_date`. `as_of_date` ≤ today; `start_date` ≤ `as_of_date`. |
| `tickers`, `exclude_tickers` | string[] | omitted | ≤ 100 each. |
| `sectors` | string[] | omitted | The 12 canonical buckets ([Industry classification (Pro+)](/documents/coverage.md#industry-classification-pro)). |
| `holding_filters` | object | omitted | See below. |
| `aggregate_filters` | object[] | omitted | ≤ 8. Company-level gates — see below. |
| `group_by_ticker` | bool | `true` | `true` → grouped by company. `false` → flat rows. |
| `sort_by` | string | — | Grouped: `ticker`, `holdings_count`, `shares_owned_total`. Flat: `filing_date`, `shares_owned`, `split_adjusted_shares_owned`, `underlying_security_shares`, `conversion_or_exercise_price`. |
| `sort_order` | `"desc"` \| `"asc"` | `"desc"` | |
| `page` | int ≥ 1 | 1 | |
| `page_size` | int 1–100 | 50 | Counts holdings in both modes: with `group_by_ticker=true` a page holds that many holdings, however few companies they come from. |
| `detail` | string | `"full"` | `"light"` leaves out each row's `footnote_refs` and the `start_date_applied` echo; `"minimal"` also leaves out `accession_number` and `company_id`. See [Response detail](/documents/responses.md#response-detail). |

**Pagination cap:** `page × page_size ≤ 500` (422 above it). When the next page would pass the cap, `has_more` is `false`, `next_page` is `null`, and `_warnings` says the limit was reached.

**`holding_filters`:**

| Field | Type | Notes |
|---|---|---|
| `relationship` | string[] | `is_director`, `is_officer`, `is_ten_percent_owner`, `is_other`. OR semantics. |
| `is_derivative` | bool | |
| `direct_or_indirect` | `"D"` \| `"I"` | |
| `include_anomalies` | bool | Default `false`. |
| `exclude_likely_merged` | bool | Default `false`. |
| `include_unresolved_amendments` | bool | Default `false`. |
| `conditions` | object[] | ≤ 8. `{field, op, value}`. `field` ∈ `shares_owned`, `split_adjusted_shares_owned`, `underlying_security_shares`, `split_adjusted_underlying_security_shares`, `conversion_or_exercise_price`. |

**`aggregate_filters`:** `{metric, op, value}`, `metric` ∈ `filing_count`, `no_securities_filing_count`, `distinct_insiders`, `holdings_count`, `shares_owned_total`. `filing_count` and `no_securities_filing_count` count filings, including filings that report no holdings; `holdings_count` and `shares_owned_total` are measured on the matching holdings.

**Operators** (both filter types): `>`, `>=`, `<`, `<=`, `between` (`[lo, hi]`, `lo ≤ hi`).

**Response:**

| Field | Meaning |
|---|---|
| `page`, `page_size`, `has_more`, `next_page` | Pagination. |
| `as_of_date_applied`, `start_date_applied` | Window actually used. |
| `results` | `group_by_ticker=true`. Each entry: `ticker`, `issuer`, `issuer_cik`, `holdings_count` and `shares_owned_total` (the company's full hit values), `holdings`. |
| `holdings` | `group_by_ticker=false`. Flat rows, each additionally carrying `ticker`, `issuer`, `issuer_cik` and `company_id`. |
| `anomalies_excluded_count` | Holdings excluded by the consistency checks; `0` when `holding_filters.include_anomalies=true`. |
| `credits_used`, `_warnings` | |

Every row carries `accession_number`, `filing_date`, `period_of_report`, `no_securities_owned`, `source_url_prefix`, `insiders`, and the [holding object](/documents/holding-object.md).

**Credits:** the [Credit formula (`/screener/ownership`)](/documents/post-screenerownership.md#credit-formula-screenerownership) formula, with `conditions` = holding conditions + aggregate filters. Range **65–920**.

**Errors:** `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`, `403 PLAN_TIER_INSUFFICIENT` below Pro, `504 QUERY_TIMEOUT` at the 30-second server timeout (charged).

**Example Request:**

```json
{
  "start_date": "2026-07-01",
  "as_of_date": "2026-09-30",
  "holding_filters": {
    "relationship": ["is_director"],
    "is_derivative": false
  },
  "group_by_ticker": false,
  "sort_by": "shares_owned",
  "page_size": 20
}
```