For Stock List, Saved Query, and Stock with History, the API returns the same data that the UI exports to CSV. The easiest way to see the exact fields and output format is to perform an export from the UI and inspect the download URL shown beneath the generated CSV. That URL corresponds directly to the API call. Important: The main identifying parameter (for example, list of stocks or the query) are not shown in the UI export URL. The UI passes these internally via Memcache. When calling the API directly from outside the Uncle Stock interface, you must provide these parameters explicitly.

Currencies

Money values are stored in USD and, by default, the exports show them in the stock price currency of the listing, while the Search (JSON) endpoint returns USD. A company that lists in one currency and reports in another (Hexagon AB lists in SEK and reports in EUR) therefore comes back converted, at the exchange rate of each fiscal period.

Every endpoint that returns money values accepts a currency parameter with the same meaning:

Fields that are explicitly in USD by name (market_cap_usd, enterprise_value_usd, the "in USD" columns of the CSV exports) are never converted. Each endpoint reports the currency it actually used: the CSV exports in their column headers and footer lines, the JSON search in a currency field per stock, so mixed portfolios stay readable. Filter values of the Search (JSON) endpoint are always USD, whatever currency says.

Authentication

All API endpoints require an API key. Your key is shown in the Account menu (top right, Gold subscription required). Pass it as the apikey query parameter on every request.

Stock list

Get stock data from search indexes, as per last calculation.

https://www.unclestock.com/csv?apikey=apiKey&stocks=stockList&metrics=metricList

Example:

https://www.unclestock.com/csv?apikey=apiKey&stocks=AAPL%2CMSFT%2CAMZN&metrics=522%2C526%2C23-4%2C391-4%2C3-5%2C3-3%2C277-5%2C277-49%2C61-22%2C331-22%2C46-20%2C172-27%2C173-27%2C86-27%2C76-27%2C117-57%2C73-27%2C131-35%2C132-35

URL parameters

Saved query

Search saved query and get stock data from search indexes, as per last calculation.

https://www.unclestock.com/csv?apikey=apiKey&results=numberOfResults&query=queryName&metrics=metricList

Example:

https://www.unclestock.com/csv?apikey=apiKey&results=150&query=Uncle%27s%20finest%0A&metrics=522%2C526%2C23-4%2C391-4%2C3-5%2C3-3%2C277-5%2C277-49%2C61-22%2C331-22%2C46-20%2C172-27%2C173-27%2C86-27%2C76-27%2C117-57%2C73-27%2C131-35%2C132-35

URL parameters

Stock with history

Get recalculated stock data and history.

https://www.unclestock.com/stock-csv?apikey=apiKey&types&holders&current&medians&fullresults&allyears&quarterobservations&currency=currency&metrics=metricList&groups=groupList&s=symbol

Examples:

https://www.unclestock.com/stock-csv?apikey=apiKey&holders&current&medians&fullresults&metrics=522%2C526%2C23-4%2C391-4%2C3-5%2C3-3%2C277-5%2C277-49%2C61-22%2C331-22%2C46-20%2C172-27%2C173-27%2C86-27%2C76-27%2C117-57%2C73-27%2C131-35%2C132-35&s=AAPL
https://www.unclestock.com/stock-csv?apikey=apiKey&groups=INCOME,BALANCE,CASHFLOW&s=AAPL
https://www.unclestock.com/stock-csv?apikey=apiKey&types&float&quarterobservations&currency=USD&s=AAPL

URL parameters

Backtest result

Get a backtest report.

https://www.unclestock.com/backtest-result?apikey=apiKey&query=queryName

Example:

https://www.unclestock.com/backtest-result?apikey=apiKey&query=Uncle%27s%20finest%0A

URL parameters

Recalculate stocks

Request recalculation of stocks.

https://www.unclestock.com/recalculate?apikey=apiKey&quick&stocks=stockList

URL parameters

Constraints

Symbols

Get list of all common stocks (symbol, name and exchange).

https://www.unclestock.com/symbols?apikey=apiKey&exchange=exchange&nodoubles&includedelisted&fmt=format

URL parameters

Indicators

Get list of all metrics, views and components of scores.

https://unclestock.com/indicators

URL parameters

Scale fields (JSON only)

When scale information is available for a metric, the JSON response includes the following fields to help understand the value range and direction:

For percentage-scale metrics (e.g. ROE, Quality score), min, max, good, and bad are returned as formatted strings such as "20%". Search results return the same format for those metrics. Filter value fields accept both the raw number (0.2) and the percentage string ("20%").

These fields are only present when the metric has defined scale data. Use them to set sensible filter thresholds in the Search API.

Universes

Get list of all continents, countries, sectors, industry groups and industries.

https://unclestock.com/universes?fmt=format

URL parameters

Request reimport

Submit a full reimport request of company and quote data for the given stock symbol. Only available to users with a Gold subscription or higher.

curl -X PUT https://www.unclestock.com/task?apikey=apiKey&task=reimport&s=symbol

URL parameters

Search (JSON)

Screen stocks using a structured JSON body and get results back as JSON. This endpoint is designed for programmatic use and AI agents. Gold subscription required.

POST https://www.unclestock.com/api/search?apikey=apiKey

Send a JSON body with Content-Type: application/json. All fields are optional.

Example request

curl -X POST "https://www.unclestock.com/api/search?apikey=apiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "max_results": 10,
    "security_type": "COMMONSTOCK",
    "exclude_otc": true,
    "exclude_minor_exchanges": true,
    "geography": {
      "continent": { "in": ["EUROPE"] }
    },
    "industry": {
      "sector": { "in": ["TECHNOLOGY"] }
    },
    "filters": [
      { "metric": "id_73-27", "operator": ">", "value": 5, "clause": "must" }
    ],
    "sort": [
      { "metric": "id_73-27", "direction": "desc" }
    ],
    "extra_metrics": ["id_3-5", "id_23-4"]
  }'

Example response

{
  "total_matches": 234,
  "warnings": ["Country 'Chna' not found. Did you mean 'China'?"],
  "results": [
    {
      "symbol": "ASML",
      "name": "ASML Holding NV",
      "sector": "Technology",
      "industry_group": "Semiconductors",
      "industry": "Semiconductor Equipment and Materials",
      "continent": "Europe",
      "country": "Netherlands",
      "fundamental_advice": "Excellent",
      "urgency": "Buy",
      "market_cap_usd": 285000000000,
      "enterprise_value_usd": 283000000000,
      "id_73-27": 18.4,
      "id_3-5": 712.5,
      "id_23-4": 34.2
    },
    ...
  ]
}

Warnings: The response may include a "warnings" array with actionable messages about your query — for example when a geography or industry filter value was not recognised. Always check this array before interpreting results, as a misspelled filter silently narrows or empties your result set.

Request body fields

max_resultsinteger, default 20, maximum 150. Maximum number of results to return. A higher value is capped at 150 and a message is added to the warnings array. This endpoint answers "which are the best matches", so it deals in small numbers; to export a larger set as a file, use the Saved query endpoint, which allows up to 500. A screen returns the best matches according to sort, so use sort and tighter filters rather than a larger result set; total_matches always reports how many stocks passed all filters, whatever the result limit.
textstring. Free text search across company name and description. Use the summary: prefix to search within business descriptions (e.g. summary:renewable energy). Also supports institutionalHolder: and fundHolder: prefixes. For country filtering, always prefer the geography filter.
security_typestring, default COMMONSTOCK. Values: COMMONSTOCK, ETF, PREFERREDSTOCK, CRYPTO, WARRANT, BOND, MUTUALFUND.
is_foreignboolean, optional. Omit (default): both domestic and foreign listings. false: only domestic listings. true: only foreign (cross-listed) listings.
exclude_otcboolean, default true. Exclude OTC/pink sheet stocks.
exclude_minor_exchangesboolean, default true. Exclude minor/alternative exchanges.
geographyobject. Contains continent, country, and/or exchange sub-objects, each with optional in and not_in arrays of enum names. See the Universes API for valid values.
industryobject. Contains sector, industry_group, and/or industry sub-objects, each with optional in and not_in arrays of enum names. See the Universes API for valid values.
filtersarray of filter objects. Each has:
  • metric: metric id from the Indicators service, e.g. id_73-27
  • operator: <, >, <=, >=, or ==
  • value: number, or a string with a suffix: "80%" (→ 0.8), "2B" (→ 2,000,000,000), "500M" (→ 500,000,000), "10K" (→ 10,000)
  • clause: must (default), should, or not

Clause behaviour: must filters are strict — stocks that don't match are excluded. should filters are soft preferences — a stock has to match two thirds of the should clauses, rounded down (1 of 2, 2 of 3, 2 of 4, 3 of 5), and stocks matching more of them rank higher. A single should clause works like must. Use must for the 2–3 most critical filters and should (3+ together) for desirable but non-essential criteria.

sortarray of sort objects. Each has metric (metric id) and optional direction (desc (default) or asc). First item is the primary sort.
extra_metricsarray of metric ids to include in the response in addition to the sort and filter metrics.
include_summaryboolean, default false. When true, includes the full company description in each result as the summary field. Omitted by default to keep responses compact.
currencystring, optional. Omitted: the id_* money metrics are in USD. "reporting": each company's own reporting currency (prices stay in the stock price currency); "price": the stock price currency of each listing; an ISO code such as "EUR": everything in that currency. When set, each result carries two extra fields: currency, the currency of its money metrics, and price_currency, the currency of its prices. market_cap_usd and enterprise_value_usd always stay USD, and filter values are always USD. An unrecognised value is reported in warnings and the response stays in USD. See Currencies.

Geography, industry and exchange filter values

The geography object supports filtering by continent, country, and exchange. The industry object supports filtering by sector, industry_group, and industry. All sub-objects support in and not_in arrays.

Note: geography filters apply to the listing country/exchange, not the company's country of incorporation. A US company cross-listed in Stockholm will appear in European results. By default (is_foreign: false), cross-listed foreign stocks are excluded, so results reflect the primary listing.

All valid enum values for continent, country, exchange, sector, industry group, and industry are available from the Universes API. Use the enumValue field from each entry as the value in the in / not_in arrays.

Metric ids

Use the Indicators endpoint to get metric ids. The id field in each metric entry (e.g. id_73-27) is the value to use for metric, sort[].metric, and extra_metrics.

Fetching metrics for a specific stock

To retrieve metrics for a single stock, put the stock symbol in the text field and the desired metric ids in extra_metrics. This returns exactly one result with the requested values.

curl -X POST "https://www.unclestock.com/api/search?apikey=apiKey" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "AAPL",
    "extra_metrics": ["id_61-22", "id_503-22", "id_3-5"]
  }'

Response:

{
  "total_matches": 1,
  "results": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "id_61-22": 3.0,
      "id_503-22": 3.0,
      "id_3-5": 263.58
    }
  ]
}

Constraints

Limitations

MCP Server

UncleStock also exposes an MCP (Model Context Protocol) server, allowing AI assistants such as Claude to query the screener directly in conversation. See the MCP documentation for setup instructions, tools, and usage examples.