Stock Screener

Screen securities by sending a POST request with a JSON body containing operator and clauses (and optional groups). Use query params for page size, sort order, and primary-only filter.

Use Case: Build stock screeners (e.g., large-cap value, high ROE, cash-rich) by defining conditions with field, operator, and value. Combine with AND, OR, or NOT.

POST /v1/stock/screener

cURL

marketCapAndPE

curl --request POST \
  --url https://api.aries.com/v1/stock/screener \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "operator": "AND",
  "clauses": [
    {
      "field": "marketcap",
      "operator": "gte",
      "value": "1000000000"
    },
    {
      "field": "pricetoearnings",
      "operator": "gte",
      "value": "5"
    },
    {
      "field": "pricetoearnings",
      "operator": "lte",
      "value": "25"
    }
  ]
}
'

200

Example

[
  {
    "security": {
      "id": "sec_XaL6mg",
      "company_id": "com_qzEByJ",
      "stock_exchange_id": "sxg_ozMr9y",
      "exchange": null,
      "exchange_mic": null,
      "name": "Microsoft Corporation",
      "code": null,
      "currency": null,
      "ticker": "MSFT",
      "composite_ticker": "MSFT:US",
      "figi": "BBG000BPHFS9",
      "composite_figi": null,
      "share_class_figi": null,
      "primary_listing": null
    },
    "data": [
      {
        "tag": "pricetoearnings",
        "number_value": 24.2204,
        "text_value": null
      },
      {
        "tag": "marketcap",
        "number_value": 2888569710564,
        "text_value": null
      }
    ]
  }
]

Request body

Required. JSON with:

Field	Type	Required	Description
operator	string	Yes	Logical operator: AND, OR, or NOT
clauses	array	Yes*	List of conditions. Each has field, operator (eq, gt, gte, lt, lte, contains), and value (string). *At least one of clauses or groups must be non-empty.
groups	array	No	Nested groups, each with operator and clauses, for complex logic.

Common field names include: marketcap, pricetoearnings, roe, volume, open_price, dilutedeps, cashandequivalents, pricetobook, pricetosales, and others supported by the screener.

Query parameters

Parameter	Type	Description
page_size	integer	Results per request (1–50000).
order_column	string	Sort by field (e.g. marketcap, pricetoearnings, roe, volume, open_price, dilutedeps, cashandequivalents).
order_direction	string	asc or desc.
primary_only	string	Use true or 1 to return only primary listings.

Response

Success returns 200 OK with a JSON array. Each element has:

• security — Identity and metadata: id, company_id, stock_exchange_id, exchange, exchange_mic, name, code, currency, ticker, composite_ticker, figi, composite_figi, share_class_figi, primary_listing (fields may be null).
• data — Array of screened tag values: each object has tag (e.g. pricetoearnings, marketcap), number_value, and text_value (one of which may be null).

[
  {
    "security": {
      "id": "sec_XaL6mg",
      "company_id": "com_qzEByJ",
      "stock_exchange_id": "sxg_ozMr9y",
      "exchange": null,
      "exchange_mic": null,
      "name": "Microsoft Corporation",
      "code": null,
      "currency": null,
      "ticker": "MSFT",
      "composite_ticker": "MSFT:US",
      "figi": "BBG000BPHFS9",
      "composite_figi": null,
      "share_class_figi": null,
      "primary_listing": null
    },
    "data": [
      { "tag": "pricetoearnings", "number_value": 24.2204, "text_value": null },
      { "tag": "marketcap", "number_value": 2888569710564.0, "text_value": null }
    ]
  }
]

Examples

Market cap + P/E filter

POST /v1/stock/screener?page_size=100&order_column=marketcap&order_direction=desc
Content-Type: application/json

{
  "operator": "AND",
  "clauses": [
    { "field": "marketcap", "operator": "gte", "value": "1000000000" },
    { "field": "pricetoearnings", "operator": "gte", "value": "5" },
    { "field": "pricetoearnings", "operator": "lte", "value": "25" }
  ]
}

ROE + EPS filter

POST /v1/stock/screener?page_size=50&order_column=roe&order_direction=desc

{
  "operator": "AND",
  "clauses": [
    { "field": "roe", "operator": "gte", "value": "0.15" },
    { "field": "dilutedeps", "operator": "gte", "value": "1" }
  ]
}

P/B and P/S (value stocks)

POST /v1/stock/screener?page_size=100&order_column=marketcap&order_direction=asc

{
  "operator": "AND",
  "clauses": [
    { "field": "pricetobook", "operator": "gte", "value": "0.5" },
    { "field": "pricetobook", "operator": "lte", "value": "3" },
    { "field": "pricetosales", "operator": "lte", "value": "5" }
  ]
}

Volume + open price range

POST /v1/stock/screener?page_size=100&order_column=volume&order_direction=desc

{
  "operator": "AND",
  "clauses": [
    { "field": "volume", "operator": "gte", "value": "500000" },
    { "field": "open_price", "operator": "gte", "value": "10" },
    { "field": "open_price", "operator": "lte", "value": "100" }
  ]
}

Cash-rich, large cap

POST /v1/stock/screener?page_size=50&order_column=cashandequivalents&order_direction=desc

{
  "operator": "AND",
  "clauses": [
    { "field": "cashandequivalents", "operator": "gte", "value": "1000000000" },
    { "field": "marketcap", "operator": "gte", "value": "5000000000" }
  ]
}

Primary listings only

POST /v1/stock/screener?page_size=500&order_column=marketcap&order_direction=desc&primary_only=true

{
  "operator": "AND",
  "clauses": [
    { "field": "marketcap", "operator": "gte", "value": "500000000" },
    { "field": "roe", "operator": "gte", "value": "0.1" }
  ]
}

Authorizations

Authorization · string · header · required

OAuth2 Bearer token: obtain an access token from the token endpoint and send it in the Authorization header.

Query Parameters

page_size · integer

Number of results to return per page. Use smaller values (10–50) for UI screens, larger (100–500) for batch exports. Defaults to the upstream provider's default.

Required range: 1 <= x <= 50000

order_column · string

Which data column to sort the screened results by. Accepts any column the upstream screener exposes — not a fixed enum on our side. Common columns:

• marketcap — market capitalization.
• pricetoearnings — trailing P/E ratio.
• pricetobook — price-to-book ratio.
• roe — return on equity.
• volume — average daily volume.
• open_price / close_price — most recent open / close.
• dilutedeps — diluted earnings per share (TTM).
• cashandequivalents — cash + cash equivalents on the balance sheet.

Pair with order_direction (asc / desc).

order_direction · enum<string>

Direction to sort order_column in:

• asc — ascending (smallest first).
• desc — descending (largest first). Sort direction for results. Use ascending for oldest or smallest first, descending for newest or largest first.

Available options: asc, desc

Example:

"asc"

primary_only · string

When true, return only the primary listing for each company (e.g. NYSE for a U.S. dual-listed stock) instead of every listing. Defaults to false.

Body

application/json

Screener request with operator (AND/OR), clauses (field, operator, value), and optional groups.

Request body for POST /v1/stock/screener. At least one of clauses or groups must be non-empty.

operator · enum<string> · required

Logical operator for combining clauses: AND, OR, or NOT

Available options: AND, OR, NOT

clauses · object[]

List of filter conditions (field, operator, value). Required unless groups is non-empty.

Show child attributes

groups · object[]

Optional nested groups of clauses for complex logic

Show child attributes

Response

200

application/json

Array of screened securities; each item has security (id, ticker, name, etc.) and data (array of tag, number_value, text_value)

security · object

Security identity and metadata

Show child attributes

data · object[]

Screened data-tag values (e.g. pricetoearnings, marketcap)

Show child attributes