Projection

What projection does

includes and excludes control which fields appear on each row of a paginated response. Default behavior, with both empty or null, returns every projectable field. Either array can be supplied alone to narrow the output, but not both in the same request.

Where it applies

Projection is only accepted by the table-shaped tools: the ones that return rows, one record per result. Aggregation and time-series tools (Net Drift, Heat Map, Gainers / Losers, the exposure endpoints, IV Rank, Volatility Skew, the OHLC endpoints, etc.) have no includes / excludes slot. Their responses always carry every field.

Includes

includes is the explicit whitelist. Pass exactly the fields you need on the response; everything else is dropped.

Request

// Keep only id, ticker, price, and tradeTime on every row.
{
  "sessionDate": "2026-05-13",
  "filter": { "tickers": ["AAPL"] },
  "includes": ["ID", "TICKER", "PRICE", "TRADE_TIME"]
}

Response (truncated)

{
  "nextSearchAfter": ["1747144203000", "9f7f7d52-..."],
  "prints": [
    { "id": "9f7f7d52-...", "ticker": "AAPL", "price": 185.41, "tradeTime": 1747144203000 },
    { "id": "8c2e3f81-...", "ticker": "AAPL", "price": 185.40, "tradeTime": 1747144203000 }
    // every other field is omitted from the response.
  ]
}

Name aliases also work

// All four arrays are equivalent: names are matched the same way as filterExpression.field.
{ "includes": ["TICKER", "STRIKE_PRICE", "IMPLIED_VOLATILITY"] }
{ "includes": ["ticker", "strikePrice", "impliedVolatility"] }
{ "includes": ["SYMBOL", "STRIKE", "IV"] }
{ "includes": ["symbol", "strike", "iv"] }

Excludes

excludes is the explicit blacklist. Pass the fields you do not want; everything else comes back. Useful when you want most of the row and just need to drop a handful of heavy or noisy fields.

Request

// Return every projectable field except the heavy notional + side-detail fields.
{
  "sessionDate": "2026-05-13",
  "filter": { "tickers": ["AAPL"] },
  "excludes": ["NOTIONAL_VALUE", "ASK_PRICE", "ASK_SIZE", "BID_PRICE", "BID_SIZE"]
}

Response (truncated)

{
  "nextSearchAfter": ["1747144203000", "9f7f7d52-..."],
  "prints": [
    {
      "id": "9f7f7d52-...",
      "ticker": "AAPL",
      "price": 185.41,
      "size": 100,
      "printType": "LIT_POOL",
      "tradeSide": "A",
      "tradeTime": 1747144203000,
      "isDelayedPrint": false
    }
    // notionalValue, askPrice, askSize, bidPrice, and bidSize are omitted.
  ]
}

Choose between includes and excludes based on which list is shorter. If you need a handful of fields out of 30, includes reads better; if you want to drop two specific fields, excludes reads better.

Projectable vs filterable

Fields have two orthogonal capability flags: filterable (can appear in filterExpression.field and sort.field) and projectable (can appear in includes / excludes). Most fields are both. A few are only filterable or only projectable.

See Field Reference for the per-surface inventory of which fields are filterable, projectable, or both.

Omitted fields on the response

Omitted fields do not appear on the response record at all, so a projected response is literally smaller on the wire.

Narrowing the field set can also speed the query up: the server skips fetching and serializing fields you did not ask for, so smaller projections typically come back faster as well as smaller.

Where to go next