Skip to main content
GET 

/us/order/retrieve-all

Get Order Book

API to retrieve all US stocks orders for the day, in every state. Prices and amounts are in USD, and quantities can be fractional.

To see only the orders of one strategy, pass the tag you sent when placing the orders. Without tag, the full order book is returned.

Query Parameters​

NameRequiredTypeDescription
tagOptionalstringReturn only orders placed with this tag. The match is exact and case-sensitive. Up to 40 characters. If no order has the tag, data is an empty array.

Request​

curl --location 'https://api.upstox.com/v2/us/order/retrieve-all' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your_access_token}'

For samples in other languages, see the Sample Code section on this page.

Responses​

Response Body​

{
"status": "success",
"data": [
{
"order_id": "1a9ecf08-e5f8-475c-a7c0-9056826d4b18",
"instrument_key": "US_EQ|AAPL",
"trading_symbol": "AAPL",
"name": "Apple Inc.",
"exchange": "US",
"order_type": "LIMIT",
"validity": "DAY",
"transaction_type": "BUY",
"price": 180.25,
"average_price": 180.2,
"quantity": 1.5,
"filled_quantity": 1.5,
"pending_quantity": 0,
"amount": null,
"status": "complete",
"status_message": "",
"status_message_raw": "",
"order_timestamp": "2026-10-22 19:05:12",
"exchange_timestamp": "2026-10-22 19:05:13",
"is_amo": false,
"fractionable": true,
"variety": "REGULAR",
"tag": "my-strategy"
}
]
}
NameTypeDescription
statusstringOutcome of the request. Typically success.
dataobject[]List of US stocks orders for the day.
data[].order_idstringUnique order ID.
data[].instrument_keystringUS instrument key, for example US_EQ|AAPL.
data[].trading_symbolstringTicker symbol of the stock.
data[].namestringCompany name.
data[].exchangestringExchange of the order. Always US.
data[].order_typestringOrder type. Possible values: MARKET, LIMIT.
data[].validitystringOrder validity. Always DAY.
data[].transaction_typestringPossible values: BUY, SELL.
data[].pricenumberLimit price in USD.
data[].average_pricenumberAverage traded price in USD.
data[].quantitynumberOrdered shares. Can be fractional. For an amount order, the shares the amount buys: amount ÷ limit price for a LIMIT order, or ÷ last traded price for a MARKET order, until the order completes, then the shares traded. null when the last traded price is unavailable.
data[].filled_quantitynumberShares traded so far.
data[].pending_quantitynumberShares still to be traded. 0 once the order has finished (complete, cancelled, cancelled_partially, failed, failed_partially or expired).
data[].amountnumberUSD amount for an order placed by amount. null for an order placed by quantity.
data[].statusstringOrder status. Possible values: open, scheduled, queued, partially_complete, complete, cancelled, cancelled_partially, failed, failed_partially, expired. An open order shows as scheduled while the US market is not in its regular session.
data[].status_messagestringReason for the current status, such as a rejection reason.
data[].status_message_rawstringUnformatted status message from the US broker.
data[].order_timestampstringWhen the order was placed, in IST. Format: yyyy-MM-dd HH:mm:ss.
data[].exchange_timestampstringWhen the order was last updated, in IST. Format: yyyy-MM-dd HH:mm:ss.
data[].is_amobooleanWhether the order was placed as an after-market order. Set automatically from the US market status when the order is placed.
data[].fractionablebooleanWhether the stock allows fractional quantities. null when the stock is not in the US instruments file.
data[].varietystringOrder variety. Always REGULAR.
data[].tagstringTag sent when the order was placed. Kept until the end of the US trading day the order runs on, so an after-market order keeps its tag through the next trading day.

Sample Code​

Get the US stocks order book​

import requests

url = 'https://api.upstox.com/v2/us/order/retrieve-all'
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
}

response = requests.get(url, headers=headers)

print(response.status_code)
print(response.json())

Get orders with a tag​

import requests

url = 'https://api.upstox.com/v2/us/order/retrieve-all'
headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
}

params = {'tag': 'my-strategy'}

response = requests.get(url, headers=headers, params=params)

print(response.status_code)
print(response.json())