The Positions API from Clear Street — 6 operation(s) for positions.
openapi: 3.2.0
info:
title: Clear Street Positions API
version: '1.0'
description: 'Operations tagged Positions across 2 of this provider''s published API definitions: clear-street-studio-openapi.yml, clear-street-trading-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.clearstreet.io/studio/v2
description: Production environment
- url: https://sandbox-api.clearstreet.io/studio/v2
description: Sandbox environment
- 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
tags:
- name: Positions
x-displayName: Positions
paths:
/accounts/{account_id}/positions/{symbol}:
servers:
- url: https://api.clearstreet.io/studio/v2
description: Production environment
- url: https://sandbox-api.clearstreet.io/studio/v2
description: Sandbox environment
get:
operationId: getPosition
summary: Get position
description: Get current position for a given account for a given symbol.
tags:
- Positions
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/AccountId'
description: The account ID or account number to get the position for.
- in: path
name: symbol
required: true
schema:
$ref: '#/components/schemas/Symbol'
description: Symbol to get position for.
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Position'
default:
$ref: '#/components/responses/error'
security:
- BearerAuth: []
/accounts/{account_id}/positions:
servers:
- url: https://api.clearstreet.io/studio/v2
description: Production environment
- url: https://sandbox-api.clearstreet.io/studio/v2
description: Sandbox environment
get:
operationId: listPositions
summary: List positions
description: List current positions for a given account.
tags:
- Positions
parameters:
- in: path
name: account_id
required: true
schema:
$ref: '#/components/schemas/AccountId'
description: The account ID or account number to list positions for.
- in: query
name: page_size
schema:
type: integer
minimum: 1
maximum: 2000
default: 25
description: Number of positions to return per page.
- in: query
name: page_token
schema:
type: string
description: Cursor for the page to return.
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Position'
next_page_token:
type: string
description: Cursor for the next page of results.
required:
- data
default:
$ref: '#/components/responses/error'
security:
- BearerAuth: []
/v1/accounts/{account_id}/positions:
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
get:
tags:
- Positions
summary: Get Positions
description: Retrieves all positions for the specified trading account.
operationId: get_positions
parameters:
- name: account_id
in: path
description: Account identifier
required: true
schema:
$ref: '#/components/schemas/i64'
- 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: instrument_ids
in: query
description: Comma-separated instrument identifiers
required: false
schema:
type: array
items:
type: string
format: uuid
style: form
explode: false
- name: sort_by
in: query
description: Field to sort by
required: false
schema:
type: string
enum:
- SYMBOL
- INSTRUMENT_TYPE
- QUANTITY
- MARKET_VALUE
- POSITION_TYPE
- UNREALIZED_PNL
- DAILY_UNREALIZED_PNL
- DAILY_REALIZED_PNL
- name: sort_direction
in: query
description: Sort direction
required: false
schema:
type: string
description: Sort direction sorted results
enum:
- ASC
- DESC
responses:
'200':
description: List of positions
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PositionList'
type: object
examples:
LongAndShortPositions:
summary: A list containing long equity, short equity, and long call option positions with all fields populated
value:
data:
- account_id: 19816
available_quantity: '100'
avg_price: '145.00'
closing_price: '150.50'
closing_price_date: 2025-10-31
cost_basis: '14500.00'
daily_realized_pnl: '700.00'
instrument_id: a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8
instrument_price: '151.00'
instrument_type: COMMON_STOCK
market_value: '15050.00'
position_type: LONG
quantity: '100'
symbol: AAPL
unrealized_pnl: '550.00'
- account_id: 19816
available_quantity: '100'
avg_price: '180.00'
closing_price: '180.00'
closing_price_date: 2025-10-30
cost_basis: '-9000.00'
daily_realized_pnl: '25.00'
instrument_id: d4d5d6d7-e4e5-f4f5-a4a5-a6a7a8a9aaab
instrument_price: '178.50'
instrument_type: COMMON_STOCK
market_value: '-9000.00'
position_type: SHORT
quantity: '-50'
symbol: TSLA
unrealized_pnl: '75.00'
- account_id: 19816
available_quantity: '100'
avg_price: '2.50'
closing_price: '2.70'
closing_price_date: 2025-10-30
cost_basis: '2500.00'
daily_realized_pnl: '10.00'
instrument_id: e5e6e7e8-f5f6-a5a6-b5b6-b7b8b9babcbe
instrument_price: '2.72'
instrument_type: OPTION
market_value: '2700.00'
position_type: LONG
quantity: '10'
symbol: AAPL250117C00190000
underlying_instrument_id: a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8
unrealized_pnl: '200.00'
error: null
metadata:
next_page_token: cGFnZT0yJmxhc3Rfc3ltYm9sPVRTM0E=
page_number: 1
request_id: 3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c
total_items: 25
total_pages: 3
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Forbidden:
summary: Caller does not have permission
value:
error:
code: 403
message: The caller does not have permission to execute the specified operation
metadata:
request_id: 5518f0c6-58ff-4b4a-81a5-701556d41206
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- BearerAuth: []
delete:
tags:
- Positions
summary: Close Positions
description: 'Delete all positions within an account.
Closes all positions for the specified trading account.'
operationId: close_positions
parameters:
- name: account_id
in: path
description: Account identifier
required: true
schema:
$ref: '#/components/schemas/i64'
requestBody:
content:
application/json:
schema:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/ClosePositionRequest'
responses:
'200':
description: List of orders generated to close all positions.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/OrderList'
type: object
examples:
FlattenAccount:
summary: A list containing orders statuses for the orders used to close all positions in the account.
value:
data:
- account_id: 19816
average_fill_price: null
client_order_id: close-positions-20251003-001
created_at: 2025-10-03 14:01:15+00:00
filled_quantity: '0'
id: 019c0b57-0850-7b0b-8a2c-5ee3fb5a5876
instrument_id: c3c4c5c6-d3d4-e3e4-f3f4-f5f6f7f8f9fa
instrument_type: COMMON_STOCK
leaves_quantity: '25'
limit_price: null
order_type: MARKET
quantity: '25'
side: SELL
status: PENDING_NEW
stop_price: null
symbol: GOOG
time_in_force: DAY
updated_at: 2025-10-03 14:01:15+00:00
venue: XNMS
error: null
metadata:
request_id: 3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
MalformedPayload:
summary: Malformed JSON in request body
value:
error:
code: 400
message: 'Failed to parse the request body as JSON: expected `:` at line 2 column 19'
metadata:
request_id: 93a7c482-b246-4e15-9618-bcbe0906b815
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Forbidden:
summary: Caller does not have permission
value:
error:
code: 403
message: The caller does not have permission to execute the specified operation
metadata:
request_id: 5518f0c6-58ff-4b4a-81a5-701556d41206
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- BearerAuth: []
/v1/accounts/{account_id}/positions/instructions:
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
get:
tags:
- Positions
summary: Get Position Instructions
description: 'Returns the current lifecycle state of the account''s position
instructions. Optionally filter by a specific contract.
Note: instructions that fail pre-acceptance validation on `POST` —
duplicates, `DO_NOT_EXERCISE` / `CONTRARY_EXERCISE` on a non-expiry day,
insufficient position, or an unresolvable instrument — are rejected
(with `status = REJECTED` and a `rejection_reason`) without being
persisted, so they surface only in the `POST` response and never appear
in this list.'
operationId: get_position_instructions
parameters:
- name: account_id
in: path
description: Account identifier
required: true
schema:
$ref: '#/components/schemas/i64'
- name: instrument_id
in: query
description: Limit results to a single contract. Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).
required: false
schema:
$ref: '#/components/schemas/InstrumentIdOrSymbol'
responses:
'200':
description: Position instructions
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PositionInstructionList'
type: object
'400':
description: Invalid query parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Account or instrument not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'503':
description: Service temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- BearerAuth: []
post:
tags:
- Positions
summary: Submit Position Instructions
description: "Submit one or more position instructions (Exercise, Do-Not-Exercise,\nContrary Exercise Advice) against the account.\n\nBatch semantics:\n- **All rows accepted** → `200 OK`. Every row is in `data` with\n `status = SENT`.\n- **Partial success** → `207 Multi-Status`. `data` contains every\n row; rejected rows carry `status = REJECTED` and\n `rejection_reason`. The top-level `error` summarizes the batch\n failure.\n- **All rows rejected** → `4xx`/`5xx`. The HTTP status reflects\n the aggregate cause: `409` when every row was a duplicate, `400`\n for validation failures like DNE/CEA on a non-expiry day, `503`\n if the clearing service is unavailable. `data` still contains\n every row carrying `status = REJECTED` and `rejection_reason`\n so callers can attribute failures by `instruction_id`; the\n top-level `error` summarizes the batch."
operationId: submit_position_instructions
parameters:
- name: account_id
in: path
description: Account identifier
required: true
schema:
$ref: '#/components/schemas/i64'
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PositionInstructionSubmissionRequest'
required: true
responses:
'200':
description: All instructions accepted
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PositionInstructionList'
type: object
examples:
AllAccepted:
summary: Every row accepted — each carries status=SENT
value:
data:
- account_id: 122503
id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02
instruction_id: ui-20260424-001
instruction_type: EXERCISE
instrument_id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01
quantity: '1'
status: SENT
symbol: AAPL 280121C00195000
metadata:
request_id: 0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd01
'207':
description: Partial success — some rows accepted, others rejected
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PositionInstructionList'
type: object
examples:
PartialDuplicate:
summary: One row accepted, one rejected as duplicate
value:
data:
- account_id: 122503
id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e02
instruction_id: ui-20260424-001
instruction_type: EXERCISE
instrument_id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01
quantity: '1'
status: SENT
symbol: AAPL 280121C00195000
- account_id: 122503
id: 00000000-0000-0000-0000-000000000000
instruction_id: ui-20260424-001
instruction_type: EXERCISE
instrument_id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01
quantity: '1'
rejection_reason: Duplicate exercise instruction
status: REJECTED
symbol: AAPL 280121C00195000
error:
code: 409
message: Duplicate exercise instruction
metadata:
request_id: 0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd02
'400':
description: Invalid request or all rows rejected by validation
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PositionInstructionList'
type: object
examples:
DneOutsideExpiry:
summary: All rows rejected — DNE submitted outside the expiration date
value:
data:
- account_id: 122503
id: 00000000-0000-0000-0000-000000000000
instruction_id: ui-20260424-001
instruction_type: DO_NOT_EXERCISE
instrument_id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01
quantity: '1'
rejection_reason: DO_NOT_EXERCISE must be submitted on the contract's expiration date
status: REJECTED
symbol: AAPL 280121C00195000
error:
code: 400
message: DO_NOT_EXERCISE must be submitted on the contract's expiration date
metadata:
request_id: 0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd03
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Account or instrument not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'409':
description: All rows rejected as duplicates
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PositionInstructionList'
type: object
examples:
AllDuplicates:
summary: Every submitted instruction_id was already accepted earlier
value:
data:
- account_id: 122503
id: 00000000-0000-0000-0000-000000000000
instruction_id: ui-20260424-001
instruction_type: EXERCISE
instrument_id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01
quantity: '1'
rejection_reason: Duplicate exercise instruction; existing_id=019e7415-de03-70c3-8ca1-9fdb72dfdbbc
status: REJECTED
symbol: AAPL 280121C00195000
error:
code: 409
message: Duplicate exercise instruction
metadata:
request_id: 0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd04
'500':
description: All rows rejected by an internal server fault
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PositionInstructionList'
type: object
examples:
AllInternalFault:
summary: Every row failed because of an internal server fault
value:
data:
- account_id: 122503
id: 00000000-0000-0000-0000-000000000000
instruction_id: ui-20260424-001
instruction_type: EXERCISE
instrument_id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01
quantity: '1'
rejection_reason: Could not process the instruction
status: REJECTED
symbol: AAPL 280121C00195000
error:
code: 500
message: Could not process the instruction
metadata:
request_id: 0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd05
'503':
description: All rows rejected because the clearing service was unavailable
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PositionInstructionList'
type: object
examples:
AllUnavailable:
summary: Every row failed because the clearing service was unavailable
value:
data:
- account_id: 122503
id: 00000000-0000-0000-0000-000000000000
instruction_id: ui-20260424-001
instruction_type: EXERCISE
instrument_id: 0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01
quantity: '1'
rejection_reason: Clearing service unavailable
status: REJECTED
symbol: AAPL 280121C00195000
error:
code: 503
message: Clearing service unavailable
metadata:
request_id: 0a5c9ebf-a9a7-4f2d-9c7e-f2b5f0b1bd06
security:
- BearerAuth: []
/v1/accounts/{account_id}/positions/instructions/{instruction_id}:
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
delete:
tags:
- Positions
summary: Cancel Position Instruction
description: 'Cancel an outstanding position instruction by its server-assigned `id`.
Returns the updated instruction with status `CANCEL_REQUESTED`. The
terminal `CANCELLED` or `CANCEL_FAILED` state arrives asynchronously and
is observable via subsequent GETs.'
operationId: cancel_position_instruction
parameters:
- name: account_id
in: path
description: Account identifier
required: true
schema:
$ref: '#/components/schemas/i64'
- name: instruction_id
in: path
description: Server-assigned instruction id
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Cancel accepted
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/PositionInstruction'
type: object
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Instruction not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'409':
description: Instruction is in a terminal state
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'503':
description: Service temporarily unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- BearerAuth: []
/v1/accounts/{account_id}/positions/{instrument_id}:
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
delete:
tags:
- Positions
summary: Close Position
description: 'Delete a position within an account for an instrument.
Retrieves orders generated to close the position.'
operationId: close_position
parameters:
- name: account_id
in: path
description: Account identifier
required: true
schema:
$ref: '#/components/schemas/i64'
- name: instrument_id
in: path
description: Instrument ID (UUID) or symbol (equity ticker or OSI option symbol).
required: true
schema:
$ref: '#/components/schemas/InstrumentIdOrSymbol'
requestBody:
content:
application/json:
schema:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/ClosePositionRequest'
responses:
'200':
description: List of orders generated to close the position.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BaseResponse'
- type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/OrderList'
type: object
examples:
LongAndShortPositions:
summary: A list containing orders statuses for the orders used to close the position of the specified instrument.
value:
data:
- account_id: 19816
average_fill_price: null
client_order_id: close-position-20251003-001
created_at: 2025-10-03 14:01:15+00:00
filled_quantity: '0'
id: 019c0b56-2119-7482-a80f-5a2a316524d9
instrument_id: c3c4c5c6-d3d4-e3e4-f3f4-f5f6f7f8f9fa
instrument_type: COMMON_STOCK
leaves_quantity: '25'
limit_price: null
order_type: MARKET
quantity: '25'
side: SELL
status: PENDING_NEW
stop_price: null
symbol: GOOG
time_in_force: DAY
updated_at: 2025-10-03 14:01:15+00:00
venue: XNMS
error: null
metadata:
request_id: 3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
MalformedPayload:
summary: Malformed JSON in request body
value:
error:
code: 400
message: 'Failed to parse the request body as JSON: expected `:` at line 2 column 19'
metadata:
request_id: 93a7c482-b246-4e15-9618-bcbe0906b815
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
examples:
Forbidden:
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clear-street/refs/heads/main/openapi/clear-street-positions-api-openapi.yml