Search instruments using structured filters.

Compose a request with filters, plus optional sorts, columns, and page_size/page_token for pagination. Each filter pairs a field reference (left) with an operator (op, e.g. GREATER_OR_EQUAL, BETWEEN) and comparison values (right), which can be literals or date variables such as today with a modifier. Field names, periods, and lookbacks come from the screener field catalog. sorts order results; columns selects which fields appear in each row (the default field set when omitted).

The response is a paginated, columnar list of matching instruments. Each row is an array of column objects, each with a display name, the field reference, an optional value type hint (e.g. CURR_USD, PERCENT), and the value. An instrument_id column is always prepended. Metadata carries total_items, total_pages, and next_page_token for paging.

Screener results can shuffle between calls; reconcile by re-checking rows across pages rather than assuming stable ordering.

{
  "columns": [
    {
      "name": "market_cap"
    },
    {
      "name": "price"
    },
    {
      "name": "volume"
    }
  ],
  "filters": [
    {
      "left": {
        "name": "market_cap"
      },
      "op": {
        "name": "GREATER_OR_EQUAL"
      },
      "right": [
        {
          "value": 1000000000
        }
      ]
    }
  ],
  "page_size": 25,
  "sorts": [
    {
      "direction": "DESC",
      "field": {
        "name": "market_cap"
      }
    }
  ]
}

{
  "error": {
    "code": 400,
    "message": "Order quantity must be greater than zero"
  },
  "metadata": {
    "page_number": 1,
    "total_items": 42,
    "total_pages": 5
  },
  "data": [
    [
      {
        "field": {
          "name": "market_cap",
          "value_type": "DECIMAL"
        },
        "name": "Market Cap",
        "type": "CURR_USD",
        "value": "2890000000000"
      }
    ]
  ]
}