Skip to main content
POST
Builder
Build a thematic stock universe from a natural language query. An AI agent interprets your query, searches ~65,000 company descriptions, and returns relevant stocks ranked by relevance score.

How It Works

This endpoint uses async job processing:
  1. Submit Request: POST with a natural language query
  2. Receive Job ID: Get a job ID and polling URL immediately
  3. Poll for Status: Check /v1/jobs/{job_id} until status is completed
  4. Get Results: The completed job contains a ranked list of matching companies
Typically takes 15-40 seconds. The agent may run multiple search iterations to refine results.

Request Body

Response (202 Accepted)

Completed Response

When the job completes, GET /v1/jobs/{job_id} returns the matched companies:

Company Fields

Query Tips

The agent works best with specific, descriptive queries:

Supported Regions

When your query mentions a geography, the agent can filter by:
  • Regions: Europe, Asia, Americas, Middle East, Oceania
  • Countries: United States, United Kingdom, Japan, South Korea, China, Hong Kong, Taiwan, Singapore, India, Germany, France, Canada, Brazil, Australia, Saudi Arabia, UAE, Thailand, Malaysia, Indonesia, and 20+ more

Example

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request model for thematic stock universe builder.

query
string
required

Natural language query describing the investment theme and any filters

Required string length: 2 - 500
Example:

"Find me top 50 electric vehicle companies in Asia"

markets
string[] | null

Exact market names (e.g. 'United States', 'Japan'). Unknown names match zero companies.

Minimum array length: 1
region

Geographic region filter — a single region or a list of them, which UNION together. Takes precedence over markets if both are set. Valid: Europe, Asia, Southeast Asia, South Asia, East Asia, Americas, Middle East, Oceania.

Available options:
Europe,
Asia,
Southeast Asia,
South Asia,
East Asia,
Americas,
Middle East,
Oceania
sectors
string[] | null

TRBC sector names; GICS-11 names accepted and normalized (case-insensitive).

Minimum array length: 1
strict_theme
boolean
default:true

Require a keyword match as well as thematic relevance. Disable for broader recall. Narrow themes may return fewer companies than requested.

rerank
boolean | null

Optionally rerank results by semantic similarity to the theme. Omit to use the server default. If reranking is unavailable, the original order is retained; inspect rerank.applied in the result.

min_relevance
number | null

Optional similarity threshold from 0 to 1, applied only when reranking is active. Companies without similarity data are retained. The returned similarity itself is not guaranteed to be within this interval.

Required range: 0 <= x <= 1

Response

Successful Response

Last modified on April 1, 2026