Universe & Cohorts

The universe block scopes which stocks are eligible before any leg runs. Omit it entirely to screen the whole global market (~24,700 stocks).

universe shape

{
  "include": [ <cohort>, <cohort>, ... ],
  "exclude": [ <cohort>, ... ]
}

• include cohorts are OR-combined — a stock in any included cohort is eligible.
• exclude cohorts are subtracted after inclusion.
• Fields within a single cohort are AND-ed — all must match.

---

Cohort fields

country — market by ISO-2 code

"country": ["US"]
"country": ["TH", "SG", "MY"]
"country": ["JP", "KR", "TW"]

Filters by the stock's primary listing market. Uses standard ISO 3166-1 alpha-2 codes. A stock is matched by its home market, not a cross-listing.

Common codes:

Code	Market
US	United States
JP	Japan
KR	South Korea
TW	Taiwan
CN	China (A-shares)
HK	Hong Kong
IN	India
AU	Australia
SG	Singapore
TH	Thailand
MY	Malaysia
ID	Indonesia
GB	United Kingdom
DE	Germany
FR	France

Use GET /v1/gics?country=true to see the full country list.

---

gics — sector, industry group, industry, or sub-industry

"gics": "45"       // all IT
"gics": "4510"     // Technology Hardware & Equipment (industry group)
"gics": "451020"   // Electronic Equipment & Instruments (industry)
"gics": "45102010" // Electronic Components (sub-industry)

The value is a prefix — all GICS codes that start with this prefix match. This means you can scope broadly (sector level "45") or precisely (sub-industry "45102010").

Common sector codes:

Code	Sector
10	Energy
15	Materials
20	Industrials
25	Consumer Discretionary
30	Consumer Staples
35	Health Care
40	Financials
45	Information Technology
50	Communication Services
55	Utilities
60	Real Estate

:::tip Lookup GICS codes by name GET /v1/gics?q=semiconductor returns the GICS node (453010) for Semiconductors. Use this instead of memorising codes. See GICS reference → :::

---

size — relative market-cap tier

"size": ["large", "mega"]
"size": ["small", "mid"]
"size": ["micro"]

Size tiers are relative within each market, modelled on MSCI's methodology:

Tier	Approximate coverage
mega	Top ~70% of market cap in market
large	Next ~15%
mid	Next ~10%
small	Next ~4%
micro	Bottom ~1%

:::warning Size is market-relative, not dollar-absolute A "large" stock in Thailand is far smaller in USD than a "large" stock in the US. To enforce a specific dollar threshold across markets, use mcap_min instead of (or in addition to) size. :::

---

mcap_min / mcap_max — absolute USD market cap

"mcap_min": 1000000000   // $1B minimum
"mcap_max": 10000000000  // $10B maximum

Absolute USD market cap floor/ceiling, independent of market. Use this when you want a consistent dollar threshold across multiple markets (e.g. "only stocks > $500M regardless of whether they're in Thailand or the US").

Combine with size to get both a relative tier and a dollar floor:

{
  "size": ["small", "mid"],
  "mcap_min": 500000000
}

---

asset_type — asset class filter

"asset_type": ["Common Stock"]
"asset_type": ["ETF"]
"asset_type": ["Common Stock", "ETF"]
"asset_type": ["Crypto"]

Valid values: "Common Stock" · "ETF" · "Crypto" · "Forex"

Omit this field to include all asset types in the universe.

---

theme — megatrend node membership

"theme": [10000000]           // AI megatrend
"theme": [10000000, 16000000] // AI AND Electric Vehicles (intersection)

Restricts to stocks that belong to all listed theme nodes. Multiple IDs are AND-ed — the stock must be in every listed theme.

Get node IDs via:

• GET /v1/megatrends — browse the theme tree
• POST /v1/ta/find-signal?q=electric vehicles — resolve a phrase to a node ID

---

Examples

US large/mega-cap tech

{ "include": [{ "country": ["US"], "gics": "45", "size": ["large", "mega"] }] }

Asian semiconductor names — TW, KR, JP

{ "include": [{ "country": ["TW","KR","JP"], "gics": "453010" }] }

AI-theme stocks globally, excluding China

{
  "include": [{ "theme": [10000000] }],
  "exclude": [{ "country": ["CN"] }]
}

Southeast Asian mid/small caps over $200M

{
  "include": [{
    "country": ["TH","SG","MY","ID"],
    "size": ["mid","small"],
    "mcap_min": 200000000
  }]
}

European pharma + biotech

{
  "include": [{
    "country": ["GB","DE","FR","CH","DK","SE","NL"],
    "gics": "352020"
  }]
}

Two cohorts OR-combined: US tech OR Asian semiconductors

{
  "include": [
    { "country": ["US"], "gics": "45", "size": ["large","mega"] },
    { "country": ["TW","KR","JP"], "gics": "453010" }
  ]
}

Whole market (omit universe entirely)

{}