Skip to main content
POST
/
v1
/
stock
/
screener
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"
    }
  ]
}
'
[
  {
    "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
      }
    ]
  }
]

Documentation Index

Fetch the complete documentation index at: https://finance.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Request body

Required. JSON with:
FieldTypeRequiredDescription
operatorstringYesLogical operator: AND, OR, or NOT
clausesarrayYes*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.
groupsarrayNoNested 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

ParameterTypeDescription
page_sizeintegerResults per request (1–50000).
order_columnstringSort by field (e.g. marketcap, pricetoearnings, roe, volume, open_price, dilutedeps, cashandequivalents).
order_directionstringasc or desc.
primary_onlystringUse 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 in one request. Enter 1 to 50000 depending on whether this is a UI page or export workflow.

Required range: 1 <= x <= 50000
​
order_column
string

Sort by this field (e.g. marketcap, pricetoearnings, roe, volume, open_price, dilutedeps, cashandequivalents)

​
order_direction
enum<string>

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

Return only primary listings; use true or 1

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.

​
groups
object[]

Optional nested groups of clauses for complex logic

Response

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

​
data
object[]

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