# US Stock Screener API — Finviz Market Data (`nexgensignal/us-stock-screener-api`) Actor

Keyless US stock screener API built on Finviz. Screen by preset or custom URL; per-ticker JSON with price, market cap, P/E, volume. Rotating-session retry, pay per ticker. Not investment advice.

- **URL**: https://apify.com/nexgensignal/us-stock-screener-api.md
- **Developed by:** [NexGen Signal](https://apify.com/nexgensignal) (community)
- **Categories:** Business, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $33.50 / 1,000 ticker records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## US Stock Screener API — Finviz Market Data

**Pay per ticker. A clean, keyless US-equity screener API — screen the whole market by preset or your own Finviz filter, and get structured per-ticker JSON back.**

Hand this actor a screener preset (`top_gainers`, `most_active`, `undervalued_large`, …) or any Finviz screener URL and it returns one clean JSON record per matching ticker: symbol, company, sector, industry, country, market cap, P/E, price, change, and volume. It is a direct, code-friendly screener API built on the Finviz public screener — hardened with a rotating-session, four-try fetch so runs complete reliably.

### What this is, in one paragraph

Finviz's screener is the fastest way to filter the US market, but its output lives in an HTML page, not an API. This actor drives that screener from code: it takes a preset or a raw `screener.ashx` URL, pages through the results (twenty tickers a page), parses each row into a typed record, and delivers it. The upgrade over a plain scraper is reliability — every page fetch runs through a **rotating-session retry, up to four attempts**, each on a fresh proxy session, so a single blocked request doesn't sink the run. Market-cap and volume are parsed into real numbers (`market_cap_usd`, `volume`) alongside the raw display strings, so you can sort and filter without post-processing. Data comes solely from the Finviz public screener — there is no Yahoo Finance dependency anywhere in this actor.

### Who buys this and for what job

- **Quant and retail traders** pulling a screen — top gainers, unusual volume, oversold large-caps — into a spreadsheet or model on a schedule.
- **Fintech builders** who need a keyless screener endpoint they can call from an app without maintaining a scraper.
- **Analysts and researchers** snapshotting a market segment (a sector, a market-cap band) into structured rows.
- **AI agents** that need current US-market screening as a tool call, returning clean JSON.

### The upgrade: reliability

The single biggest difference between a screener scrape that works and one that doesn't is what happens when a request is refused. This actor answers that with the proven fix pattern: **a four-attempt, rotating-session fetch on the primary source.** Each retry uses a fresh proxy session (Apify Proxy, on by default), and a page only counts as failed after all four attempts miss — so transient blocks are absorbed rather than fatal. Combined with a real browser User-Agent and honest pacing, that is what turns an ~80%-reliable scrape into a dependable API. This actor performs no bot-detection circumvention; it retries honest requests.

### Pricing

| Event | Free plan | Bronze | Silver | Gold / Platinum / Diamond |
|-------|-----------|--------|--------|---------------------------|
| `apify-actor-start` | $0.00005 | $0.00005 | $0.00005 | $0.00005 |
| `apify-default-dataset-item` | $0.05 | $0.045 | $0.04 | $0.0335 |

A negligible start fee plus one item charge per ticker delivered. Delivered before charged; a run that returns nothing costs only the start fee.

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `preset` | string | — | A screener preset (see list below). Ignored if `screenerUrl` is set. |
| `screenerUrl` | string | large-cap overview | Any `finviz.com/screener.ashx` URL (v=111 Overview view). Overrides `preset`. |
| `maxResults` | integer | 50 | Maximum tickers delivered (1–5000). |
| `proxyConfiguration` | object | Apify Proxy on | Proxy for the rotating-session fetch. |

**Presets:** `large_cap`, `mega_cap`, `small_cap`, `top_gainers`, `top_losers`, `most_active`, `new_high`, `new_low`, `oversold`, `overbought`, `unusual_volume`, `undervalued_large`, `high_dividend`, `growth`. Or build any screen in Finviz, copy the URL, and pass it as `screenerUrl`.

### Output

One JSON object per ticker. Real example (values as displayed):

```json
{
  "record_id": "AAPL",
  "ticker": "AAPL",
  "company": "Apple Inc",
  "sector": "Technology",
  "industry": "Consumer Electronics",
  "country": "USA",
  "market_cap": "4508.14B",
  "market_cap_usd": 4508140000000.0,
  "pe": "35.41",
  "price": 308.90,
  "change_pct": "-0.46%",
  "volume": 16752184.0,
  "source": "Finviz public screener (finviz.com)",
  "observed_at": "2026-08-25T00:00:00Z"
}
```

An unbilled `RUN_RECEIPT` records the screener URL, how many rows were delivered, and any partial-run note.

### Field reference

Each record carries `record_id` and `ticker` (the symbol), `company`, `sector`, `industry`, `country`, `market_cap` (display string) and `market_cap_usd` (parsed number), `pe`, `price` (number), `change_pct` (display string), and `volume` (number). Provenance travels on every record: `source`, `source_url`, `licence`, `attribution`, `disclaimer`, and `observed_at`.

### How a run works

The actor resolves your `preset` or `screenerUrl` to a Finviz v=111 Overview screen, then pages through it: `&r=1`, `&r=21`, `&r=41`, twenty tickers a page, until it reaches your `maxResults` ceiling or runs out of rows. Each page fetch goes through the rotating-session, four-try path; the returned HTML is parsed into rows, each row is mapped to the eleven Overview columns, market-cap and volume are converted to numbers, and one record per ticker is delivered. If a later page fails after all rows so far have been delivered, the run finishes with a partial note rather than discarding what it has.

### Working with the data

Because `market_cap_usd` and `volume` are real numbers, you can sort or threshold directly — "large-caps under a 20 P/E with volume over ten million" — without cleaning display strings first. The `ticker` is the join key into any position, watchlist, or fundamentals table you keep. Run a preset on a schedule to capture the day's gainers or unusual-volume names into your own store, or pass a saved Finviz URL to reproduce a custom screen exactly. Feed the output straight into a model, a Google Sheet, or an agent's reasoning step.

### Honest limitations

- **As displayed.** Values are the Finviz screener's displayed figures at fetch time — point-in-time market data, **not investment advice** and not a recommendation. Verify against the exchange or your broker before relying on it.
- **Overview columns.** This actor reads the v=111 Overview view; other Finviz custom views are not parsed.
- **Finviz-only.** Data is sourced solely from the Finviz public screener; there is no Yahoo Finance dependency in this actor.
- **No person data.** Only public per-ticker market data is read and emitted.

### Presets in depth

The presets cover the screens traders reach for most. `top_gainers`, `top_losers`, `most_active`, and `unusual_volume` map to Finviz signal screens for the day's movers. `new_high` and `new_low` surface stocks at 52-week extremes. `oversold` and `overbought` map to RSI signals for mean-reversion setups. `large_cap`, `mega_cap`, and `small_cap` bound the screen by market-cap band. `undervalued_large` combines large-cap with a sub-20 P/E, `high_dividend` filters for high yield, and `growth` filters mid-and-up caps with strong EPS growth. When a preset isn't enough, build the exact screen in Finviz's own UI — any combination of descriptive, fundamental, and technical filters — copy the resulting `screener.ashx?v=111&...` URL, and pass it as `screenerUrl`; the actor pages and parses it identically.

### Use with AI agents

Because the output is flat, typed JSON keyed by `ticker`, an agent can call this actor as a tool and reason over the result without any parsing step. A prompt like *"screen for the most active US stocks today and return the ten largest by market cap"* is answerable directly: the agent runs the `most_active` preset, sorts by `market_cap_usd`, and reads off the tickers. The negligible start fee and per-ticker pricing make it cheap to call repeatedly inside an agent loop or a scheduled workflow.

### Scheduling and watch use

Point a schedule at a preset to capture a daily snapshot — the day's gainers, or every stock hitting a new high — into your own store, building a time series the Finviz UI doesn't keep. Because each run is bounded by `maxResults` and priced per delivered ticker, the cost of a recurring screen is predictable and small.

### Differentiation

A **US stock screener API** built on the Finviz public screener, upgraded with a rotating-session four-try fetch for reliability and one-word screener presets as inputs. Keyless, pay-per-ticker, callable from code or an AI agent, Finviz-only.

***

*Source: Finviz public screener (finviz.com). Public market data as displayed; reformatted to per-ticker records, values unmodified. Not investment advice. No person data.*

# Actor input Schema

## `preset` (type: `string`):

Convenient screener preset. Ignored if screenerUrl is set.

## `screenerUrl` (type: `string`):

A finviz.com/screener.ashx URL (v=111 Overview view). Overrides preset.

## `maxResults` (type: `integer`):

Maximum tickers delivered.

## `proxyConfiguration` (type: `object`):

Apify proxy (rotating sessions harden the fetch). Recommended: Apify Proxy on.

## Actor input object example

```json
{
  "preset": "",
  "screenerUrl": "https://finviz.com/screener.ashx?v=111&f=cap_largeover",
  "maxResults": 50,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `results` (type: `string`):

Delivered records.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "screenerUrl": "https://finviz.com/screener.ashx?v=111&f=cap_largeover",
    "maxResults": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("nexgensignal/us-stock-screener-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "screenerUrl": "https://finviz.com/screener.ashx?v=111&f=cap_largeover",
    "maxResults": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("nexgensignal/us-stock-screener-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "screenerUrl": "https://finviz.com/screener.ashx?v=111&f=cap_largeover",
  "maxResults": 50
}' |
apify call nexgensignal/us-stock-screener-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nexgensignal/us-stock-screener-api"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/rs3NKeaBDzBcFzTXa/builds/gJdlugneYTwLQHnD7/openapi.json