# Finviz API

> Finviz returns stock data, screener results, and insider trades as a workflow and API.

Finviz, also called Finviz.com, provides delayed US-listed stock snapshots through Get stock snapshot, using a company name or ticker. Screen stocks returns matching US stocks using filters such as sector, company size, dividend yield, P/E ratio, signal, and sort order. List insider trades returns recent Form 4 trades, optionally filtered by company and trade type.

- Page: https://fous.com/workflows/finviz
- Handle: `@finviz`
- Category: [Finance](https://fous.com/workflows/category/finance)
- Source website: https://finviz.com
- Last verified: Sep 29, 2026
- Fous is not affiliated with Finviz.

## Methods

### Get stock snapshot

Operation `get_stock_snapshot`, version 1. 1 credit per call.

Get a delayed US-listed stock snapshot from its ticker or company name. Analyst labels summarize Finviz’s 1–5 mean score; dividend yield uses the estimated dividend when available. Missing metrics return null.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `company` | string | yes | `"Apple"` | Company name or US stock ticker, for example Apple or AAPL. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "company"
  ],
  "properties": {
    "company": {
      "type": "string",
      "description": "Company name or US stock ticker, for example Apple or AAPL.",
      "examples": [
        "Apple",
        "AAPL",
        "MSFT"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "company": "Apple"
    },
    {
      "company": "AAPL"
    },
    {
      "company": "MSFT"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `sector` | string | `"Technology"` | Business sector |
| `ticker` | string | `"AAPL"` | Stock ticker |
| `country` | string | `"USA"` | Company country |
| `exchange` | string | `"Nasdaq"` | US listing exchange |
| `industry` | string | `"Consumer Electronics"` | Industry |
| `price_usd` | number or null | `338.4` | Delayed share price in US dollars |
| `finviz_link` | string | `"https://finviz.com/stock?t=AAPL"` | Finviz stock page |
| `company_name` | string | `"Apple Inc"` | Company name |
| `market_cap_usd` | number or null | `4938670000000` | Market capitalization in US dollars, full number |
| `short_float_percent` | number or null | `0.88` | Short float as percent of float |
| `today_change_percent` | number or null | `-0.78` | Change today, in percent |
| `profit_margin_percent` | number or null | `27.62` | Profit margin in percent |
| `analyst_recommendation` | string or null | `"Buy"` | Analyst recommendation from Strong buy to Strong sell |
| `dividend_yield_percent` | number or null | `0.33` | Estimated dividend yield in percent, null if none |
| `fifty_two_week_low_usd` | number or null | `243.42` | 52-week low in US dollars |
| `fifty_two_week_high_usd` | number or null | `345.34` | 52-week high in US dollars |
| `price_to_earnings_ratio` | number or null | `38.79` | Trailing price-to-earnings ratio |
| `raw_recommendation_score` | number or null | `2.13` | Finviz analyst mean score from 1 (buy) to 5 (sell) |
| `insider_ownership_percent` | number or null | `0.12` | Insider ownership in percent |
| `forward_price_to_earnings_ratio` | number or null | `35.23` | Forward price-to-earnings ratio |
| `institutional_ownership_percent` | number or null | `68.89` | Institutional ownership in percent |
| `average_analyst_price_target_usd` | number or null | `337.68` | Mean analyst price target in US dollars |
| `expected_earnings_growth_next_year_percent` | number or null | `8.77` | Expected earnings growth next year, in percent |

**Example input**

```json
{
  "company": "Apple"
}
```

**Example output**

```json
{
  "sector": "Technology",
  "ticker": "AAPL",
  "country": "USA",
  "exchange": "Nasdaq",
  "industry": "Consumer Electronics",
  "price_usd": 338.4,
  "finviz_link": "https://finviz.com/stock?t=AAPL",
  "company_name": "Apple Inc",
  "market_cap_usd": 4938670000000,
  "short_float_percent": 0.88,
  "today_change_percent": -0.78,
  "profit_margin_percent": 27.62,
  "analyst_recommendation": "Buy",
  "dividend_yield_percent": 0.33,
  "fifty_two_week_low_usd": 243.42,
  "fifty_two_week_high_usd": 345.34,
  "price_to_earnings_ratio": 38.79,
  "raw_recommendation_score": 2.13,
  "insider_ownership_percent": 0.12,
  "forward_price_to_earnings_ratio": 35.23,
  "institutional_ownership_percent": 68.89,
  "average_analyst_price_target_usd": 337.68,
  "expected_earnings_growth_next_year_percent": 8.77
}
```

### List insider trades

Operation `list_insider_trades`, version 1. 1 credit per call.

List recent Form 4 insider trades by company executives and directors, optionally for a company or trade type. Finviz displays at most 200 matching public rows; proposed sales and ownership-only filings are excluded.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `company` | string | no | `"Tesla"` | Company name or stock ticker, such as Tesla or TSLA. Omit to see trades across the whole market. |
| `trade_type` | string | no | `"sales"` | Show buys, sales, or both, such as buys. |
| `max_results` | integer | no | `20` | Most trades to return, such as 20. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "company": {
      "type": "string",
      "description": "Company name or stock ticker, such as Tesla or TSLA. Omit to see trades across the whole market.",
      "examples": [
        "Tesla",
        "TSLA"
      ]
    },
    "trade_type": {
      "enum": [
        "buys",
        "sales",
        "both"
      ],
      "type": "string",
      "default": "both",
      "description": "Show buys, sales, or both, such as buys.",
      "examples": [
        "sales",
        "buys"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "description": "Most trades to return, such as 20.",
      "x-fous-developer": true,
      "examples": [
        20,
        100,
        5
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {},
    {
      "company": "Tesla",
      "trade_type": "sales",
      "max_results": 20
    },
    {
      "trade_type": "sales",
      "max_results": 100
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `trades` | array |  |  |
| `trades[].role` | string | `"CEO"` |  |
| `trades[].shares` | integer or null | `2568732` |  |
| `trades[].ticker` | string | `"TSLA"` |  |
| `trades[].company` | string | `"Tesla Inc"` |  |
| `trades[].page_url` | string | `"https://finviz.com/insidertrading?t=TSLA"` |  |
| `trades[].trade_date` | string | `"2025-09-12"` |  |
| `trades[].total_value` | number or null | `999959042` |  |
| `trades[].insider_name` | string | `"Musk Elon"` |  |
| `trades[].price_currency` | string | `"USD"` |  |
| `trades[].sec_filing_url` | string | `"https://www.sec.gov/Archives/edgar/data/1318605/000110465925089693/xslF345X05/tm2526050-1_4seq1.xml"` |  |
| `trades[].value_currency` | string | `"USD"` |  |
| `trades[].price_per_share` | number or null | `389.28` |  |
| `trades[].transaction_type` | string | `"Buy"` |  |
| `trades[].shares_owned_after_trade` | integer or null | `413362808` |  |

**Example input**

```json
{
  "company": "TSLA",
  "trade_type": "buys",
  "max_results": 5
}
```

**Example output**

```json
{
  "trades": [
    {
      "role": "CEO",
      "shares": 2568732,
      "ticker": "TSLA",
      "company": "Tesla Inc",
      "page_url": "https://finviz.com/insidertrading?t=TSLA",
      "trade_date": "2025-09-12",
      "total_value": 999959042,
      "insider_name": "Musk Elon",
      "price_currency": "USD",
      "sec_filing_url": "https://www.sec.gov/Archives/edgar/data/1318605/000110465925089693/xslF345X05/tm2526050-1_4seq1.xml",
      "value_currency": "USD",
      "price_per_share": 389.28,
      "transaction_type": "Buy",
      "shares_owned_after_trade": 413362808
    },
    {
      "role": "Director",
      "shares": 4000,
      "ticker": "TSLA",
      "company": "Tesla Inc",
      "page_url": "https://finviz.com/insidertrading?t=TSLA",
      "trade_date": "2025-04-24",
      "total_value": 1025232,
      "insider_name": "Gebbia Joseph",
      "price_currency": "USD",
      "sec_filing_url": "https://www.sec.gov/Archives/edgar/data/1318605/000177134025000006/xslF345X05/edgardoc.xml",
      "value_currency": "USD",
      "price_per_share": 256.31,
      "transaction_type": "Buy",
      "shares_owned_after_trade": 4111
    },
    {
      "role": "Director",
      "shares": 10,
      "ticker": "TSLA",
      "company": "Tesla Inc",
      "page_url": "https://finviz.com/insidertrading?t=TSLA",
      "trade_date": "2020-11-30",
      "total_value": 5676,
      "insider_name": "Gracias Antonio J.",
      "price_currency": "USD",
      "sec_filing_url": "https://www.sec.gov/Archives/edgar/data/1318605/000149515821000003/xslF345X03/primary_doc.xml",
      "value_currency": "USD",
      "price_per_share": 567.6,
      "transaction_type": "Buy",
      "shares_owned_after_trade": 1304390
    }
  ]
}
```

### Screen stocks

Operation `screen_stocks`, version 1. 1 credit per call.

Find US stocks by sector, company size, dividend yield, P/E ratio, signal, and sort order. Figures reflect the latest screener display and may be delayed.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `page` | integer | no | `2` | 1-based page of results to start from, for example 2. |
| `sort` | string | no | `"highest_dividend"` | Stock ranking, for example largest_first. |
| `sector` | string | no | `"Healthcare"` | Business sector, for example Technology; any includes all sectors. |
| `signal` | string | no | `"top_gainers"` | Market signal, for example top_gainers. |
| `max_results` | integer | no | `10` | Maximum number of stocks to return, for example 20. Up to 100. |
| `company_size` | string | no | `"mega"` | Market value range, for example large ($10B–$200B). |
| `minimum_dividend_yield_percent` | number | no | `2.5` | Minimum annual dividend yield as a percentage, for example 2.5. |
| `maximum_price_to_earnings_ratio` | number | no | `25` | Max P/E ratio, for example 25. Omit to include any P/E. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "default": 1,
      "minimum": 1,
      "description": "1-based page of results to start from, for example 2.",
      "x-fous-developer": true,
      "examples": [
        2
      ]
    },
    "sort": {
      "enum": [
        "largest_first",
        "biggest_gainers",
        "highest_dividend"
      ],
      "type": "string",
      "default": "largest_first",
      "description": "Stock ranking, for example largest_first.",
      "examples": [
        "highest_dividend",
        "biggest_gainers"
      ]
    },
    "sector": {
      "enum": [
        "any",
        "Basic Materials",
        "Communication Services",
        "Consumer Cyclical",
        "Consumer Defensive",
        "Energy",
        "Financial",
        "Healthcare",
        "Industrials",
        "Real Estate",
        "Technology",
        "Utilities"
      ],
      "type": "string",
      "default": "any",
      "description": "Business sector, for example Technology; any includes all sectors.",
      "examples": [
        "Healthcare",
        "Technology",
        "Utilities"
      ]
    },
    "signal": {
      "enum": [
        "none",
        "top_gainers",
        "top_losers",
        "new_52_week_high",
        "new_52_week_low",
        "unusual_volume",
        "most_active",
        "oversold",
        "overbought"
      ],
      "type": "string",
      "default": "none",
      "description": "Market signal, for example top_gainers.",
      "examples": [
        "top_gainers"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 20,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum number of stocks to return, for example 20. Up to 100.",
      "x-fous-developer": true,
      "examples": [
        10,
        20,
        25
      ]
    },
    "company_size": {
      "enum": [
        "any",
        "mega",
        "large",
        "mid",
        "small",
        "micro"
      ],
      "type": "string",
      "default": "any",
      "description": "Market value range, for example large ($10B–$200B).",
      "examples": [
        "mega",
        "micro"
      ]
    },
    "minimum_dividend_yield_percent": {
      "type": "number",
      "default": 0,
      "minimum": 0,
      "description": "Minimum annual dividend yield as a percentage, for example 2.5.",
      "examples": [
        2.5,
        99
      ]
    },
    "maximum_price_to_earnings_ratio": {
      "type": "number",
      "title": "Max P/E ratio",
      "minimum": 0,
      "description": "Max P/E ratio, for example 25. Omit to include any P/E.",
      "examples": [
        25
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "sort": "highest_dividend",
      "sector": "Healthcare",
      "max_results": 10,
      "minimum_dividend_yield_percent": 2.5,
      "maximum_price_to_earnings_ratio": 25
    },
    {
      "sector": "Technology",
      "max_results": 20,
      "company_size": "mega"
    },
    {
      "sector": "Utilities",
      "max_results": 20,
      "company_size": "micro",
      "minimum_dividend_yield_percent": 99
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `stocks` | array |  | Matching US stocks. |
| `stocks[].sector` | string or null | `"Healthcare"` | Business sector. |
| `stocks[].ticker` | string | `"SPOK"` | Stock symbol. |
| `stocks[].company` | string | `"Spok Holdings Inc"` | Company name. |
| `stocks[].country` | string or null | `"USA"` | Company country. |
| `stocks[].industry` | string or null | `"Health Information Services"` | Industry. |
| `stocks[].page_url` | string | `"https://finviz.com/quote.ashx?t=SPOK"` | Finviz stock page. |
| `stocks[].price_usd` | number or null | `10.37` | Price in US dollars. |
| `stocks[].volume_shares` | integer or null | `107168` | Shares traded. |
| `stocks[].market_cap_usd` | number or null | `216920000` | Market capitalization in US dollars. |
| `stocks[].change_percent_today` | number or null | `-0.86` | Current-day price change, percent. |
| `stocks[].price_to_earnings_ratio` | number or null | `17.86` | Price-to-earnings ratio. |

**Example input**

```json
{
  "sort": "highest_dividend",
  "sector": "Healthcare",
  "max_results": 10,
  "minimum_dividend_yield_percent": 2.5,
  "maximum_price_to_earnings_ratio": 25
}
```

**Example output**

```json
{
  "stocks": [
    {
      "sector": "Healthcare",
      "ticker": "SPOK",
      "company": "Spok Holdings Inc",
      "country": "USA",
      "industry": "Health Information Services",
      "page_url": "https://finviz.com/quote.ashx?t=SPOK",
      "price_usd": 10.37,
      "volume_shares": 107168,
      "market_cap_usd": 216920000,
      "change_percent_today": -0.86,
      "price_to_earnings_ratio": 17.86
    },
    {
      "sector": "Healthcare",
      "ticker": "EMBC",
      "company": "Embecta Corp",
      "country": "USA",
      "industry": "Medical Instruments & Supplies",
      "page_url": "https://finviz.com/quote.ashx?t=EMBC",
      "price_usd": 5.93,
      "volume_shares": 680936,
      "market_cap_usd": 335990000,
      "change_percent_today": 0.51,
      "price_to_earnings_ratio": 4
    },
    {
      "sector": "Healthcare",
      "ticker": "BMY",
      "company": "Bristol-Myers Squibb Co",
      "country": "USA",
      "industry": "Drug Manufacturers - General",
      "page_url": "https://finviz.com/quote.ashx?t=BMY",
      "price_usd": 63.88,
      "volume_shares": 14018716,
      "market_cap_usd": 130490000000,
      "change_percent_today": 1.62,
      "price_to_earnings_ratio": 14.07
    }
  ]
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@finviz",
  "visibility": "public",
  "operation": "get_stock_snapshot",
  "version": 1,
  "input": {
    "company": "Apple"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

body = json.loads("{\n  \"api\": \"@finviz\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_stock_snapshot\",\n  \"version\": 1,\n  \"input\": {\n    \"company\": \"Apple\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
  "api": "@finviz",
  "visibility": "public",
  "operation": "get_stock_snapshot",
  "version": 1,
  "input": {
    "company": "Apple"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

Or describe the data in plain language: send `{"api":"@finviz","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## Use cases

- Compare delayed stock metrics for a company or ticker.
- Screen US stocks by sector, size, dividend yield, or P/E ratio.
- Find stocks matching a market signal and ranking.
- Review recent insider buys or sales by company.
- Track insider trades across the market.

## FAQ

### Is Fous affiliated with Finviz?

No. Fous is not affiliated with Finviz. This workflow reads the public finviz.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. With pay-as-you-go, a credit costs 1¢; monthly plans cost less per credit.

### Do I need a Finviz account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from finviz.com when you run it; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check on Sep 29, 2026.

### What is a company’s delayed share price?

Use Get stock snapshot with a company name or US stock ticker.

### Which stocks match my screening criteria?

Use Screen stocks with filters such as sector, company size, dividend yield, or P/E ratio.

### What recent insider trades were reported?

Use List insider trades, optionally filtering by company or trade type.

## Related

- [SEC EDGAR API](https://fous.com/workflows/sec-edgar.md): SEC EDGAR provides filings, annual and quarterly financials, exact-phrase matches, up to 200 insider trades, and quarterly 13F manager holdings; older filings appear when available.
- [TradingView API](https://fous.com/workflows/tradingview.md): TradingView provides charts, markets, and technical analysis, with changing buy, sell, or neutral signals and stock screening; quotes may be delayed.
- [Stock Analysis API](https://fous.com/workflows/stock-analysis.md): Stock Analysis returns free-period company statements, statistics current as of its displayed date, typically top-25 ETF holdings, and US IPOs since 2019 with potentially missing prices or returns.
- [Yahoo Finance API](https://fous.com/workflows/yahoo-finance.md): Yahoo Finance provides quotes, movers, company financials, analyst ratings, earnings, news, and up to 5,000 price rows with adjusted returns; prices may be delayed.
- [MSN Money API](https://fous.com/workflows/msn-money.md): MSN Money provides stock quotes, key facts, financial news, and market data, including current market movers; quotes and prices may be delayed.
- [Google Finance API](https://fous.com/workflows/google-finance.md): Google Finance returns possibly delayed prices and figures, indexes, up to four movers timed by oldest quote, currency conversions, and up to five financial periods.
- [Capitol Trades API](https://fous.com/workflows/capitol-trades.md): Capitol Trades shows disclosed US congressional stock trades, with up to three years of history; recent trades are newest first and can be filtered.
- [Forbes API](https://fous.com/workflows/forbes.md): Forbes provides business news, real-time billionaire rankings and wealth that can change during the trading day, plus ranked Global 2000 companies with financial figures and company profiles.
- [All Finance workflows](https://fous.com/workflows/category/finance)