GET/us/portfolio/holdings
Get Holdings
API to retrieve the US stocks held in the user's account. Prices are in USD, and quantities can be fractional. Each holding is valued at the last traded price. If market data is unavailable, holdings are still returned with the price, value and P&L fields set to null.
Request
curl --location 'https://api.upstox.com/v2/us/portfolio/holdings' \
--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": [
{
"instrument_key": "US_EQ|AAPL",
"trading_symbol": "AAPL",
"company_name": "Apple Inc.",
"exchange": "US_EQ",
"average_price": 180.25,
"quantity": 1.5,
"available_quantity": 1.5,
"transaction_type": "long",
"invested_value": 270.38,
"last_price": 230.00,
"previous_close": 232.00,
"current_value": 345.00,
"pnl": 74.63,
"day_pnl": -3.00
}
]
}
| Name | Type | Description |
|---|---|---|
| status | string | Outcome of the request. Typically success. |
| data | object[] | List of US stocks holdings. |
| data[].instrument_key | string | US instrument key, for example US_EQ|AAPL. |
| data[].trading_symbol | string | Ticker symbol of the stock. |
| data[].company_name | string | Company name. |
| data[].exchange | string | Segment of the holding. Always US_EQ. |
| data[].average_price | number | Average buy price in USD. |
| data[].quantity | number | Shares held. Can be fractional. |
| data[].available_quantity | number | Shares free to sell. |
| data[].transaction_type | string | Position direction. Possible values: long, short. |
| data[].invested_value | number | quantity × average_price, in USD. |
| data[].last_price | number | Last traded price in USD. null when market data is unavailable. |
| data[].previous_close | number | Previous close in USD. null when market data is unavailable. |
| data[].current_value | number | quantity × last_price, in USD. null when last_price is null. |
| data[].pnl | number | Unrealised P&L in USD: current_value minus invested_value. Negated for a short position. |
| data[].day_pnl | number | Today's P&L in USD: quantity × (last_price minus previous_close). Negated for a short position. null when either price is unavailable. |
Error codes
| Error code | Description |
|---|---|
| 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 US stocks holdings
- 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/portfolio/holdings'
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/portfolio/holdings';
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/portfolio/holdings"))
.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/portfolio/holdings';
$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.UsStocksPortfolioApi(upstox_client.ApiClient(configuration))
try:
api_response = api_instance.get_us_holdings()
print(api_response)
except ApiException as e:
print("Exception when calling UsStocksPortfolioApi->get_us_holdings: %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.USStocksPortfolioApi();
apiInstance.getUsHoldings((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.UsHoldingsResponse;
import com.upstox.auth.OAuth;
import io.swagger.client.api.UsStocksPortfolioApi;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
OAuth OAUTH2 = (OAuth) defaultClient.getAuthentication("OAUTH2");
OAUTH2.setAccessToken("{your_access_token}");
UsStocksPortfolioApi apiInstance = new UsStocksPortfolioApi();
try {
UsHoldingsResponse result = apiInstance.getUsHoldings();
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling UsStocksPortfolioApi#getUsHoldings");
e.printStackTrace();
}
}
}
<?php
$config = (new Upstox\Client\Configuration())
->setAccessToken('{your_access_token}');
$apiInstance = new Upstox\Client\Api\USStocksPortfolioApi(
new GuzzleHttp\Client(),
$config
);
try {
$result = $apiInstance->getUsHoldings();
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling USStocksPortfolioApi->getUsHoldings: ' . $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<IUSStocksPortfolioApi>();
try
{
var response = await apiInstance.GetUsHoldingsAsync();
Console.WriteLine(response.RawContent);
}
catch (Exception e)
{
Console.WriteLine("Exception: " + e.Message);
}
await host.StopAsync();