> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bluumfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Positions

> Holdings, cost basis, market value, and unrealized P&L.

A **position** is a user's holding in a single asset — how many shares, at what average cost, worth how much now, and up or down by how much. Positions are created when buy orders fill and updated as prices move and further orders execute. Each carries a prefixed `pos_` id.

## Core fields

| Field                | Description                            |
| -------------------- | -------------------------------------- |
| `symbol`             | Ticker symbol                          |
| `quantity`           | Shares held (may be fractional)        |
| `average_cost_basis` | Volume-weighted average purchase price |
| `market_value`       | `quantity × current_price`             |
| `unrealized_pl`      | `market_value − total cost basis`      |
| `current_price`      | Latest market price                    |

Positions also expose the currency, total cost basis, price freshness, and timestamps — see the API reference for the complete schema.

## How positions change

| Event       | Effect                                                               |
| ----------- | -------------------------------------------------------------------- |
| Buy fills   | Creates or increases the position; recalculates `average_cost_basis` |
| Sell fills  | Decreases the position; removed when fully sold                      |
| Price moves | Updates `current_price`, `market_value`, `unrealized_pl`             |

## Reading positions

List all positions for an investor, or fetch one by its `pos_` id:

* `GET /v1/investors/{investor_id}/positions`
* `GET /v1/investors/{investor_id}/positions/{position_id}`

<Note>
  To retrieve and interpret holdings step by step, see the journey guide:
  [Track positions](/get-started/journey/track-positions). Position schemas are in the
  [API reference](/api-reference/introduction).
</Note>