openapi: 3.2.0
info:
title: Clear Street Trading Instrument Data API
description: 'A unified, secure, and high-performance RESTful API for all client interactions with the Active trading platform.
This specification provides a single source of truth for the API surface, covering order management, trade execution, market data, and account services.
### Authentication
All endpoints require authentication via a JWT Bearer token provided in the `Authorization` header.
### Response Structure
All responses, both for success and error, adhere to a standard envelope structure:
- `data`: Contains the response payload on success, or `null` on error.
- `error`: Contains a structured error object on failure, or `null` on success.
- `metadata`: Contains the `request_id` and pagination information.
### WebSockets
Real-time market data is available via WebSocket connections, which are not formally described in this OpenAPI specification. The following operations are available:
- `market-data-l1-subscribe`: To start receiving L1 market data updates for a set of symbols.
- `market-data-l1-unsubscribe`: To stop receiving L1 market data updates.'
contact:
name: Clear Street API Support
url: https://clearstreet.io/contact
email: concierge@clearstreet.com
license:
name: Proprietary
url: https://clearstreet.io/terms
version: 2025-10-31
servers:
- url: https://api.clearstreet.com
description: Clear Street API
- url: https://api-dev.clearstreet.com
description: Clear Street Development API
- url: http://localhost:5001
description: Clear Street Local API
security:
- BearerAuth: []
tags:
- name: Instrument Data
description: Retrieve instrument analytics, market data, news, and related reference data.
paths:
/v1/instruments/events:
get:
tags:
- Instrument Data
summary: Get All Instrument Events
description: "List instrument events across all securities, grouped by date.\n\nDate range defaults (anchored on the current trading day, or the next trading day\nif today is a weekend or US market holiday):\n- Unfiltered (no `instrument_ids`): a single trading day\n (`from_date` = `to_date` = anchor); the requested span is capped at 6 days.\n- Filtered (with `instrument_ids`): a 30-day lookback ending on the anchor\n (`from_date` = anchor − 30 days, `to_date` = anchor)."
operationId: get_all_instrument_events
parameters:
- name: event_types
in: query
description: 'Filter by event type(s). Comma-delimited list. Example: `event_types=EARNINGS,IPO`.'
required: false
schema:
type: array
items:
$ref: '#/components/schemas/AllEventsEventType'
style: form
explode: false
- name: instrument_ids
in: query
description: 'Filter by instrument. Comma-separated instrument IDs (UUID) or symbols (equity tickers or OSI option symbols). Example: `instrument_ids=550e8400-e29b-41d4-a716-446655440000,AAPL`.'
required: false
schema:
type: array
items:
$ref: '#/components/schemas/InstrumentIdOrSymbol'
style: form
explode: false
- name: from_date
in: query
description: The start date for the query range, inclusive (YYYY-MM-DD).
required: false
schema:
type: string
example: 2025-04-24
- name: to_date
in: query
description: The end date for the query range, inclusive (YYYY-MM-DD).
required: false
schema:
type: string
example: 2025-07-24
responses:
'200':
description: Instrument events grouped by date
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/InstrumentAllEventsData'
type: object
examples:
InstrumentEventsByDate:
summary: Dividend events grouped by date
value:
data:
event_dates:
- date: 2026-04-23
events:
- dividend_event_data:
adjusted_dividend_amount: '0.5236'
declaration_date: 2026-04-22
dividend_amount: '0.5236'
dividend_yield: '43.82881469863321'
ex_date: 2026-04-23
frequency: Weekly
payment_date: 2026-04-24
record_date: 2026-04-23
instrument_id: 2281b543-7136-4008-aa0a-a402bf9d9f90
name: YieldMax ABNB Option Income Strategy ETF
reporting_currency: USD
symbol: ABNY
type: DIVIDEND
- dividend_event_data:
adjusted_dividend_amount: '0.1432'
declaration_date: 2026-04-22
dividend_amount: '0.1432'
dividend_yield: '181.7918287937743'
ex_date: 2026-04-23
frequency: Weekly
payment_date: 2026-04-24
record_date: 2026-04-23
instrument_id: 4b33fa52-8ab6-43f5-a8df-042e0c63d20e
name: YieldMax AI Option Income Strategy ETF
reporting_currency: USD
symbol: AIYY
type: DIVIDEND
metadata:
request_id: 5efbf08a-9067-4491-9f29-cf0b233507ef
'400':
description: Invalid query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
MalformedQueryString:
summary: Invalid query string payload
value:
error:
code: 400
message: 'Failed to deserialize query string. Error: premature end of input'
metadata:
request_id: e0a9bd3a-8510-41a7-8144-c51a27787b9c
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/instruments/{instrument_id}/analyst-reporting:
get:
tags:
- Instrument Data
summary: Get Instrument Analyst Consensus
description: Retrieves analyst ratings and price targets for an instrument.
operationId: get_instrument_analyst_consensus
parameters:
- name: instrument_id
in: path
description: Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).
required: true
schema:
type: string
description: 'Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.'
minLength: 1
- name: from
in: query
description: The start date for the query range, inclusive (YYYY-MM-DD)
required: false
schema:
type: string
format: date
example: 2025-04-24
- name: to
in: query
description: The end date for the query range, inclusive (YYYY-MM-DD)
required: false
schema:
type: string
format: date
example: 2025-07-24
responses:
'200':
description: Analyst consensus data
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/InstrumentAnalystConsensus'
type: object
examples:
AnalystRatings:
summary: Analyst consensus with price targets and ratings
value:
data:
date: 2025-10-01
distribution:
buy: 20
hold: 3
sell: 1
strong_buy: 18
strong_sell: 0
price_target:
average: '240.00'
currency: USD
high: '275.00'
low: '190.00'
rating: BUY
error: null
metadata:
request_id: 9e0f1a2b-3c4d-5e6f-7890-1a2b3c4d5e6f
'404':
description: Instrument not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
InstrumentNotFound:
summary: Instrument identifier does not exist
value:
error:
code: 404
message: 'Instrument not found: AAP'
metadata:
request_id: fa8cc9b2-fbf0-4f5b-8ce3-b3205b9f85f2
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/instruments/{instrument_id}/balance-sheets:
get:
tags:
- Instrument Data
summary: Get Instrument Balance Sheet Statements
description: 'Get balance sheet statements for an instrument.
Retrieves quarterly balance sheet statements for a specific instrument, sorted by fiscal period
(most recent first).
Date range defaults:
- `from_date`: None (no lower bound)
- `to_date`: None (no upper bound)'
operationId: get_instrument_balance_sheet_statements
parameters:
- name: instrument_id
in: path
description: Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).
required: true
schema:
type: string
description: 'Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.'
minLength: 1
- name: page_size
in: query
description: The number of items to return per page. Only used when page_token is not provided.
required: false
schema:
type: integer
format: int64
default: 1000
maximum: 1000
minimum: 1
- name: page_token
in: query
description: Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored.
required: false
schema:
type: string
format: byte
description: Base64URL-encoded pagination token
example: eyJvZmZzZXQiOjEwMCwibGltaXQiOjEwMH0=
- name: from_date
in: query
description: The start date for the query range, inclusive (YYYY-MM-DD).
required: false
schema:
type: string
example: 2025-04-24
- name: to_date
in: query
description: The end date for the query range, inclusive (YYYY-MM-DD).
required: false
schema:
type: string
example: 2025-07-24
responses:
'200':
description: List of quarterly balance sheet statements
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/InstrumentBalanceSheetStatementList'
type: object
examples:
BalanceSheetStatements:
summary: List of balance sheet statements, most recent first
value:
data:
- accepted_date: 2025-05-02 14:30:00+00:00
cash_and_cash_equivalents: '29943000000'
filing_date: 2025-05-01
net_debt: '76323000000'
period: Q1
period_type: QUARTERLY
reported_currency: USD
total_assets: '352583000000'
total_debt: '106266000000'
total_liabilities: '308258000000'
total_stockholders_equity: '56727000000'
year: 2025
error: null
metadata:
next_page_token: AAAAAAAAAGQAAAAAAAAAZQ==
page_number: 1
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
total_items: 20
total_pages: 2
'404':
description: Instrument not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
InstrumentNotFound:
summary: Instrument identifier does not exist
value:
error:
code: 404
message: 'Instrument not found: AAP'
metadata:
request_id: fa8cc9b2-fbf0-4f5b-8ce3-b3205b9f85f2
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/instruments/{instrument_id}/cash-flow-statements:
get:
tags:
- Instrument Data
summary: Get Instrument Cash Flow Statements
description: 'Get cash flow statements for an instrument.
Retrieves historical cash flow statements for the specified instrument.
Cash flow statements show cash inflows and outflows from operating, investing,
and financing activities.
'
operationId: get_instrument_cash_flow_statements
parameters:
- name: instrument_id
in: path
description: Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).
required: true
schema:
type: string
description: 'Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.'
minLength: 1
- name: page_size
in: query
description: The number of items to return per page. Only used when page_token is not provided.
required: false
schema:
type: integer
format: int64
default: 1000
maximum: 1000
minimum: 1
- name: page_token
in: query
description: Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored.
required: false
schema:
type: string
format: byte
description: Base64URL-encoded pagination token
example: eyJvZmZzZXQiOjEwMCwibGltaXQiOjEwMH0=
- name: from_date
in: query
description: The start date for the query range, inclusive (YYYY-MM-DD).
required: false
schema:
type: string
example: 2025-04-24
- name: to_date
in: query
description: The end date for the query range, inclusive (YYYY-MM-DD).
required: false
schema:
type: string
example: 2025-07-24
responses:
'200':
description: Cash flow statements retrieved successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/InstrumentCashFlowStatementList'
type: object
examples:
CashFlowStatements:
summary: Cash flow statements for a security
value:
data:
- accepted_date: 2025-05-02 14:30:00+00:00
capital_expenditure: '-2600000000'
cash_at_beginning_of_period: '33743000000'
cash_at_end_of_period: '29943000000'
change_in_working_capital: '-3200000000'
common_stock_repurchased: '-23000000000'
depreciation_and_amortization: '2900000000'
filing_date: 2025-05-01
free_cash_flow: '25800000000'
investments_in_property_plant_and_equipment: '-2600000000'
net_cash_provided_by_financing_activities: '-28300000000'
net_cash_provided_by_investing_activities: '-3900000000'
net_cash_provided_by_operating_activities: '28400000000'
net_change_in_cash: '-3800000000'
net_debt_issuance: '-1500000000'
net_dividends_paid: '-3800000000'
net_income: '22200000000'
operating_cash_flow: '28400000000'
period: Q1
period_type: QUARTERLY
purchases_of_investments: '-9500000000'
reported_currency: USD
sales_maturities_of_investments: '8200000000'
stock_based_compensation: '2500000000'
year: 2025
error: null
metadata:
next_page_token: AAAAAAAAAGQAAAAAAAAAZQ==
page_number: 1
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
total_items: 20
total_pages: 2
'404':
description: Instrument not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
InstrumentNotFound:
summary: Instrument identifier does not exist
value:
error:
code: 404
message: 'Instrument not found: AAP'
metadata:
request_id: fa8cc9b2-fbf0-4f5b-8ce3-b3205b9f85f2
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/instruments/{instrument_id}/events:
get:
tags:
- Instrument Data
summary: Get Instrument Events
description: 'Retrieves corporate events (dividends, splits, etc.) for an instrument, grouped by event type.
Date range defaults:
- `from_date`: today - 365 days
- `to_date`: today + 60 days'
operationId: get_instrument_events
parameters:
- name: instrument_id
in: path
description: Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).
required: true
schema:
type: string
description: 'Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.'
minLength: 1
- name: from_date
in: query
description: The start date for the query range, inclusive (YYYY-MM-DD).
required: false
schema:
type: string
example: 2025-04-24
- name: to_date
in: query
description: The end date for the query range, inclusive (YYYY-MM-DD).
required: false
schema:
type: string
example: 2025-07-24
responses:
'200':
description: Instrument events grouped by type
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/InstrumentEventsData'
type: object
examples:
GroupedCorporateEvents:
summary: Earnings, dividends, and splits for AAPL
value:
data:
dividends:
- adjusted_dividend_amount: '0.25'
declaration_date: 2024-10-31
dividend_amount: '0.25'
dividend_yield: '0.44'
ex_date: 2024-11-08
frequency: Quarterly
payment_date: 2024-11-14
record_date: 2024-11-11
earnings:
- date: 2024-10-31
eps_actual: '1.64'
eps_estimate: '1.60'
eps_surprise_percent: '2.5'
revenue_actual: '94930000000'
revenue_estimate: '94500000000'
revenue_surprise_percent: '0.45'
instrument_id: a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8
reporting_currency: USD
splits:
- date: 2020-08-31
denominator: '1'
numerator: '4'
split_type: stock-split
error: null
metadata:
request_id: 0f1a2b3c-4d5e-6789-8a7b-6c5d4e3f2a1b
'404':
description: Instrument not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
InstrumentNotFound:
summary: Instrument identifier does not exist
value:
error:
code: 404
message: 'Instrument not found: AAP'
metadata:
request_id: fa8cc9b2-fbf0-4f5b-8ce3-b3205b9f85f2
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/instruments/{instrument_id}/fundamentals:
get:
tags:
- Instrument Data
summary: Get Instrument Fundamentals
description: Retrieves supplemental fundamentals and company profile data for an instrument.
operationId: get_instrument_fundamentals
parameters:
- name: instrument_id
in: path
description: Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).
required: true
schema:
type: string
description: 'Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.'
minLength: 1
responses:
'200':
description: Instrument fundamentals
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/InstrumentFundamentals'
type: object
examples:
InstrumentFundamentals:
summary: Supplemental fundamentals for an instrument
value:
data:
average_volume: 76000000
beta: '1.20'
description: Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide.
dividend_yield: '0.005'
earnings_per_share: '5.61'
fifty_two_week_high: '230.00'
fifty_two_week_low: '165.00'
industry: Consumer Electronics
list_date: 1980-12-12
logo_url: https://example.com/logos/aapl.png
market_cap: '2800000000000'
previous_close: '210.87'
price_to_earnings: '30.5'
reporting_currency: USD
sector: Technology
error: null
metadata:
request_id: 5b6c7d8e-9f0a-1b2c-3d4e-5f6a7b8c9d0e
'400':
description: Fundamentals not applicable to this instrument type (e.g. an index)
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Instrument or fundamentals not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/instruments/{instrument_id}/income-statements:
get:
tags:
- Instrument Data
summary: Get Instrument Income Statements
description: 'Retrieves quarterly income statements for a specific instrument, sorted by fiscal period
(most recent first).
Date range defaults:
- `from_date`: None (no lower bound)
- `to_date`: None (no upper bound)'
operationId: get_instrument_income_statements
parameters:
- name: instrument_id
in: path
description: Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).
required: true
schema:
type: string
description: 'Instrument identifier: either an instrument UUID or a symbol (symbol for equities, OSI for options). Non-UUID inputs are resolved server-side.'
minLength: 1
- name: page_size
in: query
description: The number of items to return per page. Only used when page_token is not provided.
required: false
schema:
type: integer
format: int64
default: 1000
maximum: 1000
minimum: 1
- name: page_token
in: query
description: Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored.
required: false
schema:
type: string
format: byte
description: Base64URL-encoded pagination token
example: eyJvZmZzZXQiOjEwMCwibGltaXQiOjEwMH0=
- name: from_date
in: query
description: The start date for the query range, inclusive (YYYY-MM-DD).
required: false
schema:
type: string
example: 2025-04-24
- name: to_date
in: query
description: The end date for the query range, inclusive (YYYY-MM-DD).
required: false
schema:
type: string
example: 2025-07-24
responses:
'200':
description: List of quarterly income statements
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/InstrumentIncomeStatementList'
type: object
examples:
IncomeStatements:
summary: List of income statements, most recent first
value:
data:
- accepted_date: 2025-05-02 14:30:00+00:00
cost_of_revenue: '52080000000'
eps: '1.40'
eps_diluted: '1.38'
filing_date: 2025-05-01
gross_profit: '42850000000'
net_income: '22200000000'
operating_income: '26550000000'
period: Q1
period_type: QUARTERLY
reported_currency: USD
revenue: '94930000000'
year: 2025
error: null
metadata:
next_page_token: AAAAAAAAAGQAAAAAAAAAZQ==
page_number: 1
request_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
total_items: 20
total_pages: 2
'404':
description: Instrument not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
InstrumentNotFound:
summary: Instrument identifier does not exist
value:
error:
code: 404
message: 'Instrument not found: AAP'
metadata:
request_id: fa8cc9b2-fbf0-4f5b-8ce3-b3205b9f85f2
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/market-data/daily-summary:
get:
tags:
- Instrument Data
summary: Get Daily Aggregate Summaries
description: 'Returns the most recent open, high, low, volume (OHLV) and current price
for the requested instruments.
Response contract: every request returns one row per **unique**
`instrument_id`, in first-seen request order. Unresolvable IDs come back
with `symbol = null` and every market-data field `null`; resolvable IDs
with no available data come back with `symbol` populated but market-data
fields `null`.'
operationId: get_daily_summaries
parameters:
- name: instrument_ids
in: query
description: Comma-separated instrument identifiers (required, 1..=100)
required: true
schema:
type: string
responses:
'200':
description: Daily aggregate summaries
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/DailySummaryList'
type: object
'400':
description: Missing, empty, or over-cap instrument_ids
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
/v1/market-data/snapshot:
get:
tags:
- Instrument Data
summary: Get Snapshots
description: Get market data snapshots for one or more securities.
operationId: get_snapshots
parameters:
- name: instrument_ids
in: query
description: Comma-separated instrument IDs (UUID) or symbols (equity tickers or OSI option symbols).
required: false
schema:
type: array
items:
$ref: '#/components/schemas/InstrumentIdOrSymbol'
# --- truncated at 32 KB (104 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clear-street/refs/heads/main/openapi/clear-street-instrument-data-api-openapi.yml