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.

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&owner=userId&metrics=metricList

Example:

https://www.unclestock.com/csv?apikey=apiKey&results=150&query=Uncle%27s%20finest%0A&owner=userId&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&owner=userId

Example:

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

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 50. Maximum number of results to return.
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, default false. false (default): exclude cross-listed foreign stocks. true: include foreign cross-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 — matching stocks rank higher, but non-matching stocks still appear. However, should only works as intended when there are at least 3 should clauses. With fewer than 3, should behaves like must and will eliminate non-matching stocks. 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.

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.