# Screener

Filter an exchange's full listing by sector, market cap and fundamentals, sorted however you need.

## Screen instruments

POST `/v1/screener` 

 10 credits per call  Growth and up 20 credits with fresh=true Operation ID `screener.run`

Instruments matching every filter in the body, sorted and cut to limit. Leaving a filter out doesn't filter on it.

### Query parameters

- `fresh` boolean  
Skip our cache and get the latest data. Items refreshed this way cost double
- `format` string  
Response format  
One of `json` `csv`  
Defaults to json

### Request body

- `depositaryReceipts` boolean  
true keeps only depositary receipts like ADRs, false leaves them out
- `exchanges` array of strings  
MICs or aliases like ASX  
Up to 50 items
- `fields` array of strings  
Values to fill in. Leave out to fill every one, the rest come back null
- `industries` array of strings  
Industry ids from /v1/sectors  
Up to 100 items
- `limit` integer  
From 1 to 1000\. Defaults to 100
- `marketCap` object  
In each instrument's own currency

  - `max` number  
  At least 0
  - `min` number  
  At least 0
- `order` string  
Defaults to desc, or asc when sorting by name  
One of `asc` `desc`
- `sort` string  
One of `market_cap` `close` `name`  
Defaults to market\_cap
- `types` array of strings

### Response

- `data` array of objects  

  - `close` number or null
  - `currency` string or null  
  The currency close and marketCap are in
  - `industry` string or null  
  An industry id from /v1/sectors
  - `instrument` object  

    - `country` string
    - `currency` string
    - `id` string
    - `mic` string  
      Left out for instruments that don't trade on an exchange, like tokens
    - `name` string
    - `symbol` string
    - `ticker` string or null  
      The code it's known by, like a listing's ticker, a token's symbol or an unlisted fund's APIR code. Null when it has none
    - `type` string  
      One of `equity` `etf` `fund` `index` `fx` `crypto` `token` `rate` `future` `commodity` `bond` `nft` `option` `warrant`
  - `marketCap` number or null
  - `snapshotDate` date  
  The trading day these values are from
- `meta` object  

  - `credits` integer  
  Credits this call cost
  - `nextCursor` string or null  
  Pass as cursor to get the next page, null on the last page
  - `requestId` string

### Errors

`400` Bad Request`401` Unauthorized`402` Payment Required`403` Forbidden`422` Unprocessable Entity`429` Too Many Requests`500` Internal Server Error`503` Service Unavailable

Every error body is problem+json with a stable `code`. See [errors](https://quova.io/docs/index.md#errors).

```shell
curl -X POST "https://api.quova.io/v1/screener" \
  -H "Authorization: Bearer $QUOVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "exchanges": [
      "ASX"
    ],
    "limit": 5,
    "types": [
      "equity"
    ]
  }'
```

Response 

 200 OK 

```json
{
  "data": [
    {
      "instrument": {
        "id": "ins_34VMvft6kZEXThtzFGcAL",
        "symbol": "ASX:BHP",
        "name": "BHP Group Ltd",
        "type": "equity",
        "mic": "XASX",
        "currency": "AUD",
        "country": "AU"
      },
      "snapshotDate": "2026-09-25",
      "currency": "AUD",
      "close": 60.72,
      "marketCap": 310236810658,
      "industry": "steel"
    },
    {
      "instrument": {
        "id": "ins_34VMzDyZVnJThtl1lLWBM",
        "symbol": "ASX:CBA",
        "name": "Commonwealth Bank of Australia",
        "type": "equity",
        "mic": "XASX",
        "currency": "AUD",
        "country": "AU"
      },
      "snapshotDate": "2026-09-25",
      "currency": "AUD",
      "close": 150.83,
      "marketCap": 250985884453,
      "industry": "banks"
    },
    {
      "instrument": {
        "id": "ins_34VN9NERjD9lGUbSudLwO",
        "symbol": "ASX:NEM",
        "name": "NEWMONT CORPORATION",
        "type": "equity",
        "mic": "XASX",
        "currency": "AUD",
        "country": "AU"
      },
      "snapshotDate": "2026-09-25",
      "currency": "AUD",
      "close": 171.02,
      "marketCap": 182587368300,
      "industry": "precious_metals"
    },
    {
      "instrument": {
        "id": "ins_34VN9NERj27Mra67JT2MJ",
        "symbol": "ASX:NAB",
        "name": "NATIONAL AUSTRALIA BANK LIMITED",
        "type": "equity",
        "mic": "XASX",
        "currency": "AUD",
        "country": "AU"
      },
      "snapshotDate": "2026-09-25",
      "currency": "AUD",
      "close": 38.54,
      "marketCap": 118931747092,
      "industry": "banks"
    },
    {
      "instrument": {
        "id": "ins_34VN9NKOYwThv3IdDvGnK",
        "symbol": "ASX:WBC",
        "name": "WESTPAC BANKING CORPORATION",
        "type": "equity",
        "mic": "XASX",
        "currency": "AUD",
        "country": "AU"
      },
      "snapshotDate": "2026-09-25",
      "currency": "AUD",
      "close": 34.49,
      "marketCap": 116734951800,
      "industry": "banks"
    }
  ],
  "meta": {
    "credits": 10,
    "requestId": "req_34VoxwlA4GJckdCH7HsW3",
    "nextCursor": null
  }
}
```