Filters

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 or the 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:

{
  "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).

Getting started

Guides

Authors

Yellowbrick API

Yellowbrick API reference

CEO Watcher API

CEO Watcher API reference

Defaults

How filters combine

Company

Sector slugs

Insider

Trade

Exclude / only flags

Filing date and sort

Example

Response shape

​Defaults

​How filters combine

​Company

​Sector slugs

​Insider

​Trade

​Exclude / only flags

​Filing date and sort

​Example

​Response shape

Defaults

How filters combine

Company

Sector slugs

Insider

Trade

Exclude / only flags

Filing date and sort

Example

Response shape