Skip to main content
The yf_screen tool runs powerful screener queries against Yahoo Finance’s database to filter stocks and funds based on fundamental metrics, technical indicators, and other criteria.

​
Parameters

​
query
string | object
required
Screener query. Can be:
  • String: Predefined screener name (e.g., “aggressive_small_caps”)
  • Object: Custom query builder structure with operator and operands
​
query_type
string
Type of securities to screen.Options:
  • equity - Screen stocks/equities
  • fund - Screen mutual funds and ETFs
Required when using custom query objects. Optional for predefined screener names.
​
offset
integer
default:0
Starting position for paginated results.Constraints: Min: 0
​
size
integer
default:25
Number of results per page.Constraints: Min: 1, Max: 250
​
count
integer
Total number of results to return across all pages.Constraints: Min: 1, Max: 250
​
sortField
string
Field name to sort results by (e.g., “marketcap”, “peratio”, “volumeavg”).
​
sortAsc
boolean
default:false
Sort direction. true for ascending, false for descending.
​
userId
string
User identifier (optional, for saved screeners).
​
userIdType
string
Type of user identifier (optional).

​
Output Options

​
response_format
string
default:"json"
Format of the response data.Options: json, markdown
​
preview_limit
integer
default:25
Number of rows to preview when using markdown format.Constraints: Min: 1, Max: 200
​
save
object
Save the results to a file.

​
Query Builder Structure

Custom queries use a recursive structure with operators and operands: 
{
  "operator": "AND | OR | GT | LT | EQ | BTWN | ...",
  "operands": [
    // Can be strings, numbers, booleans, or nested query objects
  ]
}

​
Common Operators

  • AND - All conditions must be true
  • OR - At least one condition must be true
  • GT - Greater than
  • LT - Less than
  • GTE - Greater than or equal
  • LTE - Less than or equal
  • EQ - Equal to
  • BTWN - Between two values (inclusive)

​
Field References

Operands can reference screener fields:
  • Market cap: marketcap
  • P/E ratio: peratio
  • Volume: volumeavg
  • Price: lastprice
  • Sector: sector
  • Industry: industry
Use the yf_equity_query_fields tool to discover available screener fields and their valid values.

​
Examples

​
Predefined Screener

Use built-in screener presets: 
{
  "query": "aggressive_small_caps",
  "size": 50,
  "sortField": "marketcap",
  "sortAsc": false
}

​
Large-Cap Tech Stocks

Find technology stocks with market cap over $10B: 
{
  "query": {
    "operator": "AND",
    "operands": [
      {
        "operator": "EQ",
        "operands": ["sector", "Technology"]
      },
      {
        "operator": "GT",
        "operands": ["marketcap", 10000000000]
      }
    ]
  },
  "query_type": "equity",
  "size": 100,
  "sortField": "marketcap",
  "sortAsc": false
}

​
Value Stocks with Low P/E

Screen for stocks with P/E ratio between 5 and 15: 
{
  "query": {
    "operator": "BTWN",
    "operands": ["peratio", 5, 15]
  },
  "query_type": "equity",
  "size": 50,
  "sortField": "peratio",
  "sortAsc": true
}

​
High-Volume Stocks

Find stocks with average volume over 1 million shares: 
{
  "query": {
    "operator": "GT",
    "operands": ["volumeavg", 1000000]
  },
  "query_type": "equity",
  "size": 100,
  "sortField": "volumeavg",
  "sortAsc": false
}

​
Multi-Criteria Screen

Combine multiple conditions: 
{
  "query": {
    "operator": "AND",
    "operands": [
      {
        "operator": "BTWN",
        "operands": ["marketcap", 2000000000, 10000000000]
      },
      {
        "operator": "LT",
        "operands": ["peratio", 20]
      },
      {
        "operator": "OR",
        "operands": [
          {"operator": "EQ", "operands": ["sector", "Technology"]},
          {"operator": "EQ", "operands": ["sector", "Healthcare"]}
        ]
      }
    ]
  },
  "query_type": "equity",
  "size": 50,
  "sortField": "marketcap",
  "sortAsc": false
}

​
Fund Screening

Screen mutual funds or ETFs: 
{
  "query": {
    "operator": "AND",
    "operands": [
      {"operator": "GT", "operands": ["aum", 1000000000]},
      {"operator": "LT", "operands": ["expenseratio", 0.5]}
    ]
  },
  "query_type": "fund",
  "size": 50,
  "sortField": "aum",
  "sortAsc": false
}

​
Pagination

Handle large result sets with pagination: 
{
  "query": "day_gainers",
  "offset": 0,
  "size": 50
}
To get the next page: 
{
  "query": "day_gainers",
  "offset": 50,
  "size": 50
}

​
Response Structure

Screener results include:
  • Symbol: Ticker symbol
  • Name: Company/fund name
  • Field Data: All requested and available fields for each result
  • Total: Total number of matches (for pagination)

​
Best Practices

Start with broad queries and refine them iteratively. Use smaller size values during development to reduce response time.
Complex queries with many nested conditions may take longer to execute. Consider breaking them into multiple simpler screens.
The maximum count and size is 250 results. For larger datasets, use pagination with offset.

Build docs developers (and LLMs) love

Get started for freeTalk to us