How to Screen Preset Stock Lists with the Mboum API

Preset screener lists let you pull a ready-made market slice, such as day gainers, most actives, or undervalued growth names, without writing your own filter rules.

You choose a documented list value, optionally set offset, and read the body rows plus meta.total so you know how far the list goes. The rows include price, percent change, volume, exchange, and market cap fields you can print or store as returned.

To access this endpoint, you must obtain an API key: Get your API key

The Endpoint

GET /v1/markets/screener returns one preset list. The sample request is list=day_gainers and offset=0. Use this when you want a known basket of tickers for a dashboard, alert feed, or research loop.

Parameters

• list: The preset to return. Documented values:
  • trending — Trending tickers in today's market
  • undervalued_growth_stocks — Stocks with earnings growth rates better than 25% and relatively low PE and PEG ratios.
  • growth_technology_stocks — Technology stocks with revenue and earnings growth in excess of 25%.
  • day_gainers — Stocks ordered in descending order by price percent change with respect to the previous close.
  • day_losers — Stocks ordered in ascending order by price percent change with respect to the previous close.
  • most_actives — Stocks ordered in descending order by intraday trade volume.
  • undervalued_large_caps — Large cap stocks that are potentially undervalued.
  • aggressive_small_caps — Small cap stocks with earnings growth rates better than 25%.
  • small_cap_gainers — Small Caps with a 1 day price change of 5.0% or more.
• offset: Optional integer. The documented example is 10. The sample request uses 0 so you see the start of the list. Keep list fixed while you page.

Python Example

The script requests day gainers at offset 0 and prints the meta totals plus symbol, regularMarketPrice, and regularMarketChangePercent for the first few rows. Send a Bearer token from your Mboum API key.

import requests

url = "https://api.mboum.com/v1/markets/screener"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"list": "day_gainers", "offset": 0}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
payload = response.json()
meta = payload["meta"]
print(meta.get("description"), meta.get("offset"), meta.get("count"), meta.get("total"))
for item in payload["body"][:5]:
    print(item["symbol"], item["regularMarketPrice"], item["regularMarketChangePercent"])

Understanding the Response

A successful response has meta and body. Meta carries description, offset, count, and total. Each body row is one name in the preset. The shortened example below is one row.

{
  "meta": {
    "description": "Day Gainers",
    "offset": 0,
    "count": 25,
    "total": 100
  },
  "body": [
    {
      "symbol": "EXAMPLE",
      "shortName": "Example Inc",
      "longName": "Example Incorporated",
      "regularMarketPrice": 12.34,
      "regularMarketChangePercent": 8.5,
      "regularMarketVolume": 1000000,
      "fullExchangeName": "NasdaqGS",
      "marketCap": 1234567890,
      "currency": "USD"
    }
  ]
}

Print symbol with price and percent change first so you can scan movers quickly. Keep volume, exchange, and market cap when you need context for how liquid or how large a name is inside the preset. Treat meta.total as the size of the list you are paging through, not as a guarantee that one response holds every row.

Key Fields

• description, offset, count, and total: Meta for the page you received. In the shortened example, description is Day Gainers, offset is 0, count is 25, and total is 100.
• symbol, shortName, and longName: The ticker and the two name strings on the row. The sample symbol is EXAMPLE.
• regularMarketPrice and regularMarketChangePercent: The price and the percent change for that row. The shortened example uses 12.34 and 8.5.
• regularMarketVolume: Intraday volume on the row. The shortened example uses 1000000.
• fullExchangeName, marketCap, and currency: Exchange, size, and currency. The sample exchange is NasdaqGS, the sample market cap is 1234567890, and the sample currency is USD.

Practical Use Cases

Scanning a movers list

For a session movers panel, request day_gainers or day_losers. For volume, use most_actives. Growth and value cohorts map to the undervalued and growth list names above. Pick the exact string from the docs rather than inventing a filter. On the first call, set offset=0 and print symbol, regularMarketPrice, and regularMarketChangePercent.

Paging with offset

offset moves through the list, so read meta.total and meta.count before you assume the first response is the whole list. Keep list fixed while you page. Raise offset and stop when offset plus the rows you already saw reach meta.total.

Learn more or explore other endpoints: Market screener