> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinyellowbrick.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters

> Search filter fields, enums, defaults, and how constraints combine.

`POST /api/v1/search` accepts a `filter` object with the **same fields as the in-app search**. Omitted fields use product defaults. Every active constraint is **AND**'d.

Pagination lives in `pagination` (`cursor`, `pageSize`), not inside `filter`.

## Defaults

| Field | Default |
| - | - |
| `excludeAnomalousTransactions` | `true` |
| `filingDatePreset` | `"All time"` |
| `insiderReturnPeriod` | `"3M"` |
| `insiderReturnType` | `"all"` |
| `sortBy` | `"filedAt"` |
| `sortDirection` | `"desc"` |
| Booleans (`exclude*`, `only*`, position flags) | `false` |
| Strings (`cikOrTicker`, amounts, …) | `""` (no constraint) |

## How filters combine

* Each set field adds one SQL condition.
* Position flags that are `true` must **all** match (AND).
* Empty string, `false`, `"all"`, and `"All time"` generally mean “no constraint” for that field.
* Return min/max only apply when the matching period is set and at least one bound is non-empty.

## Company

| Field | Type | Notes |
| - | - | - |
| `cikOrTicker` | string | Digits → issuer CIK. Alphanumeric → ticker (case-insensitive). Without an explicit filing-date range, search auto-bounds to that issuer’s filing history. |
| `sector` | string | Sector slug, CapIQ simple industry id, `""`, or `"all"`. |
| `marketCapMin` / `marketCapMax` | string | Human amounts (`250m`, `500k`). Compared to market cap at filing in **millions**. |

### Sector slugs

| Slug | Meaning |
| - | - |
| `biotech` | Biotechnology |
| `consumer` | Consumer |
| `energy` | Energy & Utilities |
| `financials` | Financials |
| `healthcare` | Health Care |
| `industrials` | Industrials |
| `materials` | Materials |
| `realestate` | Real Estate |
| `technology` | Technology, Media, and Telecommunications |

You can also pass a CapIQ **simple industry numeric id** as a string (same as Feeds `sector`).

## Insider

| Field | Type | Notes |
| - | - | - |
| `reportingOwnerCik` | string | Exact reporting-owner CIK. Resolve a name with [Insiders → Search](/api-reference/insiders/search) or the [Insiders](/ceowatcher-api/insiders) guide. |
| `position.officer` | boolean | Require officer. |
| `position.director` | boolean | Require director. |
| `position.owner` | boolean | Require 10% owner. |
| `position.ceo` / `cfo` / `cto` / `coo` | boolean | Require that title flag. |
| `insiderReturnPeriod` | enum | `1D`, `1W`, `1M`, `3M`, `6M`, `1Y`, `2Y`, `AllTime`. `AllTime` / `1D` currently fall back to the 3M series. |
| `insiderReturnType` | enum | `all`, `bullish`, `bearish`. |
| `insiderReturnMin` / `Max` | string | Percent strings. Need period + at least one bound. |

## Trade

| Field | Type | Notes |
| - | - | - |
| `tradeType` | enum | `""` / `all` = none; `purchase` → acquired (`A`); `sale` → disposed (`D`). |
| `tradeReturnPeriod` | enum | `""`, `1W`, `1M`, `3M`, `6M`, `1Y`, `2Y`, `latest`. Empty disables return filtering. |
| `tradeReturnMin` / `Max` | string | Forward return percent. Need period + at least one bound. |
| `purchaseMin` / `Max` | string | Transaction value in USD. |
| `percentChangeMin` / `Max` | string | Holdings change entered as **percent** (e.g. `10` for 10%); divided by 100 before compare. |

### Exclude / only flags

| Field | Default | Effect |
| - | - | - |
| `excludeEspp` | `false` | Drop ESPP trades. |
| `exclude10b51` | `false` | Drop Rule 10b5-1 trades. |
| `excludeTaxRelated` | `false` | Drop tax-related trades. |
| `excludePublicOffering` | `false` | Drop public offerings. |
| `excludeDividendReinvestment` | `false` | Drop dividend reinvestment. |
| `excludeDerivative` | `false` | Drop derivatives. |
| `excludeAnomalousTransactions` | `true` | Drop anomalous trades and extreme price/value outliers. |
| `excludeLowSignalTransactions` | `false` | Keep only high-signal trades. |
| `onlyMarketTransactions` | `false` | Require positive `price_per_share`. |
| `onlyNewPositions` | `false` | Shares after = shares in this trade. |
| `onlyClusterTrades` | `false` | 90-day cluster only. |
| `onlyReversal` | `false` | Reversals only. |
| `onlyBuyingDip` | `false` | Buying-the-dip only. |
| `onlySellingRip` | `false` | Selling-the-rip only. |

## Filing date and sort

| Field | Type | Notes |
| - | - | - |
| `filingDatePreset` | enum | `Today`, `3 days`, `7 days`, `1 month`, `3 months`, `6 months`, `1 year`, `2 years`, `5 years`, `10 years`, `All time`, `custom`. |
| `filingDateFrom` / `To` | string \| null | Inclusive `YYYY-MM-DD` in Eastern Time. Use with `custom` or to refine a preset. |
| `accessionNumber` | string | Exact SEC accession. |
| `sortBy` | enum | `filedAt`, `insiderReturn`, `tradeReturn`, `percentChange` (absolute), `transactionValue`. |
| `sortDirection` | enum | `asc`, `desc`. |

## Example

CEO purchases in technology, last year, excluding ESPP, sorted by value:

```json theme={null}
{
  "filter": {
    "sector": "technology",
    "tradeType": "purchase",
    "position": { "ceo": true },
    "filingDatePreset": "1 year",
    "excludeEspp": true,
    "excludeAnomalousTransactions": true,
    "sortBy": "transactionValue",
    "sortDirection": "desc"
  },
  "pagination": { "cursor": null, "pageSize": 50 }
}
```

## Response shape

Search rows are **camelCase** (see the OpenAPI `Search` response schema). Transaction detail from Feeds hydration is **snake\_case**.

Not part of the public filter schema: in-app-only fields such as `issuerCik`, `tradingItemId`, and filter-level `pageSize` / `cursor` (use `pagination` instead).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.