{ "openapi": "3.1.0", "info": { "title": "Suros public API", "version": "1.2.0", "description": "Read-only market data behind a Suros API key. Every value is upstream data as the source last published it, and a quote carries its exchange delay (delayMin) and time (asOf); when a source cannot be reached the endpoint answers {\"source\":\"unavailable\"} rather than a made-up number. API keys come with a subscription. They are created on the account page, carry the plan's rate tier, are refused while the account has no subscription, and are counted per key per day.", "contact": { "name": "Suros", "url": "https://surossystems.com" } }, "servers": [ { "url": "https://surossystems.com", "description": "production" } ], "tags": [ { "name": "market", "description": "Market data endpoints, one per handler." } ], "security": [ { "apiKey": [] }, { "apiKeyHeader": [] } ], "paths": { "/api/v1/quote": { "get": { "operationId": "quote", "summary": "Last price for one or more symbols", "description": "Quotes, each with its exchange delay in minutes (delayMin, 0 where the exchange is real time) and the time of its last trade (asOf). A symbol the upstream does not answer for is left out rather than filled in.", "tags": [ "market" ], "parameters": [ { "name": "symbols", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma separated symbols in market-data form, up to 120; any past the 120th are dropped.", "example": "NVDA,AAPL" } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/QuoteResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/history": { "get": { "operationId": "history", "summary": "Daily or intraday candles", "description": "Candles with the adjustment that was actually applied reported back in adjustment and adjusted.", "tags": [ "market" ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "description": "One symbol, in market-data form.", "example": "NVDA" }, { "name": "range", "in": "query", "required": false, "schema": { "type": "string", "default": "2y" }, "description": "1d 5d 1mo 3mo 6mo 1y 2y 5y 10y ytd max. Anything else falls back to 2y." }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "default": "1d" }, "description": "1m 2m 5m 15m 30m 60m 90m 1h 1d 5d 1wk 1mo 3mo. Anything else falls back to 1d." }, { "name": "adj", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "total", "split", "none" ] }, "description": "total adjusts for splits and dividends, split for splits only, none leaves prices as traded. Omitted or unrecognised, it is total for 1d, 5d, 1wk, 1mo and 3mo bars and none for intraday; requested in the response is the mode used." } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/HistoryResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/fundamentals": { "get": { "operationId": "fundamentals", "summary": "Statements, short interest and profile", "description": "Annual (10), quarterly (20) and trailing twelve month rows. Unknown line items are null.", "tags": [ "market" ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "description": "One symbol, in market-data form.", "example": "NVDA" }, { "name": "benchmark", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Index to measure beta against. Defaults to the local index for the exchange the listing trades on, so a European listing is not regressed on a US close struck hours later. An index this API does not serve is refused with a 400 naming the ones it does; the response always carries betaBenchmark, and beta is null where no index can be named.", "example": "^OSEAX" } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/FundamentalsResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "400": { "description": "The benchmark is not an index this API serves; choices names the ones it does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/estimates": { "get": { "operationId": "estimates", "summary": "Consensus estimates, revisions and recommendations", "description": "Consensus by period, the trend in it, and the recommendation split.", "tags": [ "market" ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "description": "One symbol, in market-data form.", "example": "NVDA" } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EstimatesResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/peers": { "get": { "operationId": "peers", "summary": "Comparable companies", "description": "Ten to twenty peers, scored on sector, industry and size.", "tags": [ "market" ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "description": "One symbol, in market-data form.", "example": "NVDA" } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PeersResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/search": { "get": { "operationId": "search", "summary": "Symbol lookup", "description": "Resolves a name or ticker to the exact symbol the other endpoints take.", "tags": [ "market" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Free text: a name or a ticker.", "example": "nvidia" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 40 }, "description": "Rows to return; a value outside 1 to 40 is clamped." } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SearchResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/screen": { "get": { "operationId": "screenPreset", "summary": "Run a screen preset", "description": "The presets the terminal itself runs.", "tags": [ "market" ], "parameters": [ { "name": "preset", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "gainers", "losers", "active", "high52", "low52", "sector" ], "default": "gainers" } }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "default": "world" }, "description": "A scope from api/market/sector.py SCOPES." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "description": "Rows per page; a value outside 1 to 200 is clamped." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 5000 }, "description": "A value outside 0 to 5000 is clamped." }, { "name": "band", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "benchmark", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Index the beta columns are read against. One beta is stored per listing, measured against that listing's own local index, so a row measured against another index has its beta withheld rather than relabelled; rows are not filtered. An index this API does not serve is refused with a 400 naming the ones it does.", "example": "^OSEAX" }, { "name": "columns", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma separated extra columns." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Any value returns the field, operator, preset and scope catalogue instead of rows." } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ScreenResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "400": { "description": "The benchmark is not an index this API serves; choices names the ones it does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } }, "post": { "operationId": "screen", "summary": "Run a filtered screen", "description": "Filters, sort and columns, the same engine the screener view uses.", "tags": [ "market" ], "parameters": [], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ScreenResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "400": { "description": "The benchmark is not an index this API serves; choices names the ones it does.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScreenRequest" } } } } } }, "/api/v1/me": { "get": { "operationId": "me", "summary": "This key", "description": "The tier, the per-minute allowance and today's usage for the key making the call. It reads no market data and reaches no upstream, but is authenticated and rate limited exactly like every other v1 route.", "tags": [ "market" ], "parameters": [], "responses": { "200": { "description": "The calling key's own tier and usage, or an unavailable marker when the store could not be read.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/KeyIdentity" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The key store or the account behind the key could not be read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The rate limiter could not count, so the request was neither metered nor served.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/aliases": { "get": { "operationId": "aliases", "summary": "Canonical symbols", "description": "Maps renamed symbols to the form the other endpoints answer for, for example VOLVA.ST to VOLV-A.ST. Nordic share classes use a dash.", "tags": [ "market" ], "parameters": [ { "name": "symbols", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma separated, up to 200. symbol is accepted for one.", "example": "VOLVA.ST,NVDA" } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AliasesResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/earnings": { "get": { "operationId": "earnings", "summary": "Next earnings report", "description": "Date, status (projected, confirmed or reported), session and the last reported quarter, per symbol.", "tags": [ "market" ], "parameters": [ { "name": "symbols", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Comma separated. symbol is accepted for one.", "example": "NVDA,AAPL" } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EarningsResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/earningscalendar": { "get": { "operationId": "earningscalendar", "summary": "Earnings calendar", "description": "Every report due inside the window, for a market scope or for the symbols given, with the same status, session and last report fields.", "tags": [ "market" ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Window in days, 1 to 400. Default 30.", "example": 14 }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A market scope, default world; all for every company with a date.", "example": "sp500" }, { "name": "symbols", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma separated; replaces scope.", "example": "NVDA,AAPL" }, { "name": "sector", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With scope=all: one sector." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With scope=all: name or ticker match." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With scope=all: date, company, symbol, sector or marketCap." }, { "name": "dir", "in": "query", "required": false, "schema": { "type": "string" }, "description": "asc or desc." } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EarningsCalendarResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/earningscal": { "get": { "operationId": "earningscal", "summary": "Earnings calendar (old name)", "description": "The pre-launch name of /api/v1/earningscalendar. It answers the same body; use the new path.", "tags": [ "market" ], "parameters": [ { "name": "days", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Window in days, 1 to 400. Default 30.", "example": 14 }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A market scope, default world; all for every company with a date.", "example": "sp500" }, { "name": "symbols", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma separated; replaces scope.", "example": "NVDA,AAPL" }, { "name": "sector", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With scope=all: one sector." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With scope=all: name or ticker match." }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With scope=all: date, company, symbol, sector or marketCap." }, { "name": "dir", "in": "query", "required": false, "schema": { "type": "string" }, "description": "asc or desc." } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EarningsCalendarResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } }, "deprecated": true } }, "/api/v1/yields": { "get": { "operationId": "yields", "summary": "Treasury yield curve", "description": "Eleven constant-maturity tenors from one month to thirty years, daily over five years.", "tags": [ "market" ], "parameters": [], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/YieldsResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/fedpath": { "get": { "operationId": "fedpath", "summary": "Fed path", "description": "The rate path fed funds futures price into each upcoming meeting, against the effective rate.", "tags": [ "market" ], "parameters": [], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/FedPathResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/feargreed": { "get": { "operationId": "feargreed", "summary": "Fear and greed", "description": "Suros's own index: seven market inputs, each ranked against its last 252 sessions and averaged. No reading on a day with fewer than five inputs.", "tags": [ "market" ], "parameters": [], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/FearGreedResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/positioning": { "get": { "operationId": "positioning", "summary": "Futures positioning", "description": "Dealer, asset manager, leveraged fund and other positions in 25 financial futures, weekly.", "tags": [ "market" ], "parameters": [ { "name": "market", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A market id such as ZN, ES, 6E or BTC. Leave it out for the board.", "example": "ZN" } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PositioningResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/shorts": { "get": { "operationId": "shorts", "summary": "Short positions", "description": "Named short positions from the NO, SE, NL, DE, FR, FI, PL, BE, IE, DK and AT registers; totals from UK, HK and AU. The register is picked from the listing. A US listing returns fails to deliver instead: shares sold that were not delivered on settlement day, which is not short interest; register.kind is ftd. Paid plans only: any other plan is refused with 403.", "tags": [ "market" ], "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One symbol, in Suros form.", "example": "EQNR.OL" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Two-letter register code; without symbol it returns that register's board.", "example": "NO" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Company name to match on when the listing has no identifier." } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ShortsResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/stakes": { "get": { "operationId": "stakes", "summary": "Five percent holders", "description": "Beneficial ownership filings for a US registrant, parsed to holder, stance, percent and shares.", "tags": [ "market" ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "description": "One symbol, in Suros form.", "example": "AAPL" }, { "name": "accession", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One filing id, for its detail." } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/StakesResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/adviser": { "get": { "operationId": "adviser", "summary": "Investment advisers", "description": "Search registered advisers by name, or read one by CRD: assets under management and the private funds it reports.", "tags": [ "market" ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Three letters or more.", "example": "bridgewater" }, { "name": "crd", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A CRD number." } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/AdviserResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/supplychain": { "get": { "operationId": "supplychain", "summary": "Supply chain", "description": "Customers and suppliers from filings and headlines, each placed in a country.", "tags": [ "market" ], "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "type": "string" }, "description": "One symbol, in Suros form.", "example": "AAPL" } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SupplyChainResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/insiderflow": { "get": { "operationId": "insiderflow", "summary": "Insider trades", "description": "Insider trades filed in the US and Sweden over the last 90 days. A filing arrives days after the trade, so this is a record of what insiders did, not a real-time signal. Five shapes, picked by the arguments. With find: insiders whose name contains the text, each with the pkey the insider argument takes, and companies by ticker or name. With insider: one insider's trades, the companies and roles on file, and older filings where the store reaches back. With symbol: that company's trades and its weekly net buying in US dollars. With any=1 and insiders and/or symbols: a watched feed of trades matching either list, funds included. Otherwise: the board (totals, clusters of insiders buying together, the largest buys and sells, net flow by company and by sector, the insiders who bought and sold the most) and a feed filtered by every argument given, where insiders and symbols must both match.", "tags": [ "market" ], "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One symbol, in Suros form: that company's trades. Leave it out for the board or a feed.", "example": "AAPL" }, { "name": "find", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Two characters or more: insiders by any part of the name as filed or as read, and companies by ticker or name. Returns people and companies, 20 of each." }, { "name": "insider", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One insider key, the pkey on a trade row: US: and the filer number for a US insider, or the country, ~ and the filed name elsewhere. Returns that insider's profile." }, { "name": "insiders", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma separated insider keys to filter the feed, up to 200." }, { "name": "any", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1 makes insiders and symbols a watched feed: a trade matching either list is kept, and funds are not left out." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma separated from open (open-market buys and sells, the default), buy, sell, grant, exercise, tax, other, all." }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Feed look back, 1 to 90. Default 30.", "example": 7 }, { "name": "min", "in": "query", "required": false, "schema": { "type": "number" }, "description": "Smallest trade in US dollars." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string" }, "description": "US or SE." }, { "name": "sector", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One sector." }, { "name": "role", "in": "query", "required": false, "schema": { "type": "string" }, "description": "ceo, cfo, chair, director, officer, owner or other; exec is ceo and cfo together." }, { "name": "symbols", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma separated symbols to filter the feed." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Feed rows, 1 to 2000. Default 200. feedTotal says how many matched." }, { "name": "cluster", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1 keeps only trades that are part of a cluster, several insiders buying the same company inside a short window." }, { "name": "firstYears", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "1 to 20. Marks each open-market buy in the feed with priorBuy, the same insider's previous open-market buy in the same company, and priorFrom, the date the store behind that answer starts." }, { "name": "first", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1, with firstYears, keeps only open-market buys that are the insider's first in the company in that many years." }, { "name": "funds", "in": "query", "required": false, "schema": { "type": "string" }, "description": "1 includes trades in funds and other investment vehicles, which the board and the market feed leave out by default." } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/InsiderFlowResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/v1/holdings13f": { "get": { "operationId": "holdings13f", "summary": "Institutional holdings (13F)", "description": "What institutional managers hold, from the quarterly 13F reports, nine quarters back. Reports are due 45 days after the quarter ends and list long positions in US-listed shares, listed options and convertible bonds only: no short positions and nothing listed outside the US. Six shapes, picked by the arguments. With manager: a summary of one manager's report and its 100 largest positions (the rest page with list), each classed against the quarter before as new, added, reduced, unchanged or sold out, with top buys and sells by value, sector weights and concentration; a newly filed report is read the day it is filed. With symbol: institutional ownership as a share of shares outstanding and its change, the number of holders and its change, the largest holders, buyers and sellers, a quarterly history, and insider ownership from the shares each insider reported holding after their latest trade. With changes: the buyers and sellers of that security last quarter. With top: the largest managers by reported value. With q: managers by name. With filings: the newest report of each manager listed, for polling. Without arguments: the quarters held. Paid plans only: any other plan is refused with 403.", "tags": [ "market" ], "parameters": [ { "name": "manager", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A manager's filer number (CIK), as q, top and every holder row give it.", "example": "1067983" }, { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With manager: the quarter end, YYYY-MM-DD. Default the newest quarter held for that manager.", "example": "2026-06-30" }, { "name": "list", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With manager: holdings or sold. Returns one page of every position, as rows with total, instead of the summary.", "example": "holdings" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With list: symbol, name, shares, value, weight, change, shareChange, shareChangePct, sector, prevShares or prevValue. Default value, or prevValue for sold." }, { "name": "dir", "in": "query", "required": false, "schema": { "type": "string" }, "description": "With list: desc (the default) or asc. Blanks sort last either way." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "With list: rows to skip.", "example": 100 }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "With list: rows per page, 1 to 500. Default 100.", "example": 100 }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One symbol, in Suros form: its ownership figures and holders.", "example": "AAPL" }, { "name": "changes", "in": "query", "required": false, "schema": { "type": "string" }, "description": "One symbol: only its buyers and sellers last quarter, with the summary.", "example": "AAPL" }, { "name": "top", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The largest managers by reported value, 1 to 200.", "example": 25 }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Part of a manager's name, every word must match.", "example": "berkshire" }, { "name": "filings", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma separated filer numbers, up to 50: the newest report of each.", "example": "1067983,1336528" } ], "responses": { "200": { "description": "The payload, or a warming marker when the data has not been fetched yet.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Holdings13fResponse" }, { "$ref": "#/components/schemas/Unavailable" } ] } } } }, "401": { "description": "No key, or the key is not recognised.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The account behind the key has no active subscription (reason subscription; the key is kept and works again once it has one), or its plan does not include this data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The per-key rate limit is spent, or this address sent too many unrecognised keys.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Requests a minute on this key: 600 when the owner's plan or their workspace's plan is pro or beta, 60 on the Equities analyst and Commodity trader plans. A key whose account has no subscription is refused with 403." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requests left in the current minute." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Unix seconds at which the window resets." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The market handlers did not answer, answered with something that is not JSON, or refused the gateway itself (never the caller's key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The data is unavailable: its source is switched off or did not answer (body: source unavailable, ok false, why when known), or the rate limiter could not count (Retry-After 5).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying: 5, when the rate limiter could not count." } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Unavailable" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer ss_ plus the rest of the key, shown once when it was created." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "The same key in an X-API-Key header, for clients that cannot set Authorization." } }, "schemas": { "Unavailable": { "type": "object", "required": [ "source" ], "description": "The upstream could not be reached. No number is invented; the caller shows an unavailable state.", "properties": { "source": { "type": "string", "enum": [ "unavailable" ] }, "why": { "type": "string", "description": "What failed, when the handler can say." }, "warming": { "type": "boolean", "description": "Not fetched yet; the server fetches what has been asked for on a schedule." }, "ok": { "type": "boolean", "enum": [ false ], "description": "Present and false on a 503: the source is switched off or did not answer." }, "error": { "type": "string", "description": "Sent by screen when the request itself was refused." } } }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ false ] }, "error": { "type": "string" }, "reason": { "type": "string", "enum": [ "missing", "malformed", "revoked", "unknown", "subscription" ], "description": "Why the key was refused: on a 401 the key itself, on a 403 subscription when its account has no active plan." }, "retryAfter": { "type": "integer", "description": "Seconds to wait before retrying, on a 429 or a 503." }, "resetAt": { "type": "integer", "description": "Unix seconds at which the per-key window resets, on a 429." }, "upgrade": { "type": "boolean", "description": "On a 403: the plan behind the key does not include this." }, "symbol": { "type": "string", "description": "On a 403 that refuses one symbol: the symbol." }, "choices": { "type": "array", "description": "On a 400 for an unserved benchmark: the indexes this API serves.", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "label": { "type": "string" }, "country": { "type": [ "string", "null" ] } } } }, "source": { "type": "string", "enum": [ "unavailable" ] } } }, "Quote": { "type": "object", "properties": { "symbol": { "type": "string" }, "price": { "type": [ "number", "null" ] }, "change": { "type": [ "number", "null" ] }, "changePct": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "time": { "type": [ "integer", "null" ] }, "prevClose": { "type": [ "number", "null" ] }, "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "delayed": { "type": "boolean", "description": "False only where the exchange publishes its quotes without delay." }, "delayMin": { "description": "How many minutes the exchange holds this quote back: a number, a [min, max] pair for a futures contract whose exchange the symbol does not name, or null where the exchange publishes no delay.", "oneOf": [ { "type": "number" }, { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 }, { "type": "null" } ] }, "asOf": { "type": [ "string", "null" ], "format": "date-time", "description": "The exchange time of the last trade in this quote, UTC." } } }, "QuoteResponse": { "type": "object", "properties": { "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } }, "source": { "type": "string" } } }, "Candle": { "type": "object", "properties": { "t": { "type": "integer", "description": "Unix seconds" }, "o": { "type": [ "number", "null" ] }, "h": { "type": [ "number", "null" ] }, "l": { "type": [ "number", "null" ] }, "c": { "type": [ "number", "null" ] }, "v": { "type": [ "number", "null" ] } } }, "HistoryResponse": { "type": "object", "properties": { "symbol": { "type": "string" }, "range": { "type": "string" }, "interval": { "type": "string" }, "candles": { "type": "array", "items": { "$ref": "#/components/schemas/Candle" } }, "requested": { "type": [ "string", "null" ] }, "adjustment": { "type": [ "string", "null" ] }, "adjusted": { "type": "boolean" }, "splits": { "type": "array", "items": { "type": "object" } }, "dividends": { "type": "array", "items": { "type": "object" } }, "source": { "type": "string" } } }, "FundamentalsRow": { "type": "object", "description": "One statement period. Unknown values are null, never zero.", "properties": { "period": { "type": "string", "example": "2024-12-31" }, "fy": { "type": [ "integer", "null" ] }, "fq": { "type": [ "integer", "null" ] }, "filed": { "type": [ "string", "null" ], "description": "ISO day the filing behind this row was filed, when a filing supplied it." }, "revenue": { "type": [ "number", "null" ] }, "costOfRevenue": { "type": [ "number", "null" ] }, "grossProfit": { "type": [ "number", "null" ] }, "rnd": { "type": [ "number", "null" ] }, "sga": { "type": [ "number", "null" ] }, "operatingIncome": { "type": [ "number", "null" ] }, "ebit": { "type": [ "number", "null" ] }, "ebitda": { "type": [ "number", "null" ] }, "interestExpense": { "type": [ "number", "null" ] }, "pretaxIncome": { "type": [ "number", "null" ] }, "taxProvision": { "type": [ "number", "null" ] }, "netIncome": { "type": [ "number", "null" ] }, "epsDiluted": { "type": [ "number", "null" ] }, "sharesDiluted": { "type": [ "number", "null" ] }, "sharesOutstanding": { "type": [ "number", "null" ] }, "totalAssets": { "type": [ "number", "null" ] }, "totalEquity": { "type": [ "number", "null" ] }, "totalDebt": { "type": [ "number", "null" ] }, "cash": { "type": [ "number", "null" ] }, "currentAssets": { "type": [ "number", "null" ] }, "currentLiabilities": { "type": [ "number", "null" ] }, "minorityInterest": { "type": [ "number", "null" ] }, "operatingCashflow": { "type": [ "number", "null" ] }, "capex": { "type": [ "number", "null" ] }, "depreciation": { "type": [ "number", "null" ] }, "freeCashflow": { "type": [ "number", "null" ] }, "dividendsPaid": { "type": [ "number", "null" ] }, "buybacks": { "type": [ "number", "null" ] }, "sbc": { "type": [ "number", "null" ] } } }, "FundamentalsResponse": { "type": "object", "description": "The headline keys come from the quote and summary feeds; netIncome through incomeBeforeTax are the latest annual statement in that feed. Unknown values are null.", "properties": { "symbol": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "financialCurrency": { "type": [ "string", "null" ] }, "marketCap": { "type": [ "number", "null" ] }, "trailingPE": { "type": [ "number", "null" ] }, "forwardPE": { "type": [ "number", "null" ] }, "priceToSales": { "type": [ "number", "null" ], "description": "Null when the quote and statement currencies differ." }, "priceToBook": { "type": [ "number", "null" ] }, "eps": { "type": [ "number", "null" ] }, "forwardEps": { "type": [ "number", "null" ] }, "revenue": { "type": [ "number", "null" ] }, "revenueGrowth": { "type": [ "number", "null" ] }, "grossMargins": { "type": [ "number", "null" ] }, "ebitdaMargins": { "type": [ "number", "null" ] }, "profitMargins": { "type": [ "number", "null" ] }, "operatingMargins": { "type": [ "number", "null" ] }, "beta": { "type": [ "number", "null" ], "description": "Measured against betaBenchmark over betaWindow. Null when no index can be named or the regression could not run; betaBasis then says why." }, "betaBenchmark": { "type": [ "string", "null" ], "description": "The index beta was measured against; null whenever beta is null." }, "betaBenchmarkLabel": { "type": [ "string", "null" ] }, "betaWindow": { "type": "string" }, "betaBasis": { "type": [ "string", "null" ], "description": "Why this index, or why there is no beta." }, "betaSource": { "type": [ "string", "null" ], "description": "screen when the stored beta was used, measured when it was regressed for this call." }, "vendorBeta": { "type": "number", "description": "The beta as published with the market data. Its index, window and return frequency are not disclosed, so it does not compare with beta. Absent when none is published." }, "vendorBetaNote": { "type": "string" }, "sharesOutstanding": { "type": [ "number", "null" ] }, "totalDebt": { "type": [ "number", "null" ] }, "totalCash": { "type": [ "number", "null" ] }, "freeCashflow": { "type": [ "number", "null" ] }, "returnOnEquity": { "type": [ "number", "null" ] }, "returnOnAssets": { "type": [ "number", "null" ] }, "dividendYield": { "type": [ "number", "null" ] }, "dividendRate": { "type": [ "number", "null" ] }, "exDividendDate": { "type": [ "integer", "null" ], "description": "Unix seconds" }, "fiftyTwoWeekHigh": { "type": [ "number", "null" ] }, "fiftyTwoWeekLow": { "type": [ "number", "null" ] }, "ebitda": { "type": [ "number", "null" ] }, "grossProfits": { "type": [ "number", "null" ] }, "operatingCashflow": { "type": [ "number", "null" ] }, "currentRatio": { "type": [ "number", "null" ] }, "quickRatio": { "type": [ "number", "null" ] }, "debtToEquity": { "type": [ "number", "null" ] }, "enterpriseValue": { "type": [ "number", "null" ] }, "enterpriseToRevenue": { "type": [ "number", "null" ], "description": "Null when the quote and statement currencies differ." }, "enterpriseToEbitda": { "type": [ "number", "null" ], "description": "Null when the quote and statement currencies differ." }, "pegRatio": { "type": [ "number", "null" ] }, "bookValue": { "type": [ "number", "null" ] }, "earningsGrowth": { "type": [ "number", "null" ] }, "payoutRatio": { "type": [ "number", "null" ] }, "netIncome": { "type": [ "number", "null" ] }, "operatingIncome": { "type": [ "number", "null" ] }, "grossProfitStmt": { "type": [ "number", "null" ] }, "totalRevenueStmt": { "type": [ "number", "null" ] }, "totalAssets": { "type": [ "number", "null" ] }, "totalStockholderEquity": { "type": [ "number", "null" ] }, "totalCurrentAssets": { "type": [ "number", "null" ] }, "totalCurrentLiabilities": { "type": [ "number", "null" ] }, "capitalExpenditures": { "type": [ "number", "null" ] }, "depreciation": { "type": [ "number", "null" ] }, "operatingCashflowStmt": { "type": [ "number", "null" ] }, "minorityInterest": { "type": [ "number", "null" ] }, "incomeTaxExpense": { "type": [ "number", "null" ] }, "interestExpense": { "type": [ "number", "null" ] }, "incomeBeforeTax": { "type": [ "number", "null" ] }, "annual": { "type": "array", "description": "Up to 10 rows, newest first.", "items": { "$ref": "#/components/schemas/FundamentalsRow" } }, "quarterly": { "type": "array", "description": "Up to 20 rows, newest first.", "items": { "$ref": "#/components/schemas/FundamentalsRow" } }, "ttm": { "$ref": "#/components/schemas/FundamentalsRow" }, "history": { "type": "array", "description": "Alias of annual, kept for older readers.", "items": { "$ref": "#/components/schemas/FundamentalsRow" } }, "short": { "type": "object", "properties": { "sharesShort": { "type": [ "number", "null" ] }, "shortRatio": { "type": [ "number", "null" ] }, "shortPctFloat": { "type": [ "number", "null" ] }, "sharesShortPriorMonth": { "type": [ "number", "null" ] }, "date": { "type": [ "string", "null" ] }, "floatShares": { "type": [ "number", "null" ] } } }, "profile": { "type": "object", "properties": { "sector": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "exchange": { "type": [ "string", "null" ] }, "employees": { "type": [ "integer", "null" ] }, "officers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "age": { "type": [ "integer", "null" ] }, "pay": { "type": [ "number", "null" ] } } } } } }, "sources": { "type": "object", "properties": { "statements": { "type": "string", "description": "sec or esef (the filing stores) or feed, with +feed when the feed filled rows the filing store does not cover." }, "quote": { "type": [ "string", "null" ] }, "profile": { "type": [ "string", "null" ] }, "derived": { "type": "array", "description": "Line items computed from others rather than reported.", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } }, "filer": { "type": "object", "description": "The filer behind the statements, when the filing store supplied them.", "properties": { "name": { "type": [ "string", "null" ] }, "cik": { "type": [ "integer", "null" ] }, "lei": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "taxonomy": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "ingestedAt": { "type": [ "integer", "null" ], "description": "Unix seconds" } } } } }, "asOf": { "type": "object", "properties": { "statements": { "type": [ "string", "null" ], "description": "Period end of the newest filed row; null when no filing store supplied the statements." }, "fetched": { "type": "integer", "description": "Unix seconds at which this payload was built." } } }, "source": { "type": "string" } } }, "EstimateLeg": { "type": "object", "properties": { "avg": { "type": [ "number", "null" ] }, "low": { "type": [ "number", "null" ] }, "high": { "type": [ "number", "null" ] }, "n": { "type": [ "integer", "null" ] }, "yearAgo": { "type": [ "number", "null" ] }, "growth": { "type": [ "number", "null" ] } } }, "EstimatesResponse": { "type": "object", "properties": { "symbol": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "periods": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": "string", "enum": [ "0q", "+1q", "0y", "+1y" ] }, "endDate": { "type": [ "string", "null" ] }, "eps": { "$ref": "#/components/schemas/EstimateLeg" }, "revenue": { "$ref": "#/components/schemas/EstimateLeg" }, "epsTrend": { "type": "object", "properties": { "current": { "type": [ "number", "null" ] }, "d7": { "type": [ "number", "null" ] }, "d30": { "type": [ "number", "null" ] }, "d60": { "type": [ "number", "null" ] }, "d90": { "type": [ "number", "null" ] } } }, "revisions": { "type": "object", "properties": { "up7": { "type": [ "integer", "null" ] }, "down7": { "type": [ "integer", "null" ] }, "up30": { "type": [ "integer", "null" ] }, "down30": { "type": [ "integer", "null" ] } } }, "growth": { "type": [ "number", "null" ] } } } }, "history": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": [ "string", "null" ] }, "epsEstimate": { "type": [ "number", "null" ] }, "epsActual": { "type": [ "number", "null" ] }, "surprisePct": { "type": [ "number", "null" ] }, "date": { "type": [ "string", "null" ] }, "epoch": { "type": [ "integer", "null" ], "description": "Unix seconds" } } } }, "recommendations": { "type": "array", "items": { "type": "object", "properties": { "period": { "type": [ "string", "null" ] }, "strongBuy": { "type": [ "integer", "null" ] }, "buy": { "type": [ "integer", "null" ] }, "hold": { "type": [ "integer", "null" ] }, "sell": { "type": [ "integer", "null" ] }, "strongSell": { "type": [ "integer", "null" ] } } } }, "nextEarnings": { "type": "object", "properties": { "date": { "type": [ "string", "null" ] }, "epoch": { "type": [ "integer", "null" ], "description": "Unix seconds" }, "dateEnd": { "type": [ "string", "null" ] }, "estimate": { "type": [ "boolean", "null" ], "description": "true while the date is estimated rather than announced." } } }, "source": { "type": "string" } } }, "ScreenRow": { "type": "object", "description": "Requested columns are added to these.", "properties": { "symbol": { "type": "string", "description": "Symbol in market-data form" }, "tv": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ], "description": "The ticker without its exchange suffix." }, "price": { "type": [ "number", "null" ] }, "change": { "type": [ "number", "null" ] }, "changePct": { "type": [ "number", "null" ] }, "volume": { "type": [ "number", "null" ] }, "relVolume": { "type": [ "number", "null" ] }, "mcap": { "type": [ "number", "null" ] }, "ccy": { "type": [ "string", "null" ] }, "exchange": { "type": [ "string", "null" ] }, "sector": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "description": { "type": "string", "description": "The company name, or the symbol when none is known." }, "type": { "type": "string" }, "isin": { "type": [ "string", "null" ] }, "figi": { "type": [ "string", "null" ] }, "mic": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "ScreenResponse": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/ScreenRow" } }, "total": { "type": [ "integer", "null" ] }, "source": { "type": "string", "enum": [ "suros" ] }, "note": { "type": [ "string", "null" ] }, "gated": { "type": "object", "description": "Present when the plan hides rows on this page; total still counts every match.", "properties": { "withheld": { "type": "integer" }, "shown": { "type": "integer" }, "note": { "type": "string" } } }, "coverage": { "type": "object", "description": "What the screen index holds for this scope; built false means it has no table yet." }, "benchmark": { "type": "string", "description": "The index asked for, when one was." }, "benchmarkLabel": { "type": "string" } } }, "ScreenRequest": { "type": "object", "properties": { "scope": { "type": "string", "description": "A scope from api/market/sector.py SCOPES.", "example": "world" }, "filters": { "type": "array", "items": { "type": "object", "required": [ "field", "op" ], "properties": { "field": { "type": "string" }, "op": { "type": "string", "enum": [ "gt", "lt", "gte", "lte", "between", "eq", "ne", "in", "nempty", "match" ] }, "value": { "description": "A number, or a string for a text field; a two-number array for between; an array or a comma separated string for in; a string for match; omitted for nempty." } } } }, "sort": { "type": "object", "properties": { "field": { "type": "string" }, "dir": { "type": "string", "enum": [ "asc", "desc" ] } } }, "limit": { "type": "integer", "default": 50, "minimum": 1, "maximum": 200 }, "offset": { "type": "integer", "default": 0, "minimum": 0, "maximum": 5000 }, "columns": { "type": "array", "items": { "type": "string" } }, "q": { "type": "string" }, "band": { "type": "string" }, "benchmark": { "type": "string", "description": "Index the beta columns are read against. One beta is stored per listing, measured against that listing's own local index, so a row measured against another index has its beta withheld rather than relabelled; rows are not filtered. An index this API does not serve is refused with a 400 naming the ones it does." } } }, "Peer": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "sector": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "mcap": { "type": [ "number", "null" ] }, "ccy": { "type": [ "string", "null" ] }, "exchange": { "type": [ "string", "null" ] }, "score": { "type": [ "number", "null" ] } } }, "PeersResponse": { "type": "object", "properties": { "symbol": { "type": "string" }, "peers": { "type": "array", "items": { "$ref": "#/components/schemas/Peer" } }, "source": { "type": "string" } } }, "SearchResult": { "type": "object", "properties": { "symbol": { "type": "string" }, "name": { "type": "string" }, "type": { "type": [ "string", "null" ] }, "quoteType": { "type": [ "string", "null" ] }, "exchange": { "type": [ "string", "null" ] }, "exchangeCode": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "sector": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "isin": { "type": [ "string", "null" ], "description": "Rows from the Suros master list only." }, "figi": { "type": [ "string", "null" ], "description": "Rows from the Suros master list only." }, "lei": { "type": [ "string", "null" ], "description": "Rows from the Suros master list only." } } }, "SearchResponse": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResult" } }, "source": { "type": "string", "enum": [ "suros", "feed", "suros+feed", "none" ] } } }, "KeyIdentity": { "type": "object", "description": "What the calling key itself is allowed to do. Nothing about the account behind it.", "required": [ "ok", "prefix", "tier", "rpm" ], "properties": { "ok": { "type": "boolean" }, "name": { "type": "string", "description": "The label the key was created with." }, "prefix": { "type": "string", "description": "The first twelve characters of the key, the part it is safe to show.", "example": "ss_4Kb2xQ7p" }, "tier": { "type": "string", "enum": [ "free", "pro" ] }, "rpm": { "type": "integer", "description": "Requests a minute this key may spend." }, "usageToday": { "type": "integer", "description": "Requests this key has spent since midnight UTC, this one included.", "nullable": true }, "createdAt": { "type": "integer", "description": "Unix milliseconds at which the key was minted.", "nullable": true } } }, "LastReport": { "type": "object", "description": "The most recent reported quarter.", "properties": { "reportedAt": { "type": "integer", "description": "Unix seconds of the report." }, "periodEnd": { "type": [ "number", "null" ], "description": "Unix seconds of the quarter end." }, "fiscalQuarter": { "type": [ "string", "null" ], "description": "Fiscal quarter label." }, "epsActual": { "type": [ "number", "null" ], "description": "Reported EPS." }, "epsEstimate": { "type": [ "number", "null" ], "description": "Consensus EPS before the report." }, "epsSurprisePct": { "type": [ "number", "null" ], "description": "Surprise in percent." }, "revenueActual": { "type": [ "number", "null" ], "description": "Reported revenue." }, "revenueEstimate": { "type": [ "number", "null" ], "description": "Consensus revenue before the report." }, "revenueSurprisePct": { "type": [ "number", "null" ], "description": "Surprise in percent." } }, "additionalProperties": true }, "EarningsEvent": { "type": "object", "description": "The next report for one symbol.", "properties": { "symbol": { "type": "string", "description": "The symbol asked for." }, "earningsDate": { "type": [ "string", "null" ], "description": "YYYY-MM-DD." }, "earningsEpoch": { "type": [ "number", "null" ], "description": "Unix seconds." }, "calendarQuarter": { "type": [ "string", "null" ], "description": "The calendar quarter the report falls in, e.g. Q3 2026. A company whose fiscal year does not end in December names the same quarter differently." }, "estimate": { "type": "boolean", "description": "True when the date is projected rather than set by the company." }, "status": { "type": "string", "enum": [ "projected", "confirmed", "reported" ], "description": "projected: not yet set by the company; confirmed: set; reported: the figures are out." }, "time": { "type": [ "string", "null" ], "enum": [ "before open", "after close", null ], "description": "The session, where the company has stated it; null when it has not." }, "last": { "anyOf": [ { "$ref": "#/components/schemas/LastReport" }, { "type": "null" } ] } }, "additionalProperties": true, "required": [ "symbol" ] }, "EarningsResponse": { "type": "object", "description": "The next report per symbol.", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/EarningsEvent" }, "description": "One row per symbol that has a date." }, "warming": { "type": "array", "items": { "type": "string" }, "description": "Symbols being fetched now; ask again in a few seconds." } }, "additionalProperties": true, "required": [ "events" ] }, "EarningsCalendarRow": { "type": "object", "description": "One company on the calendar.", "properties": { "symbol": { "type": "string", "description": "Symbol." }, "name": { "type": [ "string", "null" ], "description": "Company name." }, "date": { "type": [ "number", "null" ], "description": "Unix seconds." }, "time": { "type": [ "string", "null" ], "enum": [ "before open", "after close", null ], "description": "The session, where the company has stated it; null when it has not." }, "status": { "type": "string", "enum": [ "projected", "confirmed", "reported" ], "description": "projected: not yet set by the company; confirmed: set; reported: the figures are out." }, "estimate": { "type": "boolean", "description": "True when the date is projected." }, "period": { "type": [ "string", "null" ], "description": "Fiscal period label." }, "epsForecast": { "type": [ "number", "null" ], "description": "Consensus EPS." }, "revenueForecast": { "type": [ "number", "null" ], "description": "Consensus revenue." }, "marketCap": { "type": [ "number", "null" ], "description": "In marketCapCurrency." }, "marketCapCurrency": { "type": [ "string", "null" ], "description": "ISO currency." }, "basis": { "type": [ "string", "null" ], "description": "How a projected date was reached." }, "last": { "anyOf": [ { "$ref": "#/components/schemas/LastReport" }, { "type": "null" } ] } }, "additionalProperties": true }, "EarningsCalendarResponse": { "type": "object", "description": "Reports due inside the window.", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/EarningsCalendarRow" }, "description": "Sorted by date." }, "days": { "type": "integer", "description": "The window used." }, "coverage": { "type": "object", "description": "How much of the scope has a date, and why the rest does not." } }, "additionalProperties": true, "required": [ "events" ] }, "AliasesResponse": { "type": "object", "description": "Renamed symbols, mapped to the canonical form.", "properties": { "aliases": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Old symbol to canonical symbol. A symbol that is already canonical is absent." }, "asked": { "type": "integer", "description": "How many symbols were read." } }, "additionalProperties": true, "required": [ "aliases" ] }, "YieldsResponse": { "type": "object", "description": "The US Treasury constant-maturity curve, daily, over five years.", "properties": { "ok": { "type": "boolean", "description": "True." }, "asOf": { "type": "string", "description": "Newest date with a print." }, "tenors": { "type": "array", "items": { "type": "object", "description": "One maturity.", "properties": { "id": { "type": "string", "description": "Series id, the key into series." }, "label": { "type": "string", "description": "For example 10Y." }, "years": { "type": "number", "description": "Maturity in years." } }, "additionalProperties": true }, "description": "Shortest first." }, "missing": { "type": "array", "items": { "type": "string" }, "description": "Tenors that could not be read this time." }, "dates": { "type": "array", "items": { "type": "string" }, "description": "YYYY-MM-DD, oldest first." }, "series": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": [ "number", "null" ] } }, "description": "Yield in percent per tenor id, aligned to dates; null where the market was shut." } }, "additionalProperties": true, "required": [ "dates", "series" ] }, "FedPathResponse": { "type": "object", "description": "The policy rate path priced by fed funds futures.", "properties": { "effr": { "type": [ "number", "null" ], "description": "Effective fed funds rate, percent." }, "effrDate": { "type": "string", "description": "Date of that print." }, "range": { "type": "array", "items": { "type": "number" }, "description": "Target range, low and high." }, "meetings": { "type": "array", "items": { "type": "object", "description": "One meeting.", "properties": { "date": { "type": "string", "description": "Decision date." }, "start": { "type": [ "number", "null" ], "description": "Implied rate going in." }, "end": { "type": [ "number", "null" ], "description": "Implied rate coming out." }, "moveBp": { "type": [ "number", "null" ], "description": "Implied move in basis points." }, "cumBp": { "type": [ "number", "null" ], "description": "Cumulative from today." }, "dist": { "type": "object", "description": "Probability of each outcome." } }, "additionalProperties": true }, "description": "Upcoming meetings." }, "strip": { "type": "array", "items": { "type": "object", "description": "month, contract, price, implied rate, date." }, "description": "The monthly contracts behind the path." }, "history": { "type": "object", "description": "Implied rate per meeting over recent sessions." } }, "additionalProperties": true, "required": [ "meetings" ] }, "FearGreedResponse": { "type": "object", "description": "The Suros fear and greed index, 0 to 100.", "properties": { "score": { "type": [ "number", "null" ], "description": "Today, 0 extreme fear to 100 extreme greed." }, "rating": { "type": [ "string", "null" ], "description": "The band the score falls in." }, "asOf": { "type": "string", "description": "Session date." }, "prev": { "type": "object", "description": "close, week, month and year ago." }, "parts": { "type": "array", "items": { "type": "object", "description": "One input.", "properties": { "k": { "type": "string", "description": "Name." }, "v": { "type": [ "number", "null" ], "description": "Rank against its last 252 sessions, 0 to 100." }, "read": { "type": "string", "description": "What is measured." }, "rating": { "type": "string", "description": "Band." } }, "additionalProperties": true }, "description": "The seven inputs." }, "history": { "type": "array", "items": { "type": "array" }, "description": "[date, score] pairs." }, "method": { "type": "string", "description": "How the index is built." } }, "additionalProperties": true, "required": [ "score" ] }, "PositioningResponse": { "type": "object", "description": "Weekly futures positioning by trader group. Without market: one row per market. With market: that market and its history.", "properties": { "markets": { "type": "array", "items": { "type": "object", "description": "id, label, group, date, open interest and groups." }, "description": "The board." }, "groups": { "type": [ "object", "array" ], "description": "Detail: per trader group, long, short, net, weekly change, percentile rank and share of open interest. Board: the group order." }, "cols": { "type": "array", "items": { "type": "string" }, "description": "Detail: the column names of history." }, "history": { "type": "array", "items": { "type": "array" }, "description": "Detail: one row per week, oldest first." }, "rankWeeks": { "type": "integer", "description": "Weeks each percentile is ranked against." } }, "additionalProperties": true }, "ShortsResponse": { "type": "object", "description": "Short positions from the national register that covers the listing.", "properties": { "register": { "type": "object", "description": "country, authority, aggregated (true where the register publishes totals only), threshold, unit (pct or shares), asOf." }, "symbol": { "type": "string", "description": "The symbol asked for." }, "issuer": { "type": [ "object", "null" ], "description": "With symbol: name, holders [{holder, pct, date}], total, history, chg30, chg90, matchedBy." }, "byName": { "type": "boolean", "description": "True when the company was matched on its name rather than an identifier." }, "issuers": { "type": "array", "items": { "type": "object" }, "description": "Without symbol: the most shorted companies." }, "holders": { "type": "array", "items": { "type": "object" }, "description": "Without symbol: the largest position holders." }, "positions": { "type": "array", "items": { "type": "object" }, "description": "Without symbol: the latest positions." } }, "additionalProperties": true }, "StakesResponse": { "type": "object", "description": "Five percent holders from beneficial ownership filings (13D active, 13G passive).", "properties": { "symbol": { "type": "string", "description": "Symbol." }, "issuer": { "type": "object", "description": "name and identifiers." }, "holders": { "type": "array", "items": { "type": "object", "description": "One holder.", "properties": { "name": { "type": "string", "description": "Filer." }, "stance": { "type": "string", "description": "active or passive." }, "form": { "type": "string", "description": "Form type." }, "filed": { "type": "string", "description": "Filing date." }, "accession": { "type": "string", "description": "Filing id; pass it back as accession for the detail." }, "pct": { "type": [ "number", "null" ], "description": "Percent of the class." }, "shares": { "type": [ "number", "null" ], "description": "Shares held." }, "pctChg": { "type": [ "number", "null" ], "description": "Change against the holder's previous filing." } }, "additionalProperties": true }, "description": "Newest first." }, "legacy": { "type": "array", "items": { "type": "object" }, "description": "Older filings under the pre-2025 form names, linked but not parsed." } }, "additionalProperties": true }, "AdviserResponse": { "type": "object", "description": "Registered investment advisers: a name search, or one firm by CRD.", "properties": { "firms": { "type": "array", "items": { "type": "object", "description": "A match.", "properties": { "crd": { "type": "string", "description": "CRD number; pass it back as crd." }, "name": { "type": "string", "description": "Firm." }, "city": { "type": [ "string", "null" ], "description": "City." }, "country": { "type": [ "string", "null" ], "description": "Country." } }, "additionalProperties": true }, "description": "Name search results." }, "firm": { "type": "object", "description": "With crd: the firm, its assets under management and the private funds it lists." } }, "additionalProperties": true }, "SupplyChainResponse": { "type": "object", "description": "Customers and suppliers named in company filings and in the news, each placed in a country.", "properties": { "symbol": { "type": "string", "description": "Symbol." }, "country": { "type": [ "string", "null" ], "description": "ISO country of the company itself." }, "countryVia": { "type": [ "string", "null" ], "description": "How that country was decided." }, "customers": { "type": "array", "items": { "type": "object" }, "description": "symbol, name, country, percent of revenue, the filing and the sentence it came from." }, "suppliers": { "type": "array", "items": { "type": "object" }, "description": "Companies that name this one as a customer." }, "newsGraph": { "type": "object", "description": "Suppliers, customers, partners and deals read from headlines and filings." } }, "additionalProperties": true }, "InsiderFlowResponse": { "type": "object", "additionalProperties": true, "description": "One insider's profile, one company's insider trades, a name search, or the board with a feed.", "properties": { "rows": { "type": "array", "items": { "type": "object" }, "description": "With symbol or insider: trade rows, newest first. Each carries id (unique per filing line, stable across calls, so a poller can deduplicate on it), country, filed, traded, company, symbol, sector, name, display, pkey (the insider key), role, group, kind, open (an open-market trade), shares, price, currency, value, valueUsd (null when no rate or the price failed a check, see priceCheck), holdings, plan, cluster, fund, url." }, "weeks": { "type": "array", "items": { "type": "object" }, "description": "With symbol: week, bought, sold, net, in US dollars." }, "clusters": { "type": "array", "items": { "type": "object" }, "description": "Board: companies where several insiders bought in the open market inside a short window: symbol, company, country, sector, insiders, count, trades, first, last, valueUsd." }, "largest": { "type": "object", "description": "Board: the largest buys and sells." }, "flow": { "type": "object", "description": "Board: net buyers and sellers by company." }, "sectors": { "type": "object", "description": "Board: weekly buys and sells by sector." }, "feed": { "type": "array", "items": { "type": "object" }, "description": "Board and watched feed: trades matching the query, newest first, with the same fields as rows; priorBuy and priorFrom when firstYears is given." }, "coverage": { "type": "object", "description": "Per market: days read, filings, rows and what is still pending." }, "markets": { "type": "array", "items": { "type": "string" }, "description": "Markets with data." }, "feedTotal": { "type": "integer", "description": "Board and watched feed: how many trades matched before limit." }, "totals": { "type": "object", "description": "Board: open-market buys and sells counted, the dollars bought and sold, and how many carry no dollar value." }, "clusterCount": { "type": "integer", "description": "Board: clusters found, of which clusters lists the newest 40." }, "query": { "type": "object", "description": "Board and watched feed: the arguments as the server read them." }, "funds": { "type": "object", "description": "Board: whether funds are included, and how many trades and issuers the default leaves out." }, "name": { "type": "string", "description": "With insider: the name as the filings most often show it." }, "linked": { "type": "string", "description": "With insider: filer number when the trades are joined on it, name when the filed name is all there is." }, "companies": { "type": "array", "items": { "type": "object" }, "description": "With insider: each company traded, with trades, bought and sold in US dollars, first and last filing, and the last holdings. With find: matching companies with key, symbol, company, country, trades and last." }, "roles": { "type": "array", "items": { "type": "object" }, "description": "With insider: each role held, per company, with first and last filing." }, "history": { "type": "array", "items": { "type": "object" }, "description": "With a US insider: older filings from the stored quarters, with filed, bought, sold, symbol and accession." }, "people": { "type": [ "object", "array" ], "description": "Board: an object of buyers and sellers, the 15 insiders who bought and sold the most in US dollars, each with pkey, display, country, role, bought, sold, buys, sells, net, last and up to four companies. With find: an array of matching insiders with pkey, display, country, role, company, symbol, trades and last." } } }, "Holdings13fResponse": { "type": "object", "description": "Institutional holdings from 13F reports. Values are US dollars; reports filed before 3 January 2023 were in thousands and are converted.", "properties": { "note": { "type": "string", "description": "What a 13F report covers and what it leaves out." }, "period": { "type": "string", "description": "The quarter end the answer is for." }, "prevPeriod": { "type": [ "string", "null" ], "description": "The quarter compared with." }, "cik": { "type": "integer", "description": "With manager: the manager's filer number." }, "name": { "type": [ "string", "null" ], "description": "With manager: the manager's name as filed. With symbol: the issuer's name as filed." }, "value": { "type": "number", "description": "With manager: the sum of the positions in US dollars." }, "live": { "type": "boolean", "description": "With manager: true when the quarter comes from a report read on the day it was filed, before the quarterly data set holds it." }, "suspect": { "type": "boolean", "description": "With manager: true when the report was filed in dollars but its values look like thousands; shown as filed." }, "periods": { "type": "array", "items": { "type": "object" }, "description": "With manager: every quarter held, with value, count, filed, accession, amended and live." }, "holdings": { "type": "array", "items": { "type": "object" }, "description": "With manager: the 100 largest positions by value, each with cusip, symbol (null when unmapped), mapped, name, class, putCall, principal, shares, value, weight, prevShares, prevValue, change (new, added, reduced, unchanged), shareChange, shareChangePct, flow and sector. name is null where the report squashed it into one word; nameAsFiled marks a name read from the report." }, "sold": { "type": "array", "items": { "type": "object" }, "description": "With manager: the 100 largest positions held the quarter before and sold out." }, "buys": { "type": "array", "items": { "type": "object" }, "description": "With manager: the largest additions by shares added times the price the report implies." }, "sells": { "type": "array", "items": { "type": "object" }, "description": "With manager: the largest reductions, likewise." }, "sectors": { "type": "array", "items": { "type": "object" }, "description": "With manager: sector, value and weight of the long share positions." }, "concentration": { "type": [ "object", "null" ], "description": "With manager: positions, top1, top10, hhi and effective (the number of equal positions with the same concentration)." }, "stats": { "type": "object", "description": "With symbol or changes: holders, prevHolders, holdersChange, shares, prevShares, sharesChangePct, value, outstanding, institutionalPct, prevInstitutionalPct and changes (counts of new, added, reduced, soldout)." }, "insider": { "type": [ "object", "null" ], "description": "With symbol: shares, pct, insiders, from, to and days: the shares each insider reported holding after their latest trade inside the insider window." }, "history": { "type": "array", "items": { "type": "object" }, "description": "With symbol: holders, shares, value, calls and puts per quarter." }, "top": { "type": "array", "items": { "type": "object" }, "description": "With symbol: the largest holders with cik, name, shares, value, pct of shares outstanding, weight in the holder, change and shareChange." }, "buyers": { "type": "array", "items": { "type": "object" }, "description": "With symbol or changes: holders that added, largest first." }, "sellers": { "type": "array", "items": { "type": "object" }, "description": "With symbol or changes: holders that reduced or sold out, largest first." }, "rows": { "type": "array", "items": { "type": "object" }, "description": "With top or q: managers with cik, name, value, count, location, and prevValue with top. With list: one page of positions, shaped as holdings." }, "filers": { "type": "object", "description": "With filings: per filer number, ok and latest {acc, filed, period, form, url}, or ok false and why." }, "holdingsTotal": { "type": "integer", "description": "With manager: how many positions the report holds; page with list=holdings." }, "soldTotal": { "type": "integer", "description": "With manager: how many positions were sold out; page with list=sold." }, "total": { "type": "integer", "description": "With list: how many rows the list holds." } }, "additionalProperties": true } } } }