Public API · v2.0.0

StockMarketScan API

A production-ready JSON stock screener API covering screeners, options flow, chart patterns, trends and market breadth data. Choose direct API access or subscribe via the RapidAPI marketplace.

A stock screener API for your own tooling

Every screener, pattern and options flow endpoint on this page is the same one the site itself calls. If you want the model to query it for you instead of calling it yourself, the same data is exposed over MCP on the connector page.

A stock market data API for developers

Authentication is a single header, responses are plain JSON, and the endpoints below are documented with their parameters and rate limits. That makes it a stock market data API for developers who would rather query the data than read a dashboard.

Base URLhttps://stockmarketscan.com/api/v1

All changes are listed in the API changelog.

Authentication

Two authentication paths are supported. Direct API key holders generate their own credentials. RapidAPI subscribers use the marketplace’s standard headers and automatically receive Pro-tier access.

Direct API key

Generate at Settings. Requires a Basic or Pro plan.

X-API-Key: sms_xxxxxxxxxxxxxxxx# orAuthorization: Bearer sms_xxxxxxxxxxxxxxxx

RapidAPI

Pro

Subscribe on the marketplace. All subscribers get Pro tier.

X-RapidAPI-Key: ...X-RapidAPI-Host: stockmarketscan.com

Responses

Every successful JSON response is an envelope with the result in data (an array or an object) and metadata in meta. All fields are snake_case, numbers are JSON numbers, trading dates are YYYY-MM-DD, timestamps are RFC 3339 UTC, and missing values are null.

{
  "data": [
    {
      "symbol": "NVDA",
      "symbol_name": "NVIDIA Corp",
      "last_price": 181.85,
      "data_date": "2026-09-25"
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T20:15:03Z",
    "pagination": {
      "limit": 50,
      "next_cursor": "eyJ2IjoxLCJkIjoiMjAyNi0wOS0yNSIsImsiOlsiTlZEQSJdLCJmIjoiYWJjIn0",
      "total": 412
    },
    "parameters": {
      "limit": 50,
      "date": null
    }
  }
}

meta field	Meaning
`as_of`	Trading date of the underlying data. Null when there is no data.
`generated_at`	When this response was produced (RFC 3339 UTC).
`pagination`	Present on list endpoints. Follow `next_cursor` until it is null.
`parameters`	Parameters applied after defaults.

Pagination

List endpoints accept limit and cursor. Pass meta.pagination.next_cursor as cursor (or follow the Link: rel="next" header) until it is null. The first page pins the data snapshot, so a refresh while you page never mixes two snapshots. A malformed cursor, or one issued for other parameters, returns 400 INVALID_CURSOR.

pagination field	Meaning
`limit`	Page size that was applied.
`next_cursor`	Cursor for the next page; null on the last page.
`total`	Rows across all pages. Only where it is cheap and exact.

Rate Limits

Limits apply per user. Authenticated responses carry the IETF RateLimit and RateLimit-Policy headers plus the legacy X-RateLimit-* headers, and every 429 carries Retry-After. The monthly quota is shared by the REST API and the MCP server and resets on the 1st of each month (UTC): every API request counts once, and composite MCP tools such as get_stock_report make several requests. Requests that end in 400, 401, 403, 404 or 304 do not count. Public endpoints allow 30 requests per minute per IP without a key.

Plan	Per minute	Per day	Per month
Free	No API access
Basic	15	500	10,000
Pro	30	2,000	50,000
RapidAPI	Per RapidAPI plan plus a 10,000/day backend safety cap

Header	Meaning
`RateLimit`	Most constrained window, IETF format, e.g. `"minute";r=27;t=41` (r = remaining, t = seconds until reset). Absent on unauthenticated probes.
`RateLimit-Policy`	All windows of your plan, e.g. `"minute";q=30;w=60, "day";q=2000;w=86400, "month";q=50000;w=2592000`.
`Retry-After`	Seconds until the exceeded window resets. Always present on 429.
`X-RateLimit-Limit`	Legacy. Limit of the per-minute window (per-day for RapidAPI), or of the exceeded window on 429.
`X-RateLimit-Remaining`	Legacy. Requests left in that window.
`X-RateLimit-Reset`	Legacy. Window reset as Unix seconds.
`X-RateLimit-Monthly-Limit`	Legacy. Monthly quota of a direct key.
`X-RateLimit-Monthly-Remaining`	Legacy. Requests left this month.
`X-RateLimit-Monthly-Reset`	Legacy. Start of next month (UTC) as Unix seconds.

Caching

Data responses can be cached privately for 60 seconds. Send the ETag back as If-None-Match: an unchanged resource returns 304 without a body and does not count against your quota.

Header	Meaning
`ETag`	Weak validator of the body (ignoring `meta.generated_at`). Send it back as `If-None-Match`.
`Cache-Control`	`private, max-age=60` on 2xx data responses; `no-store` on errors, `/ping`, `/health` and `POST /patterns`.
`Vary`	Always `Authorization, X-API-Key`.
`X-Request-Id`	Request id. Echoes a valid inbound `X-Request-Id`, otherwise a new UUID. Same value as `request_id` in errors.

Errors

Errors are RFC 9457 application/problem+json documents. code is stable and machine-readable, request_id matches the X-Request-Id header (quote it when you report an issue), and parameter errors list each offending parameter in errors. The type URL links to the row below.

{
  "type": "https://stockmarketscan.com/docs/errors#invalid_parameter",
  "title": "Invalid parameter",
  "status": 400,
  "detail": "limit must be an integer between 1 and 500.",
  "instance": "/api/v1/screeners/golden-cross?limit=9000",
  "code": "INVALID_PARAMETER",
  "request_id": "3f2c9a1e-8b7d-4c61-9e0f-2a5b6c7d8e9f",
  "errors": [
    {
      "parameter": "limit",
      "detail": "must be an integer between 1 and 500"
    }
  ]
}

Code	Meaning
MISSING_API_KEY	401. No `X-API-Key` or `Authorization: Bearer` header.
INVALID_API_KEY_FORMAT	401. Key does not start with `sms_` or `mct_`, or is too short.
INVALID_API_KEY	401. Key or connector token not found.
INVALID_RAPIDAPI_PROXY_SECRET	401. Request did not come through the RapidAPI proxy.
FREE_TIER_NOT_ALLOWED	403. The account has no active plan.
TIER_UPGRADE_REQUIRED	403. The endpoint or screener needs a higher plan.
SCREENER_NOT_ACCESSIBLE	403. `POST /patterns` names a screener above your plan.
RATE_LIMIT_MINUTE	429. Per-minute limit reached (Basic 15, Pro 30). See `Retry-After`.
RATE_LIMIT_DAY	429. Per-day limit reached (Basic 500, Pro 2,000, RapidAPI 10,000). See `Retry-After`.
RATE_LIMIT_MONTH	429. Monthly quota reached (Basic 10,000, Pro 50,000; shared with MCP). See `Retry-After`.
RATE_LIMIT_ANONYMOUS	429. More than 30 requests per minute per IP without a credential on a public endpoint.
INVALID_PARAMETER	400. A query parameter or body field is malformed or out of range; `errors` names it.
INVALID_CURSOR	400. `cursor` is malformed or was issued for other parameters. Restart without it.
INVALID_SYMBOL	400. Symbol is not 1 to 20 characters of A-Z, 0-9, `.`, `^`, `=`, `-`.
INVALID_DATE	400. `date` is not a real calendar date in YYYY-MM-DD format.
INVALID_DATE_FROM	400. `date_from` is not a real calendar date in YYYY-MM-DD format.
INVALID_DATE_TO	400. `date_to` is not a real calendar date in YYYY-MM-DD format.
INVALID_DATE_RANGE	400. `date_from` is after `date_to`.
INVALID_SORT	400. `sort` is not one of streak, volume, callput, premium.
INVALID_SIDE	400. `side` is not one of call, put, both.
INVALID_INTERVAL	400. `interval` is not 1d or 1wk.
INVALID_RANGE	400. `range` is not an allowed value.
INVALID_CATEGORY	400. `category` is not techscience, patents, or fundingevents.
INVALID_QUERY	400. `q` is missing or longer than 60 characters.
INVALID_JSON	400. Request body is not valid JSON.
INVALID_BODY	400. Request body is not a JSON object.
MISSING_SCREENERS	400. `screeners` is missing or empty.
TOO_MANY_SCREENERS	400. More than 24 screeners requested.
INVALID_LIMIT	400. `limit` in the `POST /patterns` body is not an integer from 1 to 500.
SCREENER_NOT_FOUND	404 on `/screeners/{slug}`, 400 in the `POST /patterns` body. Unknown screener slug.
SNAPSHOT_NOT_FOUND	404. The screener has no snapshot for the requested date or cursor.
STOCK_NOT_FOUND	404. Symbol not found in any screener or candle data.
AUTH_UNAVAILABLE	503. The key store could not be reached.
RAPIDAPI_NOT_CONFIGURED	503. RapidAPI access is not configured on the server.
DB_UNHEALTHY	503. Health probe could not reach the database.
STOCK_LOOKUP_FAILED	503. Stock data sources could not be queried.
INTERNAL_ERROR	500. Unexpected error. Quote `request_id` when reporting it.

Health

Liveness and database probes. Public, no auth.

GET/ping

Public

Liveness probe

Returns immediately without touching the database. No authentication, never cached.

curl "https://stockmarketscan.com/api/v1/ping"

Response

200Service is up

dataobjectrequired

statusenum("ok")required

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)nullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPagination

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobject

Parameters applied after defaults.

{
  "data": {
    "status": "ok"
  },
  "meta": {
    "generated_at": "2026-09-28T10:00:00Z"
  }
}

Errors

500

GET/health

Public

Health check

Service status and database reachability. No authentication, never cached.

curl "https://stockmarketscan.com/api/v1/health"

Response

200Service healthy

dataHealthrequired

statusenum("ok")required

versionstringrequired

dbobjectrequired

reachablebooleanrequired

latency_msintegerrequired

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)nullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPagination

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobject

Parameters applied after defaults.

{
  "data": {
    "status": "ok",
    "version": "v1",
    "db": {
      "reachable": true,
      "latency_ms": 9
    }
  },
  "meta": {
    "generated_at": "2026-09-28T10:00:00Z"
  }
}

Errors

500503

Screeners

24 curated screeners with full table data, column metadata, and tier requirements.

GET/screeners

Public

List all screeners

Metadata for all 24 screeners, including each row field with its JSON value_type, and the tier each screener requires. The API key is optional: without one only the free screeners report accessible: true. Not paginated.

curl "https://stockmarketscan.com/api/v1/screeners"

Parameters

Name	In	Type	Notes
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Screener catalog

dataarray<Screener>required

slugScreenerSlugrequired

namestringrequired

descriptionstringrequired

categoryScreenerCategoryrequired

tierTierrequired

accessiblebooleanrequired

Whether your plan can read this screener's rows.

columnsarray<ScreenerColumn>required

Fields of each row. Every row also carries data_date.

keystringrequired

labelstringrequired

Display type on stockmarketscan.com.

value_typeenum("number" | "string" | "date")required

JSON type of the value in rows (date = YYYY-MM-DD). Any value may be null except the row key.

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)nullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPagination

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobject

Parameters applied after defaults.

caller_tierTierrequired

totalintegerrequired

Number of screeners.

accessibleintegerrequired

Screeners whose rows your plan can read.

{
  "data": [
    {
      "slug": "golden-cross",
      "name": "Golden Cross",
      "description": "Stocks whose 50-day moving average just crossed above the 200-day moving average",
      "category": "technical",
      "tier": "basic",
      "accessible": true,
      "columns": [
        {
          "key": "symbol",
          "label": "Symbol",
          "type": "text",
          "value_type": "string"
        },
        {
          "key": "last_price",
          "label": "Price",
          "type": "price",
          "value_type": "number"
        },
        {
          "key": "macd_50_to_200d_new_signal",
          "label": "Signal",
          "type": "signal",
          "value_type": "string"
        }
      ]
    }
  ],
  "meta": {
    "generated_at": "2026-09-25T20:15:03Z",
    "caller_tier": "pro",
    "total": 24,
    "accessible": 24
  }
}

Errors

401403429500503

GET/screeners/{slug}

Basic+

Screener rows

One row per symbol (per exchange for market-momentum) from a single screener snapshot, ordered by that key ascending. The first page uses the latest snapshot unless date is given; its cursor pins that snapshot, so later pages never mix snapshots. The fields of each screener are the ScreenerRow<Slug> schemas. The tier required depends on the screener (see tier in the catalog).

curl "https://stockmarketscan.com/api/v1/screeners/golden-cross" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`slug`*	path	ScreenerSlug	Screener slug from `GET /screeners`.
`limit`	query	integer	Page size.default: 50 · 1 to 500
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`date`	query	string (date)	Snapshot date. Defaults to the latest snapshot.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Screener rows

dataarray<ScreenerRow>required

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

limitintegerrequired

datestring (date)requirednullable

screenerobjectrequired

slugScreenerSlugrequired

namestringrequired

tierTierrequired

{
  "data": [
    {
      "symbol": "NVDA",
      "symbol_name": "NVIDIA Corp",
      "last_price": 181.85,
      "macd_50_to_200d_new_signal": "Buy",
      "average_volume_20d": 2069031,
      "exchange": "NASDAQ",
      "industry": "Semiconductors",
      "data_date": "2026-09-25"
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T20:15:03Z",
    "screener": {
      "slug": "golden-cross",
      "name": "Golden Cross",
      "tier": "basic"
    },
    "pagination": {
      "limit": 50,
      "next_cursor": "eyJ2IjoxLCJkIjoiMjAyNi0wOS0yNSIsImsiOlsiTlZEQSJdLCJmIjoiYWJjIn0",
      "total": 412
    },
    "parameters": {
      "limit": 50,
      "date": null
    }
  }
}

Errors

400401403404429500503

Patterns

Chart pattern detection per symbol or across screener cohorts.

GET/patterns/{symbol}

Basic+

Detected patterns for a symbol

The most recent pattern computation for one symbol. When nothing has been computed, patterns is empty and computed_at is null.

curl "https://stockmarketscan.com/api/v1/patterns/AAPL" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`symbol`*	path	string	Ticker symbol, case-insensitive.
`interval`	query	enum("1d" \| "1wk")	Candle interval.default: "1d"
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Pattern list

dataSymbolPatternsrequired

symbolstringrequired

intervalenum("1d" | "1wk")required

computed_atstring (date-time)requirednullable

When the patterns were computed; null when never.

candle_countintegerrequirednullable

Candles the detection ran on.

patternsarray<Pattern>required

idPatternIdrequired

namestringrequired

typeenum("bullish" | "bearish" | "neutral")required

Conventional direction of the chart pattern.

categoryenum("reversal" | "continuation" | "harmonic" | "wave")required

confidencenumberrequired0 to 100 · nullable

pointsarray<PatternPoint>required

indexintegerrequirednullable

Candle index within the analysed window.

datestring (date)requirednullable

pricenumberrequirednullable

labelstringrequirednullable

linesarray<PatternLine>required

pointsarray<object>required

datestring (date)requirednullable

pricenumberrequirednullable

styleenum("solid" | "dashed" | "dotted")requirednullable

target_pricenumberrequirednullable

Measured-move price level; null when not defined for the pattern.

last_structural_pointPatternPoint | anyrequired

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPagination

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobject

Parameters applied after defaults.

{
  "data": {
    "symbol": "NVDA",
    "interval": "1d",
    "computed_at": "2026-09-25T21:05:11Z",
    "candle_count": 250,
    "patterns": [
      {
        "id": "cup_handle",
        "name": "Cup and Handle",
        "type": "bullish",
        "category": "continuation",
        "confidence": 72,
        "points": [
          {
            "index": 180,
            "date": "2026-06-02",
            "price": 142.1,
            "label": "Left rim"
          },
          {
            "index": 246,
            "date": "2026-09-19",
            "price": 176.9,
            "label": "Right rim"
          }
        ],
        "lines": [
          {
            "points": [
              {
                "date": "2026-06-02",
                "price": 142.1
              },
              {
                "date": "2026-09-19",
                "price": 176.9
              }
            ],
            "style": "dashed"
          }
        ],
        "target_price": 225.4,
        "last_structural_point": {
          "index": 246,
          "date": "2026-09-19",
          "price": 176.9,
          "label": null
        }
      }
    ]
  },
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T21:10:00Z"
  }
}

Errors

400401403429500503

POST/patterns

Basic+

Pattern search across screeners

For each requested screener, takes the stocks on its latest snapshot and returns those with a recent pattern (computed within 3 days for 1d, 14 days for 1wk). Unknown slugs are 400 SCREENER_NOT_FOUND, screeners above your plan are 403 SCREENER_NOT_ACCESSIBLE, unknown pattern ids are 400 INVALID_PARAMETER. Grouped per screener and capped by limit per group; not cursor-paginated. Not cached.

curl -X POST "https://stockmarketscan.com/api/v1/patterns" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"screeners":["hot-prospects","golden-cross"]}'

Request body *

screenersarray<ScreenerSlug>required

patternsarray<PatternId>

Pattern ids to keep. Empty or omitted means any pattern.

intervalenum("1d" | "1wk")default: "1d"

limitintegerdefault: 100 · 1 to 500

Max stocks per screener group.

Response

200Pattern search results

dataarray<PatternSearchGroup>required

screener_slugScreenerSlugrequired

screener_namestringrequired

countintegerrequired

Matches before truncation to limit.

truncatedbooleanrequired

True when stocks were cut to limit.

stocksarray<PatternSearchStock>required

symbolstringrequired

symbol_namestringrequirednullable

exchangestringrequirednullable

industrystringrequirednullable

last_pricenumberrequirednullable

volumenumberrequirednullable

data_datestring (date)requirednullable

matched_patternsarray<PatternHit>required

idPatternIdrequired

labelstringrequired

directionenum("bullish" | "bearish" | "neutral")required

strengthnumberrequirednullable

Pattern confidence 0 to 100.

forming_statusenum("forming" | "near-breakout")required

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPagination

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

screenersarray<string>required

patternsarray<string>required

intervalenum("1d" | "1wk")required

limitintegerrequired

total_unique_stocksintegerrequired

Unique symbols matched across all groups, before truncation.

{
  "data": [
    {
      "screener_slug": "hot-prospects",
      "screener_name": "Hot Prospects",
      "count": 1,
      "truncated": false,
      "stocks": [
        {
          "symbol": "NVDA",
          "symbol_name": "NVIDIA Corp",
          "exchange": "NASDAQ",
          "industry": "Semiconductors",
          "last_price": 181.85,
          "volume": 201345600,
          "data_date": "2026-09-25",
          "matched_patterns": [
            {
              "id": "cup_handle",
              "label": "Cup and Handle",
              "direction": "bullish",
              "strength": 72,
              "forming_status": "forming"
            }
          ]
        }
      ]
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T21:10:00Z",
    "total_unique_stocks": 1,
    "parameters": {
      "screeners": [
        "hot-prospects"
      ],
      "patterns": [
        "cup_handle"
      ],
      "interval": "1d",
      "limit": 100
    }
  }
}

Errors

400401403429500503

Options Flow

Daily aggregated options flow per symbol, per-symbol timelines, ranked daily flow records with subsequent price data, daily market-wide call/put statistics, and unusual contract activity. Pro tier.

GET/options-flow

Pro

Daily flow overview

Aggregated unusual-options flow per symbol for one trading day, plus market-wide totals for that day in meta.market_stats. A date without data returns an empty data array. Orders: streak = consecutive_days desc, total_volume desc, symbol asc; volume = total_volume desc, symbol asc; callput = call/put volume ratio desc, symbol asc; premium = call + put premium desc, symbol asc. Nulls sort last. The cursor pins the trading day. Pro tier required.

curl "https://stockmarketscan.com/api/v1/options-flow" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`date`	query	string (date)	Trading date. Defaults to the latest available day.
`sort`	query	enum("streak" \| "volume" \| "callput" \| "premium")	default: "streak"
`limit`	query	integer	default: 100 · 1 to 500
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Options flow for one day

dataarray<OptionsFlowDay>required

symbolstringrequired

data_datestring (date)required

stock_pricenumberrequirednullable

Underlying price.

call_contractsintegerrequirednullable

Number of unusual call contracts.

call_volumeintegerrequirednullable

call_open_interestintegerrequirednullable

call_avg_vol_oinumberrequirednullable

Average volume/OI ratio of the calls.

call_avg_ivnumberrequirednullable

Average implied volatility of the calls, in percent.

call_avg_deltanumberrequirednullable

call_total_premiumnumberrequirednullable

Sum of last_price * volume * 100 for calls, USD.

put_contractsintegerrequirednullable

put_volumeintegerrequirednullable

put_open_interestintegerrequirednullable

put_avg_vol_oinumberrequirednullable

put_avg_ivnumberrequirednullable

put_avg_deltanumberrequirednullable

Average absolute delta of the puts.

put_total_premiumnumberrequirednullable

total_volumeintegerrequirednullable

total_oiintegerrequirednullable

call_put_volume_rationumberrequirednullable

Call volume divided by put volume. Null without puts.

call_put_oi_rationumberrequirednullable

Call open interest divided by put open interest.

net_deltanumberrequirednullable

avg_days_to_expirynumberrequirednullable

consecutive_daysintegerrequirednullable

Consecutive trading days up to this one with the same call/put regime.

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

datestring (date)requirednullable

sortenum("streak" | "volume" | "callput" | "premium")required

limitintegerrequired

market_statsOptionsFlowMarketStats | anyrequired

available_datesarray<string (date)>required

Up to 60 most recent trading dates with data, newest first.

{
  "data": [
    {
      "symbol": "NVDA",
      "data_date": "2026-09-25",
      "stock_price": 181.85,
      "call_contracts": 41,
      "call_volume": 912345,
      "call_open_interest": 1543210,
      "call_avg_vol_oi": 2.41,
      "call_avg_iv": 48.2,
      "call_avg_delta": 0.41,
      "call_total_premium": 98234500,
      "put_contracts": 12,
      "put_volume": 301234,
      "put_open_interest": 823456,
      "put_avg_vol_oi": 1.8,
      "put_avg_iv": 51.3,
      "put_avg_delta": 0.37,
      "put_total_premium": 21345000,
      "total_volume": 1213579,
      "total_oi": 2366666,
      "call_put_volume_ratio": 3.03,
      "call_put_oi_ratio": 1.87,
      "net_delta": 0.21,
      "avg_days_to_expiry": 17.4,
      "consecutive_days": 6
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T21:10:00Z",
    "market_stats": {
      "total_symbols": 412,
      "total_market_volume": 58123456,
      "total_call_volume": 33456789,
      "total_put_volume": 24666667,
      "market_call_put_ratio": 1.36,
      "avg_streak": 3.42,
      "max_streak": 19
    },
    "available_dates": [
      "2026-09-25",
      "2026-09-24"
    ],
    "pagination": {
      "limit": 100,
      "next_cursor": null,
      "total": 412
    },
    "parameters": {
      "date": null,
      "sort": "streak",
      "limit": 100
    }
  }
}

Errors

400401403429500503

GET/options-flow/{symbol}

Pro

Per-symbol timeline

Daily flow rows for one symbol, newest first (data_date desc). Pro tier required.

curl "https://stockmarketscan.com/api/v1/options-flow/AAPL" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`symbol`*	path	string	Ticker symbol, case-insensitive.
`limit`	query	integer	Trading days per page.default: 60 · 1 to 365
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Timeline rows

dataarray<OptionsFlowDay>required

symbolstringrequired

data_datestring (date)required

stock_pricenumberrequirednullable

Underlying price.

call_contractsintegerrequirednullable

Number of unusual call contracts.

call_volumeintegerrequirednullable

call_open_interestintegerrequirednullable

call_avg_vol_oinumberrequirednullable

Average volume/OI ratio of the calls.

call_avg_ivnumberrequirednullable

Average implied volatility of the calls, in percent.

call_avg_deltanumberrequirednullable

call_total_premiumnumberrequirednullable

Sum of last_price * volume * 100 for calls, USD.

put_contractsintegerrequirednullable

put_volumeintegerrequirednullable

put_open_interestintegerrequirednullable

put_avg_vol_oinumberrequirednullable

put_avg_ivnumberrequirednullable

put_avg_deltanumberrequirednullable

Average absolute delta of the puts.

put_total_premiumnumberrequirednullable

total_volumeintegerrequirednullable

total_oiintegerrequirednullable

call_put_volume_rationumberrequirednullable

Call volume divided by put volume. Null without puts.

call_put_oi_rationumberrequirednullable

Call open interest divided by put open interest.

net_deltanumberrequirednullable

avg_days_to_expirynumberrequirednullable

consecutive_daysintegerrequirednullable

Consecutive trading days up to this one with the same call/put regime.

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

symbolstringrequired

limitintegerrequired

{
  "data": [
    {
      "symbol": "NVDA",
      "data_date": "2026-09-25",
      "stock_price": 181.85,
      "call_contracts": 41,
      "call_volume": 912345,
      "call_open_interest": 1543210,
      "call_avg_vol_oi": 2.41,
      "call_avg_iv": 48.2,
      "call_avg_delta": 0.41,
      "call_total_premium": 98234500,
      "put_contracts": 12,
      "put_volume": 301234,
      "put_open_interest": 823456,
      "put_avg_vol_oi": 1.8,
      "put_avg_iv": 51.3,
      "put_avg_delta": 0.37,
      "put_total_premium": 21345000,
      "total_volume": 1213579,
      "total_oi": 2366666,
      "call_put_volume_ratio": 3.03,
      "call_put_oi_ratio": 1.87,
      "net_delta": 0.21,
      "avg_days_to_expiry": 17.4,
      "consecutive_days": 6
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T21:10:00Z",
    "pagination": {
      "limit": 60,
      "next_cursor": null
    },
    "parameters": {
      "symbol": "NVDA",
      "limit": 60
    }
  }
}

Errors

400401403429500503

GET/options-flow/signals

Pro

Ranked daily flow records

Stored flow records with screener confluence and subsequent price data, ordered by signal_date desc, strength_score desc, symbol asc, signal_type asc. date_from and date_to are inclusive and either may be sent alone. Without both, the window starts 60 days before the latest record day; the effective start is in meta.parameters.date_from and is pinned by the cursor. Data only, not a recommendation. Pro tier required.

curl "https://stockmarketscan.com/api/v1/options-flow/signals" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`date_from`	query	string (date)
`date_to`	query	string (date)
`limit`	query	integer	default: 500 · 1 to 2000
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Flow records

dataarray<OptionsFlowRecord>required

symbolstringrequired

signal_datestring (date)required

Trading day of the record.

Classification of the day's flow by call/put ratio, streak, and volume.

sideenum("bullish" | "bearish")required

bullish when the call/put volume ratio is above 1.

call_put_rationumberrequirednullable

Call/put volume ratio.

call_put_oi_rationumberrequirednullable

Call/put open-interest ratio.

near_earningsbooleanrequired

An earnings report falls within 14 days after the record date.

next_earnings_datestring (date)requirednullable

call_volumeintegerrequired

put_volumeintegerrequired

total_volumeintegerrequired

total_oiintegerrequired

call_avg_ivnumberrequirednullable

Average implied volatility of calls, in percent.

put_avg_ivnumberrequirednullable

total_premiumnumberrequirednullable

Call plus put premium, USD.

consecutive_daysintegerrequired

Streak length of the same flow regime up to the record date.

signal_pricenumberrequirednullable

Underlying price on the record date.

entry_pricenumberrequirednullable

Open of the first daily candle after the record was published. Null until that candle exists.

entry_datestring (date)requirednullable

net_deltanumberrequirednullable

avg_days_to_expirynumberrequirednullable

strength_scoreintegerrequired0 to 13

Composite ranking score.

bullish_screener_hitsintegerrequired

bearish_screener_hitsintegerrequired

bullish_screener_listarray<string>required

bearish_screener_listarray<string>required

market_breadth_scoreintegerrequired0 to 100 · nullable

market_call_put_rationumberrequirednullable

market_contextenum("bullish_only" | "bearish_only" | "mixed")requirednullable

current_pricenumberrequirednullable

Latest daily close.

high_sincenumberrequirednullable

Highest high since entry_date.

low_sincenumberrequirednullable

Lowest low since entry_date.

price_change_pctnumberrequirednullable

(current_price - entry_price) / entry_price * 100.

max_gain_pctnumberrequirednullable

(high_since - entry_price) / entry_price * 100.

max_drawdown_pctnumberrequirednullable

(low_since - entry_price) / entry_price * 100.

max_high_datestring (date)requirednullable

min_low_datestring (date)requirednullable

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

date_fromstring (date)requirednullable

date_tostring (date)requirednullable

limitintegerrequired

{
  "data": [
    {
      "symbol": "NVDA",
      "signal_date": "2026-09-25",
      "signal_type": "strong_bullish",
      "side": "bullish",
      "call_put_ratio": 3.03,
      "call_put_oi_ratio": 1.87,
      "near_earnings": false,
      "next_earnings_date": "2026-11-19",
      "call_volume": 912345,
      "put_volume": 301234,
      "total_volume": 1213579,
      "total_oi": 2366666,
      "call_avg_iv": 48.2,
      "put_avg_iv": 51.3,
      "total_premium": 119579500,
      "consecutive_days": 6,
      "signal_price": 181.85,
      "entry_price": null,
      "entry_date": null,
      "net_delta": 0.21,
      "avg_days_to_expiry": 17.4,
      "strength_score": 11,
      "bullish_screener_hits": 2,
      "bearish_screener_hits": 0,
      "bullish_screener_list": [
        "golden-cross",
        "top-tech-stocks"
      ],
      "bearish_screener_list": [],
      "market_breadth_score": 61,
      "market_call_put_ratio": 1.36,
      "market_context": "mixed",
      "current_price": 181.85,
      "high_since": null,
      "low_since": null,
      "price_change_pct": null,
      "max_gain_pct": null,
      "max_drawdown_pct": null,
      "max_high_date": null,
      "min_low_date": null
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T21:10:00Z",
    "pagination": {
      "limit": 500,
      "next_cursor": null
    },
    "parameters": {
      "date_from": "2026-07-27",
      "date_to": null,
      "limit": 500
    }
  }
}

Errors

400401403429500503

GET/options-flow/sentiment

Pro

Daily market call/put statistics

One row per trading day, newest first. date_from and date_to are inclusive and either may be sent alone; without both, the last 60 days before the latest day. Pro tier required.

curl "https://stockmarketscan.com/api/v1/options-flow/sentiment" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`date_from`	query	string (date)
`date_to`	query	string (date)
`limit`	query	integer	default: 100 · 1 to 1000
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Daily statistics

dataarray<SentimentDay>required

datestring (date)required

market_breadth_scoreintegerrequirednullable

Combined advance/decline and new-highs/new-lows score, 0 to 100.

market_call_put_rationumberrequirednullable

Market-wide call volume divided by put volume.

contextenum("bullish_only" | "bearish_only" | "mixed")required

bullish_countintegerrequired

bearish_countintegerrequired

sentiment_scoreintegerrequired0 to 100

clamp(round((market_call_put_ratio - 0.5) * 100), 0, 100); 50 when the ratio is missing.

sentiment_labelenum("bullish" | "neutral" | "bearish")required

65 and above bullish, 45 to 64 neutral, below 45 bearish.

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

date_fromstring (date)requirednullable

date_tostring (date)requirednullable

limitintegerrequired

{
  "data": [
    {
      "date": "2026-09-25",
      "market_breadth_score": 61,
      "market_call_put_ratio": 1.36,
      "context": "mixed",
      "bullish_count": 7,
      "bearish_count": 2,
      "sentiment_score": 86,
      "sentiment_label": "bullish"
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T21:10:00Z",
    "pagination": {
      "limit": 100,
      "next_cursor": null
    },
    "parameters": {
      "date_from": "2026-07-27",
      "date_to": null,
      "limit": 100
    }
  }
}

Errors

400401403429500503

GET/options-flow/unusual

Pro

Unusual contract activity

Individual option contracts from the latest trading day, ranked by vol/OI times ln(premium), descending (ties by contract id). All filters apply before paging. Fixed floor: open interest at least 100. The cursor pins the trading day. Pro tier required.

curl "https://stockmarketscan.com/api/v1/options-flow/unusual" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`symbol`	query	string	Only contracts on this underlying.
`side`	query	enum("call" \| "put" \| "both")	Case-insensitive.default: "both"
`min_vol_oi`	query	number	default: 1.5 · min 0
`min_premium_usd`	query	number	default: 25000 · min 0
`max_dte`	query	integer	Maximum days to expiration. No filter when omitted.0 to 3000
`limit`	query	integer	default: 300 · 1 to 1000
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Unusual contracts

dataarray<UnusualContract>required

symbolstringrequired

option_symbolstringrequirednullable

symbol_typeenum("Call" | "Put")requirednullable

base_last_pricenumberrequirednullable

Underlying price.

strike_pricenumberrequirednullable

expiration_datestring (date)requirednullable

days_to_expirationintegerrequirednullable

last_pricenumberrequirednullable

bid_pricenumberrequirednullable

midpointnumberrequirednullable

ask_pricenumberrequirednullable

volumeintegerrequirednullable

open_interestintegerrequirednullable

volume_oi_rationumberrequirednullable

volatilitynumberrequirednullable

Implied volatility in percent.

deltanumberrequirednullable

trade_timestringrequirednullable

As delivered by the source: a date ("09/03/26") or a time ("16:00 ET").

data_datestring (date)required

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

symbolstringrequirednullable

sideenum("call" | "put" | "both")required

min_vol_oinumberrequired

min_premium_usdnumberrequired

max_dteintegerrequirednullable

limitintegerrequired

{
  "data": [
    {
      "symbol": "NVDA",
      "option_symbol": "NVDA|20261016|190.00C",
      "symbol_type": "Call",
      "base_last_price": 181.85,
      "strike_price": 190,
      "expiration_date": "2026-10-16",
      "days_to_expiration": 21,
      "last_price": 4.35,
      "bid_price": 4.3,
      "midpoint": 4.35,
      "ask_price": 4.4,
      "volume": 11025,
      "open_interest": 3872,
      "volume_oi_ratio": 2.85,
      "volatility": 45.85,
      "delta": 0.3672,
      "trade_time": "16:00 ET",
      "data_date": "2026-09-25"
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T21:10:00Z",
    "pagination": {
      "limit": 300,
      "next_cursor": null
    },
    "parameters": {
      "symbol": null,
      "side": "both",
      "min_vol_oi": 1.5,
      "min_premium_usd": 25000,
      "max_dte": null,
      "limit": 300
    }
  }
}

Errors

400401403429500503

Trends

AI-detected trending topics and cross-category connections. Pro tier.

GET/trends

Pro

AI-detected topics

Trending topics of one category. Choose one window: date (one day), latest=1 (the most recent day), or days (the last N days, the default with 10). Sending more than one is 400. Ordered by date desc, weight desc, topic asc. Pro tier required.

curl "https://stockmarketscan.com/api/v1/trends" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`category`	query	enum("techscience" \| "patents" \| "fundingevents")	default: "techscience"
`date`	query	string (date)
`latest`	query	enum("1" \| "0" \| "true" \| "false")	`1` or `true` returns only the most recent day.
`days`	query	integer	default: 10 · 1 to 180
`limit`	query	integer	default: 500 · 1 to 1000
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Topics

dataarray<TrendTopic>required

datestring (date)required

topicstringrequired

weightnumberrequired

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

categoryenum("techscience" | "patents" | "fundingevents")required

datestring (date)requirednullable

latestbooleanrequired

daysintegerrequirednullable

limitintegerrequired

{
  "data": [
    {
      "date": "2026-09-25",
      "topic": "Solid-state batteries",
      "weight": 0.82
    },
    {
      "date": "2026-09-25",
      "topic": "Photonic interconnects",
      "weight": 0.64
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T21:10:00Z",
    "pagination": {
      "limit": 500,
      "next_cursor": null
    },
    "parameters": {
      "category": "techscience",
      "date": null,
      "latest": true,
      "days": null,
      "limit": 500
    }
  }
}

Errors

400401403429500503

GET/trend-connections

Pro

Cross-category connections

Model-validated links between topics of different categories. Choose one window: date, latest=1, or days (default 14). Sending more than one is 400. Ordered by date desc, strength desc. Pro tier required.

curl "https://stockmarketscan.com/api/v1/trend-connections" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`date`	query	string (date)
`latest`	query	enum("1" \| "0" \| "true" \| "false")
`days`	query	integer	default: 14 · 1 to 90
`limit`	query	integer	default: 200 · 1 to 1000
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Connections

dataarray<TrendConnection>required

datestring (date)required

source_categoryenum("techscience" | "patents" | "fundingevents")required

source_topicstringrequired

target_categoryenum("techscience" | "patents" | "fundingevents")required

target_topicstringrequired

strengthnumberrequired0 to 1

rationalestringrequirednullable

Model-written explanation of the link.

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

datestring (date)requirednullable

latestbooleanrequired

daysintegerrequirednullable

limitintegerrequired

{
  "data": [
    {
      "date": "2026-09-25",
      "source_category": "techscience",
      "source_topic": "Solid-state batteries",
      "target_category": "fundingevents",
      "target_topic": "Battery startup Series C rounds",
      "strength": 0.78,
      "rationale": "Both describe commercial scale-up of solid electrolyte cells."
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T21:10:00Z",
    "pagination": {
      "limit": 200,
      "next_cursor": null
    },
    "parameters": {
      "date": null,
      "latest": true,
      "days": null,
      "limit": 200
    }
  }
}

Errors

400401403429500503

Market Breadth

NYSE and NASDAQ advance/decline and new-highs/new-lows data.

GET/market-momentum

Basic+

NYSE/NASDAQ advance-decline data

One row per exchange per trading day, ordered by data_date desc, exchange asc. Send date for one day, or date_from and/or date_to for an inclusive range (either may be sent alone), but not both kinds. Without dates: the last 7 trading days (the window is pinned by the cursor).

curl "https://stockmarketscan.com/api/v1/market-momentum" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`date`	query	string (date)
`date_from`	query	string (date)
`date_to`	query	string (date)
`limit`	query	integer	default: 100 · 1 to 1000
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Market breadth rows

dataarray<MarketMomentumRow>required

data_datestring (date)required

exchangestringrequired

advancing_issuesnumberrequirednullable

declining_issuesnumberrequirednullable

unchanged_issuesnumberrequirednullable

percent_advancing_issuesnumberrequirednullable

Percent, 63 means 63%.

percent_declining_issuesnumberrequirednullable

percent_unchanged_issuesnumberrequirednullable

new_highsnumberrequirednullable

new_lowsnumberrequirednullable

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

datestring (date)requirednullable

date_fromstring (date)requirednullable

date_tostring (date)requirednullable

limitintegerrequired

{
  "data": [
    {
      "data_date": "2026-09-25",
      "exchange": "NASDAQ",
      "advancing_issues": 1706,
      "declining_issues": 1315,
      "unchanged_issues": 110,
      "percent_advancing_issues": 54,
      "percent_declining_issues": 42,
      "percent_unchanged_issues": 4,
      "new_highs": 64,
      "new_lows": 105
    },
    {
      "data_date": "2026-09-25",
      "exchange": "NYSE",
      "advancing_issues": 1174,
      "declining_issues": 658,
      "unchanged_issues": 40,
      "percent_advancing_issues": 63,
      "percent_declining_issues": 35,
      "percent_unchanged_issues": 2,
      "new_highs": 63,
      "new_lows": 29
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T21:10:00Z",
    "pagination": {
      "limit": 100,
      "next_cursor": null
    },
    "parameters": {
      "date": null,
      "date_from": "2026-09-17",
      "date_to": null,
      "limit": 100
    }
  }
}

Errors

400401403429500503

Stock Data

Stock metadata and OHLCV candles for any supported symbol.

GET/stocks/{symbol}

Public

Stock metadata

Name, exchange, industry, last price and daily percent change of one symbol, taken from the newest screener snapshot that contains it (field by field), otherwise from the latest daily candle. Fields come only from the screeners available on the caller's plan. No API key required (30 requests per minute per IP without one).

curl "https://stockmarketscan.com/api/v1/stocks/AAPL"

Parameters

Name	In	Type	Notes
`symbol`*	path	string	Ticker symbol, case-insensitive.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Stock metadata

dataStockInforequired

symbolstringrequired

symbol_namestringrequirednullable

last_pricenumberrequirednullable

percent_changenumberrequirednullable

Daily change in percent: 1.27 means +1.27%.

exchangestringrequirednullable

industrystringrequirednullable

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPagination

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobject

Parameters applied after defaults.

{
  "data": {
    "symbol": "NVDA",
    "symbol_name": "NVIDIA Corp",
    "last_price": 181.85,
    "percent_change": 1.27,
    "exchange": "NASDAQ",
    "industry": "Semiconductors"
  },
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T20:15:03Z"
  }
}

Errors

400401404429500503

GET/stocks/{symbol}/candles

Basic+

OHLCV candles

Daily or weekly candles, oldest first. meta.pagination.total counts all candles in the range.

curl "https://stockmarketscan.com/api/v1/stocks/AAPL/candles" \
  -H "X-API-Key: $STOCKMARKETSCAN_API_KEY"

Parameters

Name	In	Type	Notes
`symbol`*	path	string	Ticker symbol, case-insensitive.
`interval`	query	enum("1d" \| "1wk")	Candle interval.default: "1d"
`range`	query	string	`1d`, `5d`, `1y`, `2y`, `5y`, `max` (10 years), or `{N}mo` with N from 1 to 240.default: "6mo"
`limit`	query	integer	default: 1000 · 1 to 5000
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Candles

dataarray<Candle>required

datestring (date)required

Trading day (weekly candles use the Monday of the week).

opennumberrequired

highnumberrequired

lownumberrequired

closenumberrequired

volumenumberrequired

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)requirednullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

symbolstringrequired

intervalenum("1d" | "1wk")required

rangestringrequired

limitintegerrequired

{
  "data": [
    {
      "date": "2026-09-24",
      "open": 177.2,
      "high": 180.1,
      "low": 176.9,
      "close": 179.56,
      "volume": 188234500
    },
    {
      "date": "2026-09-25",
      "open": 179.9,
      "high": 182.4,
      "low": 179.1,
      "close": 181.85,
      "volume": 201345600
    }
  ],
  "meta": {
    "as_of": "2026-09-25",
    "generated_at": "2026-09-25T20:15:03Z",
    "pagination": {
      "limit": 1000,
      "next_cursor": null,
      "total": 2
    },
    "parameters": {
      "symbol": "NVDA",
      "interval": "1d",
      "range": "5d",
      "limit": 1000
    }
  }
}

Errors

400401403429500503

Search

Symbol and company-name search plus reverse screener lookup. Public with a per-IP limit; an API key lifts it.

GET/search/symbols

Public

Symbol and company-name search

Finds tickers by symbol prefix or company-name substring. Exact symbol prefix matches come first, then shorter symbols, then alphabetical. No API key required (30 requests per minute per IP without one).

curl "https://stockmarketscan.com/api/v1/search/symbols?q=Apple"

Parameters

Name	In	Type	Notes
`q`*	query	string	Search text (symbol prefix or part of the company name), 1 to 60 characters.
`limit`	query	integer	default: 10 · 1 to 50
`cursor`	query	string	Opaque cursor from `meta.pagination.next_cursor` of the previous page. Omit for the first page.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Matching symbols

dataarray<SymbolMatch>required

symbolstringrequired

namestringrequirednullable

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)nullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPaginationrequired

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

qstringrequired

limitintegerrequired

{
  "data": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc."
    },
    {
      "symbol": "APLE",
      "name": "Apple Hospitality REIT Inc."
    }
  ],
  "meta": {
    "generated_at": "2026-09-25T20:15:03Z",
    "pagination": {
      "limit": 2,
      "next_cursor": "eyJ2IjoxLCJkIjpudWxsLCJrIjpbMSw0LCJBUExFIl0sImYiOiJ4In0"
    },
    "parameters": {
      "q": "Apple",
      "limit": 2
    }
  }
}

Errors

400401429500503

GET/search/screeners

Public

Reverse screener lookup

Which screeners contain a symbol on their latest snapshot, limited to the screeners your plan can access (the 3 free-tier screeners are always included). Returns membership only, never rows. Not paginated (at most 23 screeners). No API key required (30 requests per minute per IP without one).

curl "https://stockmarketscan.com/api/v1/search/screeners?symbol=NVDA"

Parameters

Name	In	Type	Notes
`symbol`*	query	string	Ticker symbol, case-insensitive.
`If-None-Match`	header	string	ETag of a previous response. An unchanged resource returns 304 without a body and without a quota charge.

Response

200Screeners containing the symbol

dataarray<ScreenerMembership>required

slugScreenerSlugrequired

namestringrequired

categoryScreenerCategoryrequired

tierTierrequired

metaobjectrequired

Response metadata. Endpoint-specific keys are documented per operation.

as_ofstring (date)nullable

Trading date of the underlying data. Null when there is no data.

generated_atstring (date-time)required

When this response was produced (RFC 3339 UTC).

paginationPagination

Present on list endpoints. Follow next_cursor until it is null.

limitintegerrequiredmin 1

Page size that was applied.

next_cursorstringrequirednullable

Cursor for the next page; null on the last page.

totalintegermin 0

Rows across all pages. Only where it is cheap and exact.

parametersobjectrequired

symbolstringrequired

{
  "data": [
    {
      "slug": "golden-cross",
      "name": "Golden Cross",
      "category": "technical",
      "tier": "basic"
    },
    {
      "slug": "top-tech-stocks",
      "name": "Top Tech Stocks",
      "category": "fundamental",
      "tier": "free"
    }
  ],
  "meta": {
    "generated_at": "2026-09-25T20:15:03Z",
    "parameters": {
      "symbol": "NVDA"
    }
  }
}

Errors

400401429500503