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

# Get live positioning across all accounts

> Every open position of your organization in one call, each with the account's plan, type and trader, plus the contract details needed to group and value exposure.

Use it to build an aggregated book (net long/short per product, by plan or account type) and keep it current with the real-time trading stream (`POST .../trading-accounts/stream-token`, connect with `v=2`): connect first, then read with `fresh=true`, and apply each `PositionUpdate` whose `state_version` is not lower than the position's `stateVersion` in the same `stateEpoch`. When the stream reports an account this read did not include, read it with `accountId`.

When `source` is `live`, the answer already reflects every change within about a second, with or without `fresh`. Otherwise results without `fresh` are shared for up to 15 seconds, and newly created accounts appear within a minute. About 60 requests per minute per organization.

## Example

```bash
curl "https://api.hyperprop.com/platform/v1/organization/risk/positioning" \
  -H "X-API-Key: hp_live_your_key_here"
```

**Permissions:** requires **view** access to "Traders & accounts".

**Access:** read-only and full-access API keys. Dashboard members need view access to Traders & accounts.



## OpenAPI

````yaml https://api.hyperprop.com/platform/openapi.json get /v1/organization/risk/positioning
openapi: 3.0.0
info:
  title: Hyperprop Platform API
  version: 1.0.0
  description: >-
    REST API for the Hyperprop Trading Platform — provision evaluation and
    funded trading accounts, manage traders and plans, react to account
    lifecycle events via signed webhooks, and reconcile billing. Built for prop
    firms integrating from their own backend.


    Authentication, quick start, error handling, idempotency, pagination, custom
    metadata, webhooks, and the MCP connector are documented at
    https://docs.hyperprop.com.
  x-logo:
    url: https://app.hyperprop.com/logo-icon.svg
    altText: Hyperprop
    href: https://hyperprop.com
servers:
  - url: https://api.hyperprop.com/platform
    description: Production
security: []
tags:
  - name: Trading accounts
    description: Create, update, and inspect trading accounts.
  - name: Traders
    description: Look up and update the traders in your organization.
  - name: Trading plans
    description: Define the plans you sell.
  - name: Trading rules
    description: Define how accounts are evaluated.
  - name: Instruments
    description: >-
      The contracts your organization's accounts can trade, with their
      specifications.
  - name: Lockouts
    description: Pause and resume trading on an account.
  - name: Payouts
    description: Check payout eligibility and record payouts.
  - name: Purchases
    description: Purchases recorded for your organization.
  - name: Time Machine
    description: Restore accounts to an earlier trading day or instant.
  - name: Mass credit
    description: >-
      Credit back losses across many accounts after an incident, as background
      jobs you can follow, pause, export and reverse.
  - name: Webhooks
    description: Register webhook endpoints and inspect deliveries.
  - name: Events
    description: Your organization's event history, to replay or audit what happened.
  - name: Real-time streams
    description: >-
      Live events and trading data over a WebSocket, for dashboards and CRMs
      that update as things happen.
  - name: Reconciliation
    description: Balances, end-of-day snapshots, and fills for reconciliation.
  - name: Analytics
    description: Organization performance, revenue and top traders.
  - name: Risk
    description: Firm profit and loss and plan economics.
  - name: Trader insights
    description: >-
      What your traders hold right now and over time, your top traders, and the
      traders you follow.
  - name: Billing and invoices
    description: >-
      Your Hyperprop invoices, credits and billing details, with usage so far
      this month, billing cycles, forecasts and CSV exports.
  - name: Team and roles
    description: Manage dashboard access for your staff.
  - name: API keys
    description: >-
      Manage your organization's API keys: rotation, read-only keys and IP
      allowlists.
  - name: Logs and health
    description: >-
      API request logs, the audit log, integration health, and idempotency key
      recovery.
  - name: Organization profile
    description: Your organization's profile and logo.
  - name: Support
    description: Open and follow up on support tickets.
  - name: Partner access
    description: >-
      Read a trader's journal as an approved partner app, with the trader's own
      key.
paths:
  /v1/organization/risk/positioning:
    get:
      tags:
        - Trader insights
      summary: Get live positioning across all accounts
      description: >-
        Every open position of your organization in one call, each with the
        account's plan, type and trader, plus the contract details needed to
        group and value exposure.


        Use it to build an aggregated book (net long/short per product, by plan
        or account type) and keep it current with the real-time trading stream
        (`POST .../trading-accounts/stream-token`, connect with `v=2`): connect
        first, then read with `fresh=true`, and apply each `PositionUpdate`
        whose `state_version` is not lower than the position's `stateVersion` in
        the same `stateEpoch`. When the stream reports an account this read did
        not include, read it with `accountId`.


        When `source` is `live`, the answer already reflects every change within
        about a second, with or without `fresh`. Otherwise results without
        `fresh` are shared for up to 15 seconds, and newly created accounts
        appear within a minute. About 60 requests per minute per organization.


        ## Example


        ```bash

        curl
        "https://api.hyperprop.com/platform/v1/organization/risk/positioning" \
          -H "X-API-Key: hp_live_your_key_here"
        ```


        **Permissions:** requires **view** access to "Traders & accounts".


        **Access:** read-only and full-access API keys. Dashboard members need
        view access to Traders & accounts.
      operationId: getV1OrganizationRiskPositioning
      parameters:
        - description: >-
            Comma-separated account IDs, at most 200: return these accounts,
            flat ones included, instead of every open position
          name: accountId
          in: query
          required: false
          example: >-
            7c9e6679-7425-40de-944b-e07fc1f90ae7,9d1e6679-7425-40de-944b-e07fc1f90ae8
          schema:
            type: string
            maxLength: 8000
        - description: >-
            `true`: read positions taken no earlier than one second before the
            request, instead of the result shared for a few seconds. Use it
            right after connecting to the trading stream, so no change falls
            between the two.
          name: fresh
          in: query
          example: true
          schema:
            type: boolean
            default: false
        - name: If-None-Match
          in: header
          required: false
          description: >-
            Optional. The `ETag` of the answer you already have. When the answer
            would be the same, the response is `304` without a body.
          example: '"Hq3mB1c0s8n2JkVbQy4Tz9uXw5E"'
          schema:
            type: string
      responses:
        '200':
          description: Open positions with account, plan, trader and contract details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model699'
        '304':
          description: >-
            Not modified: the answer is the same as the one whose `ETag` you
            sent in `If-None-Match`. No body; keep using the answer you have.
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model351'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model15'
        '403':
          description: This API key does not have admin permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model511'
        '429':
          description: >-
            Too many requests for your organization (`RATE_LIMITED`); wait
            `retryAfterSeconds`
        '500':
          description: Internal error (`POSITIONING_ERROR`)
        '504':
          description: >-
            Gateway Timeout - The request did not complete within 25 seconds
            (`REQUEST_TIMEOUT`). Nothing was changed; retry, or narrow the
            request (for example a shorter date range).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model700'
      security:
        - X-API-Key: []
components:
  schemas:
    Model699:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/Model698'
    Model351:
      type: object
      properties:
        success:
          type: boolean
          description: Always false on errors
          example: false
        statusCode:
          type: number
          example: 400
        error:
          type: string
          example: Bad Request
        message:
          type: string
          example: Invalid request data
        code:
          type: string
          description: Machine-readable error code — switch on this, not on message text
          example: BAD_REQUEST
    Model15:
      type: object
      properties:
        success:
          type: boolean
          description: Always false on errors
          example: false
        statusCode:
          type: number
          example: 401
        error:
          type: string
          example: Unauthorized
        message:
          type: string
          example: Authentication required
        code:
          type: string
          description: Machine-readable error code — switch on this, not on message text
          example: UNAUTHORIZED
    Model511:
      type: object
      properties:
        success:
          type: boolean
          description: Always false on errors
          example: false
        statusCode:
          type: number
          example: 403
        error:
          type: string
          example: Forbidden
        message:
          type: string
          example: This API key does not have admin permissions
        code:
          type: string
          description: Machine-readable error code — switch on this, not on message text
          example: INSUFFICIENT_PERMISSIONS
    Model700:
      type: object
      properties:
        statusCode:
          type: number
          example: 504
        error:
          type: string
          example: Gateway Timeout
        message:
          type: string
          example: >-
            The request did not complete within 25 seconds. Try again, or narrow
            it (for example a shorter date range).
        code:
          type: string
          description: Machine-readable error code — switch on this, not on message text
          example: REQUEST_TIMEOUT
    Model698:
      type: object
      properties:
        organizationId:
          type: string
          example: 55555555-5555-4555-8555-555555555555
        asOf:
          type: string
          description: When the read started
          example: '2026-11-03T14:41:07.118Z'
        source:
          $ref: '#/components/schemas/source'
        accounts:
          $ref: '#/components/schemas/Model695'
        unavailable:
          $ref: '#/components/schemas/unavailable'
        instruments:
          $ref: '#/components/schemas/Model696'
        summary:
          $ref: '#/components/schemas/Model697'
    source:
      type: string
      description: >-
        `live`: answered from positions kept current from the trading stream,
        within about a second of every change; `scan`: read from every account
      example: live
      enum:
        - live
        - scan
    Model695:
      type: array
      description: >-
        Accounts with open positions (with `accountId`: every requested account
        of yours, flat ones included)
      items:
        $ref: '#/components/schemas/Model694'
    unavailable:
      type: array
      description: >-
        Accounts whose positions could not be read right now; unknown, never
        flat
      items:
        type: string
    Model696:
      type: object
      description: Each contract in `accounts`, by symbol
    Model697:
      type: object
      properties:
        accountsScanned:
          type: integer
          example: 1840
        accountsWithPositions:
          type: integer
          example: 212
        unavailable:
          type: integer
          example: 0
        truncated:
          type: boolean
          description: >-
            True when the organization has more active accounts than one read
            covers
          example: false
    Model694:
      type: object
      properties:
        accountId:
          type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          x-format:
            guid: true
        accountNumber:
          type: string
          example: ACC-50K-000123
        customerId:
          type: string
          example: crm-cust-4471
        status:
          type: string
          example: in_progress
        accountType:
          type: string
          description: '`evaluation`, `sim_funded` or `competition`'
          example: sim_funded
        initialBalance:
          type: number
          example: 50000
        planId:
          type: string
          example: 7f8d9e0a-1b2c-3d4e-5f60-718293a4b5c6
          x-format:
            guid: true
        planName:
          type: string
          example: 50K Pro
        accountSize:
          type: number
          example: 50000
        traderId:
          type: string
          description: >-
            Groups one trader's accounts: your trader record when the account
            has one, otherwise the trader's login
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        traderName:
          type: string
          example: Jane Trader
        traderEmail:
          type: string
          example: jane@example.com
        stateEpoch:
          type: integer
          example: 1761847200123
        stateVersion:
          type: integer
          example: 57
        positions:
          $ref: '#/components/schemas/positions'
    positions:
      type: array
      items:
        $ref: '#/components/schemas/Model693'
    Model693:
      type: object
      properties:
        positionId:
          type: string
          description: >-
            Stable ID of this position from open to flat; `position.position_id`
            on the trading stream with `v=2`
          example: 3f6c1d2e-8a4b-5c7d-9e0f-1a2b3c4d5e6f
          x-format:
            guid: true
        contract:
          type: string
          description: Contract symbol, as on the trading stream
          example: MNQZ6
        side:
          $ref: '#/components/schemas/side'
        quantity:
          type: number
          description: >-
            Open size in units of order quantity, always positive (`side` gives
            the direction). Multiply by the instrument's `contractSize` for the
            size in `sizeUnit`
          example: 2
        avgEntryPrice:
          type: number
          example: 21012.25
        unrealizedPnl:
          type: number
          description: Open profit or loss at the position's last price update
          example: 41
        realizedPnl:
          type: number
          description: >-
            Gross profit or loss already taken by partial closes of this
            position
          example: 0
        openedAt:
          type: string
          example: '2026-11-03T14:30:00.000Z'
        updatedAt:
          type: string
          example: '2026-11-03T14:35:12.000Z'
        stateVersion:
          type: integer
          description: >-
            Book version at this position's last change; compare with
            `state_version` on the stream
          example: 57
        stateEpoch:
          type: integer
          description: Book epoch; `state_epoch` on the stream with `v=2`
          example: 1761847200123
    side:
      type: string
      example: long
      enum:
        - long
        - short
  securitySchemes:
    X-API-Key:
      type: apiKey
      name: X-API-Key
      in: header
      description: >-
        Organization API key (`hp_live_...`), sent in the `X-API-Key` header.
        Create, rotate and restrict keys in the dashboard or with the API keys
        endpoints; an organization can have two active keys, so you can rotate
        without downtime. A **full-access** key can call every endpoint in this
        reference. A **read-only** key can call `GET` endpoints (and create a
        trading stream token); any other request returns `403 READ_ONLY_KEY`. A
        key with an IP allowlist returns `403 IP_NOT_ALLOWED` from any other
        address. Each endpoint lists which keys can call it under **Access**.

````

## Related topics

- [Close all positions across accounts](https://docs.hyperprop.com/platform-api/trading-accounts/close-all-positions-across-accounts.md)
- [Get an account's order history](https://docs.hyperprop.com/platform-api/trading-accounts/get-an-accounts-order-history.md)
- [Get organization analytics](https://docs.hyperprop.com/platform-api/analytics/get-organization-analytics.md)
- [Get a close-all run](https://docs.hyperprop.com/platform-api/trading-accounts/get-a-close-all-run.md)
- [Get long vs short positioning over time](https://docs.hyperprop.com/platform-api/trader-insights/get-long-vs-short-positioning-over-time.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.