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
| Name | Required | Type | Description |
|---|---|---|---|
| tag | Optional | string | Return 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
- 200
- 4XX
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"
}
]
}
| Name | Type | Description |
|---|---|---|
| status | string | Outcome of the request. Typically success. |
| data | object[] | List of US stocks orders for the day. |
| data[].order_id | string | Unique order ID. |
| data[].instrument_key | string | US instrument key, for example US_EQ|AAPL. |
| data[].trading_symbol | string | Ticker symbol of the stock. |
| data[].name | string | Company name. |
| data[].exchange | string | Exchange of the order. Always US. |
| data[].order_type | string | Order type. Possible values: MARKET, LIMIT. |
| data[].validity | string | Order validity. Always DAY. |
| data[].transaction_type | string | Possible values: BUY, SELL. |
| data[].price | number | Limit price in USD. |
| data[].average_price | number | Average traded price in USD. |
| data[].quantity | number | Ordered 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_quantity | number | Shares traded so far. |
| data[].pending_quantity | number | Shares still to be traded. 0 once the order has finished (complete, cancelled, cancelled_partially, failed, failed_partially or expired). |
| data[].amount | number | USD amount for an order placed by amount. null for an order placed by quantity. |
| data[].status | string | Order 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_message | string | Reason for the current status, such as a rejection reason. |
| data[].status_message_raw | string | Unformatted status message from the US broker. |
| data[].order_timestamp | string | When the order was placed, in IST. Format: yyyy-MM-dd HH:mm:ss. |
| data[].exchange_timestamp | string | When the order was last updated, in IST. Format: yyyy-MM-dd HH:mm:ss. |
| data[].is_amo | boolean | Whether the order was placed as an after-market order. Set automatically from the US market status when the order is placed. |
| data[].fractionable | boolean | Whether the stock allows fractional quantities. null when the stock is not in the US instruments file. |
| data[].variety | string | Order variety. Always REGULAR. |
| data[].tag | string | Tag 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. |
Error codes
| Error code | Description |
|---|---|
| UDAPI1119 | tag length exceeds limit - tag can be up to 40 characters. |
| UDAPI1316 | US stocks is not activated for this account - Returned with HTTP 403. |
| UDAPI1317 | US stocks order service is unavailable. Please try again later. - Returned with HTTP 423. |
| UDAPI1318 | US stocks trading is in its daily maintenance window. Please try again later. - Returned with HTTP 423. |
Sample Code
Get the US stocks order book
- Python
- Node.js
- Java
- PHP
- Python SDK
- Node.js SDK
- Java SDK
- PHP SDK
- .NET SDK
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())
const axios = require('axios');
const url = 'https://api.upstox.com/v2/us/order/retrieve-all';
const headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
};
axios.get(url, { headers })
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error(error.response ? error.response.data : error.message);
});
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.upstox.com/v2/us/order/retrieve-all"))
.header("Accept", "application/json")
.header("Authorization", "Bearer {your_access_token}")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
<?php
$url = 'https://api.upstox.com/v2/us/order/retrieve-all';
$headers = [
'Accept: application/json',
'Authorization: Bearer {your_access_token}',
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Error: ' . curl_error($ch);
} else {
echo $response;
}
curl_close($ch);
?>
import upstox_client
from upstox_client.rest import ApiException
configuration = upstox_client.Configuration()
configuration.access_token = '{your_access_token}'
api_instance = upstox_client.UsStocksOrderApi(upstox_client.ApiClient(configuration))
try:
api_response = api_instance.get_us_order_book()
print(api_response)
except ApiException as e:
print("Exception when calling UsStocksOrderApi->get_us_order_book: %s\n" % e)
let UpstoxClient = require('upstox-js-sdk');
let defaultClient = UpstoxClient.ApiClient.instance;
var OAUTH2 = defaultClient.authentications['OAUTH2'];
OAUTH2.accessToken = "{your_access_token}";
let apiInstance = new UpstoxClient.USStocksOrderApi();
apiInstance.getUsOrderBook({}, (error, data, response) => {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + JSON.stringify(data));
}
});
import com.upstox.ApiClient;
import com.upstox.ApiException;
import com.upstox.Configuration;
import com.upstox.api.UsOrderBookResponse;
import com.upstox.auth.OAuth;
import io.swagger.client.api.UsStocksOrderApi;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
OAuth OAUTH2 = (OAuth) defaultClient.getAuthentication("OAUTH2");
OAUTH2.setAccessToken("{your_access_token}");
UsStocksOrderApi apiInstance = new UsStocksOrderApi();
String tag = null; // optional: return only orders placed with this tag
try {
UsOrderBookResponse result = apiInstance.getUsOrderBook(tag);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling UsStocksOrderApi#getUsOrderBook");
e.printStackTrace();
}
}
}
<?php
$config = (new Upstox\Client\Configuration())
->setAccessToken('{your_access_token}');
$apiInstance = new Upstox\Client\Api\USStocksOrderApi(
new GuzzleHttp\Client(),
$config
);
try {
$result = $apiInstance->getUsOrderBook();
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling USStocksOrderApi->getUsOrderBook: ' . $e->getMessage();
}
using UpstoxClient.Api;
using UpstoxClient.Client;
using UpstoxClient.Extensions;
using UpstoxClient.Model;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
var host = Host.CreateDefaultBuilder()
.ConfigureApi((context, services, options) =>
{
options.AddTokens(new OAuthToken("{your_access_token}"));
}).Build();
await host.StartAsync();
var apiInstance = host.Services.GetRequiredService<IUSStocksOrderApi>();
try
{
var response = await apiInstance.GetUsOrderBookAsync();
Console.WriteLine(response.RawContent);
}
catch (Exception e)
{
Console.WriteLine("Exception: " + e.Message);
}
await host.StopAsync();
Get orders with a tag
- Python
- Node.js
- Java
- PHP
- Python SDK
- Node.js SDK
- Java SDK
- PHP SDK
- .NET SDK
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())
const axios = require('axios');
const url = 'https://api.upstox.com/v2/us/order/retrieve-all';
const headers = {
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
};
axios.get(url, { headers, params: { tag: 'my-strategy' } })
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error(error.response ? error.response.data : error.message);
});
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.upstox.com/v2/us/order/retrieve-all?tag=my-strategy"))
.header("Accept", "application/json")
.header("Authorization", "Bearer {your_access_token}")
.GET()
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
<?php
$url = 'https://api.upstox.com/v2/us/order/retrieve-all?' . http_build_query(['tag' => 'my-strategy']);
$headers = [
'Accept: application/json',
'Authorization: Bearer {your_access_token}',
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Error: ' . curl_error($ch);
} else {
echo $response;
}
curl_close($ch);
?>
import upstox_client
from upstox_client.rest import ApiException
configuration = upstox_client.Configuration()
configuration.access_token = '{your_access_token}'
api_instance = upstox_client.UsStocksOrderApi(upstox_client.ApiClient(configuration))
try:
api_response = api_instance.get_us_order_book(tag='my-strategy')
print(api_response)
except ApiException as e:
print("Exception when calling UsStocksOrderApi->get_us_order_book: %s\n" % e)
let UpstoxClient = require('upstox-js-sdk');
let defaultClient = UpstoxClient.ApiClient.instance;
var OAUTH2 = defaultClient.authentications['OAUTH2'];
OAUTH2.accessToken = "{your_access_token}";
let apiInstance = new UpstoxClient.USStocksOrderApi();
let opts = { tag: "my-strategy" };
apiInstance.getUsOrderBook(opts, (error, data, response) => {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + JSON.stringify(data));
}
});
import com.upstox.ApiClient;
import com.upstox.ApiException;
import com.upstox.Configuration;
import com.upstox.api.UsOrderBookResponse;
import com.upstox.auth.OAuth;
import io.swagger.client.api.UsStocksOrderApi;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
OAuth OAUTH2 = (OAuth) defaultClient.getAuthentication("OAUTH2");
OAUTH2.setAccessToken("{your_access_token}");
UsStocksOrderApi apiInstance = new UsStocksOrderApi();
String tag = "my-strategy";
try {
UsOrderBookResponse result = apiInstance.getUsOrderBook(tag);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling UsStocksOrderApi#getUsOrderBook");
e.printStackTrace();
}
}
}
<?php
$config = (new Upstox\Client\Configuration())
->setAccessToken('{your_access_token}');
$apiInstance = new Upstox\Client\Api\USStocksOrderApi(
new GuzzleHttp\Client(),
$config
);
try {
$result = $apiInstance->getUsOrderBook('my-strategy');
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling USStocksOrderApi->getUsOrderBook: ' . $e->getMessage();
}
using UpstoxClient.Api;
using UpstoxClient.Client;
using UpstoxClient.Extensions;
using UpstoxClient.Model;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
var host = Host.CreateDefaultBuilder()
.ConfigureApi((context, services, options) =>
{
options.AddTokens(new OAuthToken("{your_access_token}"));
}).Build();
await host.StartAsync();
var apiInstance = host.Services.GetRequiredService<IUSStocksOrderApi>();
try
{
var response = await apiInstance.GetUsOrderBookAsync(tag: "my-strategy");
Console.WriteLine(response.RawContent);
}
catch (Exception e)
{
Console.WriteLine("Exception: " + e.Message);
}
await host.StopAsync();