---
title: "One portfolio, priced. Open lots are rolled up into a position per instrument, each marked from its own price lane and labelled with the trading session that mark belongs to; a position that could not be priced carries nulls and a reason rather than a zero. Closed lots are listed with their realized profit and loss, and instruments watched but not held come in a separate `watching` array carrying marks only, outside every total. Totals are in the portfolio's `currency`; each position and lot states its own currency, with its figures converted at the official rates listed in `conversionRates`."
method: GET
path: "/v1/portfolios/{id}"
tags: ["Portfolios"]
---

# One portfolio, priced. Open lots are rolled up into a position per instrument, each marked from its own price lane and labelled with the trading session that mark belongs to; a position that could not be priced carries nulls and a reason rather than a zero. Closed lots are listed with their realized profit and loss, and instruments watched but not held come in a separate \`watching\` array carrying marks only, outside every total. Totals are in the portfolio's \`currency\`; each position and lot states its own currency, with its figures converted at the official rates listed in \`conversionRates\`.

`GET /v1/portfolios/{id}`

## Request

- Base URL: `https://api.equibles.com`
- URL: `https://api.equibles.com/v1/portfolios/{id}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/equibles/apis/equibles-api/docs/v1/portfolios/:id/get.ts> (a function with typed inputs; its response is checked against the schema)

## Path parameters

- `id` string, uuid, required

## Response `200`

OK

- PortfolioValuationResponse
  - `id` string, uuid
  - `name` string, nullable
  - `access` string, nullable: What you may do with it: Owner, Edit (change its lots and watches) or View.
  - `sharedBy` string, nullable: Who shared it with your organization. Absent on your own portfolios.
  - `asOfUtc` string, date-time: When this valuation was computed, UTC.
  - `currency` string, nullable: ISO 4217 code every total below is stated in.
  - `conversionRates` PortfolioFxRateDto[], nullable: The current official rate each position in another currency was converted at, dated by its observation. Empty when every holding is already in `currency`.
    - `from` string, nullable
    - `to` string, nullable
    - `rate` number, double
    - `asOf` string, date, nullable: The official observation date. Weekly releases make a rate a few days old normal.
  - `costBasis` number, double: Total paid across every open lot whose cost converts into `currency`, priced or not.
  - `marketValue` number, double, nullable: Sum over the positions that could be priced. Null when none could.
  - `unrealizedGain` number, double, nullable
  - `unrealizedGainPercent` number, double, nullable
  - `realizedGain` number, double: Profit or loss already taken, across every closed lot.
  - `unconvertedClosedLotCount` integer: Closed lots left out of realizedGain because no rate converts them.
  - `unvaluedPositionCount` integer: Open positions this pass could not price. Never silently excluded: a total computed over part of a portfolio reads as the whole one unless the gap is stated.
  - `unconvertedPositionCount` integer: Open positions left out of the totals because their cost or value could not be converted into `currency`; each says why in conversionUnavailableReason.
  - `coverageNote` string, nullable: Set when a bound stopped this pass from pricing everything, for example more distinct option contracts than one valuation may fetch. Null when nothing was cut.
  - `positions` PortfolioPositionDto[], nullable
    - `instrumentKind` string, nullable: Stock or Option.
    - `ticker` string, nullable
    - `exchange` string, nullable: The exchange's market identifier code (MIC, e.g. XPAR) for a listing outside the U.S.; null for a U.S. listing. Together with ticker it names the listing, e.g. XPAR:AIR.
    - `name` string, nullable
    - `occTicker` string, nullable: OCC option symbol. Null on a stock position.
    - `expirationDate` string, date, nullable
    - `strikePrice` number, double, nullable
    - `contractType` string, nullable: Call or Put. Null on a stock position.
    - `sharesPerContract` integer, nullable
    - `quantity` number, double: Signed total across the open lots; negative is a short position or a written option.
    - `currency` string, nullable: ISO 4217 code of the listing's currency: cost, mark, value and gains are in it. Null when the lots disagree, which leaves the position unvalued.
    - `costBasis` number, double
    - `averageCostPerUnit` number, double, nullable
    - `markPerUnit` number, double, nullable: Price per share the position is marked at. Null when this pass could not price it.
    - `markSource` string, nullable: Where the mark came from: LiveQuote, SettledClose, OptionDailyClose or OptionDelayedTrade, as the caller's plan allows. Null when there is no mark; read markUnavailableReason instead.
    - `markAsOf` string, date, nullable: The trading session the mark belongs to. Null when the source did not date it; for an option snapshot that means the session is unknown, never today.
    - `markUnavailableReason` string, nullable: Why there is no mark, in one short phrase. Null when the position is priced.
    - `marketValue` number, double, nullable
    - `unrealizedGain` number, double, nullable
    - `unrealizedGainPercent` number, double, nullable
    - `expired` boolean: True once an option contract's expiration has passed. An expired contract is never marked: it was exercised or expired worthless, and only the owner knows which.
    - `convertedCostBasis` number, double, nullable: Cost at each lot's purchase rate, in the portfolio's currency. Null when a lot has no rate.
    - `convertedMarketValue` number, double, nullable: Market value at the current official rate, in the portfolio's currency.
    - `convertedUnrealizedGain` number, double, nullable: Gain in the portfolio's currency, including the exchange-rate move since purchase.
    - `convertedUnrealizedGainPercent` number, double, nullable
    - `conversionUnavailableReason` string, nullable: Why a converted figure is null, in one short phrase.
    - `lots` PortfolioLotDto[], nullable
      - `id` string, uuid
      - `instrumentKind` string, nullable: Stock or Option.
      - `ticker` string, nullable: The listed symbol: the stock itself, or an option's underlying.
      - `exchange` string, nullable: The exchange's market identifier code (MIC, e.g. XPAR) for a listing outside the U.S.; null for a U.S. listing. Together with ticker it names the listing, e.g. XPAR:AIR.
      - `name` string, nullable
      - `occTicker` string, nullable: OCC option symbol, e.g. O:AAPL260116C00250000. Null on a stock lot.
      - `expirationDate` string, date, nullable
      - `strikePrice` number, double, nullable
      - `contractType` string, nullable: Call or Put. Null on a stock lot.
      - `sharesPerContract` integer, nullable: Shares of the underlying one contract controls — the P&L multiplier. Null on a stock lot.
      - `quantity` number, double: Signed: shares for a stock, contracts for an option; negative is short or written.
      - `costPerUnit` number, double: Price per share the lot was opened at, always positive. For an option, the premium per share of the underlying rather than per contract.
      - `costBasis` number, double, nullable
      - `currency` string, nullable: ISO 4217 code the lot's prices and own figures are in: its listing's currency.
      - `purchaseFxRate` number, double, nullable: The broker exchange rate recorded with the lot: units of purchaseFxCurrency per 1 unit of currency. Null when none was recorded.
      - `purchaseFxCurrency` string, nullable
      - `acquiredDate` string, date
      - `note` string, nullable
      - `closedDate` string, date, nullable: Set on a closed lot; null while the lot is open.
      - `closePricePerUnit` number, double, nullable
      - `marketValue` number, double, nullable: Null when this pass could not price the instrument — never a zero, which would read as a total loss.
      - `unrealizedGain` number, double, nullable
      - `realizedGain` number, double, nullable: Realized profit or loss on a closed lot; null while the lot is open.
      - `convertedCostBasis` number, double, nullable: The lot's figures in the portfolio's currency: cost at the purchase rate, value at the current rate, and a closed lot's proceeds at the official rate on its closing date. Null on a lot returned by a write, which carries no valuation.
      - `convertedMarketValue` number, double, nullable
      - `convertedUnrealizedGain` number, double, nullable
      - `convertedRealizedGain` number, double, nullable
      - `purchaseRate` PortfolioFxRateDto
        - `from` string, nullable
        - `to` string, nullable
        - `rate` number, double
        - `asOf` string, date, nullable: The official observation date. Weekly releases make a rate a few days old normal.
      - `closeRate` PortfolioFxRateDto
        - `from` string, nullable
        - `to` string, nullable
        - `rate` number, double
        - `asOf` string, date, nullable: The official observation date. Weekly releases make a rate a few days old normal.
      - `isOpen` boolean
  - `watching` PortfolioWatchDto[], nullable: Instruments watched but not held. They carry marks and nothing else, and are never part of costBasis, marketValue or any gain figure. A watched instrument the account also holds appears in positions only, carrying its watchId.
    - `id` string, uuid: The watch entry's id — what DELETE /v1/portfolios/{id}/watches/{watchId} takes.
    - `instrumentKind` string, nullable: "Stock" or "Option".
    - `ticker` string, nullable: The listed ticker: the stock itself, or the option's underlying.
    - `exchange` string, nullable: The exchange's market identifier code (MIC, e.g. XPAR) for a listing outside the U.S.; null for a U.S. listing. Together with ticker it names the listing, e.g. XPAR:AIR.
    - `name` string, nullable
    - `occTicker` string, nullable: The OCC contract symbol; null on a stock row.
    - `expirationDate` string, date, nullable
    - `strikePrice` number, double, nullable
    - `contractType` string, nullable: "Call" or "Put"; null on a stock row.
    - `sharesPerContract` integer, nullable
    - `currency` string, nullable: ISO 4217 code the mark is in: the listing's currency. Null when the listing states none, and on a row returned by a write, which carries no mark.
    - `markPerUnit` number, double, nullable: Price per share of the underlying. Null when this pass could not price it.
    - `markSource` string, nullable: Where the mark came from; null when unpriced.
    - `markAsOf` string, date, nullable: The trading session the mark belongs to. Null when the source did not date it.
    - `markUnavailableReason` string, nullable: Why there is no mark, when markSource is null.
    - `expired` boolean: True once a watched contract's expiration has passed.
  - `closedLots` PortfolioLotDto[], nullable: Closed lots, most recently closed first. They carry realized profit and loss and no market value.
    - `id` string, uuid
    - `instrumentKind` string, nullable: Stock or Option.
    - `ticker` string, nullable: The listed symbol: the stock itself, or an option's underlying.
    - `exchange` string, nullable: The exchange's market identifier code (MIC, e.g. XPAR) for a listing outside the U.S.; null for a U.S. listing. Together with ticker it names the listing, e.g. XPAR:AIR.
    - `name` string, nullable
    - `occTicker` string, nullable: OCC option symbol, e.g. O:AAPL260116C00250000. Null on a stock lot.
    - `expirationDate` string, date, nullable
    - `strikePrice` number, double, nullable
    - `contractType` string, nullable: Call or Put. Null on a stock lot.
    - `sharesPerContract` integer, nullable: Shares of the underlying one contract controls — the P&L multiplier. Null on a stock lot.
    - `quantity` number, double: Signed: shares for a stock, contracts for an option; negative is short or written.
    - `costPerUnit` number, double: Price per share the lot was opened at, always positive. For an option, the premium per share of the underlying rather than per contract.
    - `costBasis` number, double, nullable
    - `currency` string, nullable: ISO 4217 code the lot's prices and own figures are in: its listing's currency.
    - `purchaseFxRate` number, double, nullable: The broker exchange rate recorded with the lot: units of purchaseFxCurrency per 1 unit of currency. Null when none was recorded.
    - `purchaseFxCurrency` string, nullable
    - `acquiredDate` string, date
    - `note` string, nullable
    - `closedDate` string, date, nullable: Set on a closed lot; null while the lot is open.
    - `closePricePerUnit` number, double, nullable
    - `marketValue` number, double, nullable: Null when this pass could not price the instrument — never a zero, which would read as a total loss.
    - `unrealizedGain` number, double, nullable
    - `realizedGain` number, double, nullable: Realized profit or loss on a closed lot; null while the lot is open.
    - `convertedCostBasis` number, double, nullable: The lot's figures in the portfolio's currency: cost at the purchase rate, value at the current rate, and a closed lot's proceeds at the official rate on its closing date. Null on a lot returned by a write, which carries no valuation.
    - `convertedMarketValue` number, double, nullable
    - `convertedUnrealizedGain` number, double, nullable
    - `convertedRealizedGain` number, double, nullable
    - `purchaseRate` PortfolioFxRateDto
      - `from` string, nullable
      - `to` string, nullable
      - `rate` number, double
      - `asOf` string, date, nullable: The official observation date. Weekly releases make a rate a few days old normal.
    - `closeRate` PortfolioFxRateDto
      - `from` string, nullable
      - `to` string, nullable
      - `rate` number, double
      - `asOf` string, date, nullable: The official observation date. Weekly releases make a rate a few days old normal.
    - `isOpen` boolean

## Other responses

- `400`: Invalid request — a malformed parameter value or a query parameter this endpoint does not support.
- `404`: Not Found

---

[API](https://skmtc.dev/equibles/apis/equibles-api.md) - [All operations](https://skmtc.dev/equibles/apis/equibles-api/llms.txt) - [OpenAPI document](https://skmtc.dev/equibles/apis/equibles-api/revisions/879ad16326ad?raw)