> ## 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.

# Read trader sentiment over time

> How your traders are positioned over time: how many are long and short, their long and short exposure and open P&L, and the entries they make in each time bucket, for the whole firm and per product. Each is also given for a smart-money group, your best traders by realized P&L over the last 30 days (at least 5 trades and a profit), so you can compare them with everyone else.

- A trader is long a product when their accounts' positions in it add up to more than zero, short when less. Firm-wide, a trader long one product and short another counts on both sides.
- Exposure and open P&L use your traders' last fill price in each contract, so they move when your traders trade.
- An entry is a fill that opens or adds to a position; a reversal counts as an entry on the new side.
- Positions are rebuilt from fills starting `carryDays` before `since`; a position held since before that is not seen. Read the positioning endpoint for the live book.
- With `assetClass` or `market`, only positions and executions in contracts of those markets count. The smart-money group is then your best traders in those markets.
- When the smart-money group can't be ranked in time, the response still comes back with every other series; `smartMoney.available` is `false` and the smart-money series are zero until it can be ranked again.

Results are shared for up to a minute (5 minutes for `7d`) per range and filter. About 60 requests per minute per organization.

## Example

```bash
curl "https://api.hyperprop.com/platform/v1/organization/insights/sentiment?range=24h&smartMoney=20" \
  -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/insights/sentiment
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/insights/sentiment:
    get:
      tags:
        - Trader insights
      summary: Read trader sentiment over time
      description: >-
        How your traders are positioned over time: how many are long and short,
        their long and short exposure and open P&L, and the entries they make in
        each time bucket, for the whole firm and per product. Each is also given
        for a smart-money group, your best traders by realized P&L over the last
        30 days (at least 5 trades and a profit), so you can compare them with
        everyone else.


        - A trader is long a product when their accounts' positions in it add up
        to more than zero, short when less. Firm-wide, a trader long one product
        and short another counts on both sides.

        - Exposure and open P&L use your traders' last fill price in each
        contract, so they move when your traders trade.

        - An entry is a fill that opens or adds to a position; a reversal counts
        as an entry on the new side.

        - Positions are rebuilt from fills starting `carryDays` before `since`;
        a position held since before that is not seen. Read the positioning
        endpoint for the live book.

        - With `assetClass` or `market`, only positions and executions in
        contracts of those markets count. The smart-money group is then your
        best traders in those markets.

        - When the smart-money group can't be ranked in time, the response still
        comes back with every other series; `smartMoney.available` is `false`
        and the smart-money series are zero until it can be ranked again.


        Results are shared for up to a minute (5 minutes for `7d`) per range and
        filter. About 60 requests per minute per organization.


        ## Example


        ```bash

        curl
        "https://api.hyperprop.com/platform/v1/organization/insights/sentiment?range=24h&smartMoney=20"
        \
          -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: getV1OrganizationInsightsSentiment
      parameters:
        - description: >-
            `1h` (1-minute buckets), `today` (since 17:00 Chicago time, 5-minute
            buckets), `24h` (5-minute buckets) or `7d` (hourly buckets)
          name: range
          in: query
          example: 24h
          schema:
            type: string
            enum:
              - 1h
              - today
              - 24h
              - 7d
            default: 24h
        - description: >-
            Comma-separated account types: `evaluation`, `sim_funded`,
            `competition`
          name: accountType
          in: query
          required: false
          example: sim_funded
          schema:
            type: string
            maxLength: 100
        - description: >-
            Comma-separated plan IDs, at most 50; `none` for accounts without a
            plan
          name: planId
          in: query
          required: false
          example: 7f8d9e0a-1b2c-3d4e-5f60-718293a4b5c6
          schema:
            type: string
            maxLength: 2000
        - description: >-
            Comma-separated product keys, at most 5, to include in `products`
            besides the largest ones
          name: product
          in: query
          required: false
          example: BTC-PERP
          schema:
            type: string
            maxLength: 200
        - description: >-
            Size of the smart-money group: your best traders by realized P&L
            over the last 30 days
          name: smartMoney
          in: query
          example: 20
          schema:
            type: integer
            enum:
              - 10
              - 20
              - 50
            default: 20
        - description: >-
            Only one kind of market: `future` (CME Group futures) or `perpetual`
            (perpetuals). Omit for both
          name: assetClass
          in: query
          required: false
          example: perpetual
          schema:
            type: string
            enum:
              - future
              - perpetual
        - description: >-
            Comma-separated markets your organization is enabled for: futures
            `CME`, `CBOT`, `NYMEX`, `COMEX`; perpetuals `HDL`, `BINANCE`,
            `HYPERLIQUID`. With `assetClass`, every market must be of that class
          name: market
          in: query
          required: false
          example: CME,CBOT
          schema:
            type: string
            maxLength: 84
        - 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: Sentiment series
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model509'
        '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 parameters: `INVALID_MARKET`, `MARKET_NOT_ALLOWED` (not
            enabled for your organization), `MARKET_ASSET_CLASS_MISMATCH` (a
            market of another `assetClass`), or another validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model510'
        '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`. Also returned while your organization already
            has 6 reports being computed at once; wait the `Retry-After`
            seconds.
        '500':
          description: Internal error (`SENTIMENT_ERROR`)
        '503':
          description: >-
            Not available yet (`SENTIMENT_UNAVAILABLE`), or the report took too
            long (`REPORT_TIMEOUT`, with `Retry-After`): choose a shorter range
            or fewer plans
        '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/Model512'
      security:
        - X-API-Key: []
components:
  schemas:
    Model509:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/Model508'
    Model510:
      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: >-
            Unknown market: CMX. Use CME, CBOT, NYMEX, COMEX, HDL, BINANCE,
            HYPERLIQUID
        code:
          type: string
          description: Machine-readable error code — switch on this, not on message text
          example: INVALID_MARKET
    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
    Model512:
      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
    Model508:
      type: object
      properties:
        organizationId:
          type: string
          example: 55555555-5555-4555-8555-555555555555
        range:
          $ref: '#/components/schemas/range'
        bucketSeconds:
          type: integer
          example: 300
        since:
          type: string
          example: '2026-11-02T16:45:00.000Z'
        until:
          type: string
          example: '2026-11-03T16:45:00.000Z'
        asOf:
          type: string
          example: '2026-11-03T16:41:07.118Z'
        carryDays:
          type: integer
          description: >-
            Positions are rebuilt from fills starting this many days before
            `since`
          example: 2
        marketFilter:
          $ref: '#/components/schemas/marketFilter'
        times:
          $ref: '#/components/schemas/times'
        smartMoney:
          $ref: '#/components/schemas/smartMoney'
        firm:
          $ref: '#/components/schemas/firm'
        products:
          $ref: '#/components/schemas/Model504'
        productIndex:
          $ref: '#/components/schemas/productIndex'
        fills:
          type: integer
          description: Fills replayed
          example: 18204
        live:
          $ref: '#/components/schemas/live'
    range:
      type: string
      example: 24h
      enum:
        - 1h
        - today
        - 24h
        - 7d
    marketFilter:
      type: object
      description: The market filter applied
      properties:
        assetClass:
          $ref: '#/components/schemas/Model501'
        markets:
          $ref: '#/components/schemas/Model502'
    times:
      type: array
      description: >-
        End of each bucket; the last one is `asOf`. Every series has one value
        per entry
      example:
        - '2026-11-03T16:35:00.000Z'
        - '2026-11-03T16:40:00.000Z'
        - '2026-11-03T16:41:07.118Z'
      items:
        type: string
    smartMoney:
      type: object
      properties:
        size:
          type: integer
          example: 20
          enum:
            - 10
            - 20
            - 50
        periodDays:
          type: integer
          example: 30
        minTrades:
          type: integer
          example: 5
        traderIds:
          $ref: '#/components/schemas/traderIds'
        available:
          type: boolean
          description: >-
            False when the group could not be ranked in time: `traderIds` is
            empty and every smart-money series is zero. The rest of the response
            is complete; try again in a few minutes
          example: true
    firm:
      type: object
      description: All products together
      properties:
        tradersLong:
          $ref: '#/components/schemas/tradersLong'
        tradersShort:
          $ref: '#/components/schemas/tradersShort'
        tradersInPosition:
          $ref: '#/components/schemas/tradersInPosition'
        smartTradersLong:
          $ref: '#/components/schemas/smartTradersLong'
        smartTradersShort:
          $ref: '#/components/schemas/smartTradersShort'
        smartTradersInPosition:
          $ref: '#/components/schemas/smartTradersInPosition'
        longNotional:
          $ref: '#/components/schemas/longNotional'
        shortNotional:
          $ref: '#/components/schemas/shortNotional'
        smartLongNotional:
          $ref: '#/components/schemas/smartLongNotional'
        smartShortNotional:
          $ref: '#/components/schemas/smartShortNotional'
        longOpenPnl:
          $ref: '#/components/schemas/longOpenPnl'
        shortOpenPnl:
          $ref: '#/components/schemas/shortOpenPnl'
        longEntries:
          $ref: '#/components/schemas/longEntries'
        shortEntries:
          $ref: '#/components/schemas/shortEntries'
        longEntryNotional:
          $ref: '#/components/schemas/longEntryNotional'
        shortEntryNotional:
          $ref: '#/components/schemas/shortEntryNotional'
        smartLongEntryNotional:
          $ref: '#/components/schemas/smartLongEntryNotional'
        smartShortEntryNotional:
          $ref: '#/components/schemas/smartShortEntryNotional'
    Model504:
      type: array
      description: >-
        The 16 products with the largest exposure in the range, plus the ones
        you asked for, in `productIndex` order
      items:
        $ref: '#/components/schemas/Model503'
    productIndex:
      type: array
      description: Every product traded or held in the range, largest exposure first
      items:
        $ref: '#/components/schemas/Model505'
    live:
      type: object
      description: >-
        The levels right now, under the same filters, so a chart can end at the
        present (entries stay in the series). Null while not available
      properties:
        at:
          type: string
          description: When these figures were taken
          example: '2026-11-13T15:41:07.118Z'
        historyAsOf:
          type: string
          description: '`asOf` of the series they follow'
          example: '2026-11-13T15:40:02.000Z'
        historyCompleteUntil:
          type: string
          description: >-
            Every fill before this is in the series; buckets after it may still
            change. Null when unknown
          example: '2026-11-13T15:39:00.000Z'
        firm:
          $ref: '#/components/schemas/Model506'
        products:
          $ref: '#/components/schemas/Model507'
    Model501:
      type: string
      description: Null when not filtered by class
      example: future
      enum:
        - future
        - perpetual
    Model502:
      type: array
      description: Empty when not filtered by market
      example:
        - CME
        - CBOT
      items:
        type: string
    traderIds:
      type: array
      description: >-
        The traders in the group, best first; fewer than `size` when not enough
        traders qualify with a profit
      example:
        - 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
      items:
        type: string
    tradersLong:
      type: array
      description: Traders with a net long position
      example:
        - 41
        - 44
        - 47
      items:
        type: integer
    tradersShort:
      type: array
      description: Traders with a net short position
      example:
        - 30
        - 29
        - 25
      items:
        type: integer
    tradersInPosition:
      type: array
      description: >-
        Traders with any position (firm-wide, a trader long one product and
        short another counts once)
      example:
        - 68
        - 70
        - 69
      items:
        type: integer
    smartTradersLong:
      type: array
      description: >-
        Smart-money traders with a net long position; the crowd is all traders
        minus these
      example:
        - 9
        - 10
        - 11
      items:
        type: integer
    smartTradersShort:
      type: array
      description: Smart-money traders with a net short position
      example:
        - 4
        - 3
        - 3
      items:
        type: integer
    smartTradersInPosition:
      type: array
      description: Smart-money traders with any position
      example:
        - 13
        - 13
        - 14
      items:
        type: integer
    longNotional:
      type: array
      description: 'Gross long exposure: size × last fill price × point value'
      example:
        - 2410000
        - 2560400
        - 2731900
      items:
        type: number
    shortNotional:
      type: array
      description: Gross short exposure, as a positive amount
      example:
        - 1870250
        - 1802300
        - 1655000
      items:
        type: number
    smartLongNotional:
      type: array
      description: Smart-money gross long exposure
      example:
        - 610000
        - 655200
        - 702100
      items:
        type: number
    smartShortNotional:
      type: array
      description: Smart-money gross short exposure
      example:
        - 212000
        - 180400
        - 176250
      items:
        type: number
    longOpenPnl:
      type: array
      description: Open profit or loss of the long positions at the last fill price
      example:
        - 12400.5
        - 15120
        - 18002.25
      items:
        type: number
    shortOpenPnl:
      type: array
      description: Open profit or loss of the short positions
      example:
        - -8210
        - -9950.5
        - -12300
      items:
        type: number
    longEntries:
      type: array
      description: Fills that opened or added to a long position in the bucket
      example:
        - 12
        - 18
        - 9
      items:
        type: integer
    shortEntries:
      type: array
      description: Fills that opened or added to a short position in the bucket
      example:
        - 7
        - 5
        - 11
      items:
        type: integer
    longEntryNotional:
      type: array
      description: Value of the long entries in the bucket, at their fill prices
      example:
        - 182000
        - 301400
        - 120500
      items:
        type: number
    shortEntryNotional:
      type: array
      description: Value of the short entries in the bucket
      example:
        - 96000
        - 61200
        - 188400
      items:
        type: number
    smartLongEntryNotional:
      type: array
      description: Value of the smart-money long entries in the bucket
      example:
        - 41000
        - 88000
        - 0
      items:
        type: number
    smartShortEntryNotional:
      type: array
      description: Value of the smart-money short entries in the bucket
      example:
        - 0
        - 0
        - 22100
      items:
        type: number
    Model503:
      type: object
      properties:
        productKey:
          type: string
          description: Futures root (`MNQ`) or the perpetual's base asset (`BTC-PERP`)
          example: MNQ
        rootSymbol:
          type: string
          example: MNQ
        name:
          type: string
          example: Micro E-mini Nasdaq-100
        productGroup:
          type: string
          example: equity_index
        assetClass:
          type: string
          example: future
        sizeUnit:
          type: string
          example: contracts
        longQuantity:
          $ref: '#/components/schemas/longQuantity'
        shortQuantity:
          $ref: '#/components/schemas/shortQuantity'
        price:
          $ref: '#/components/schemas/price'
        tradersLong:
          $ref: '#/components/schemas/tradersLong'
        tradersShort:
          $ref: '#/components/schemas/tradersShort'
        tradersInPosition:
          $ref: '#/components/schemas/tradersInPosition'
        smartTradersLong:
          $ref: '#/components/schemas/smartTradersLong'
        smartTradersShort:
          $ref: '#/components/schemas/smartTradersShort'
        smartTradersInPosition:
          $ref: '#/components/schemas/smartTradersInPosition'
        longNotional:
          $ref: '#/components/schemas/longNotional'
        shortNotional:
          $ref: '#/components/schemas/shortNotional'
        smartLongNotional:
          $ref: '#/components/schemas/smartLongNotional'
        smartShortNotional:
          $ref: '#/components/schemas/smartShortNotional'
        longOpenPnl:
          $ref: '#/components/schemas/longOpenPnl'
        shortOpenPnl:
          $ref: '#/components/schemas/shortOpenPnl'
        longEntries:
          $ref: '#/components/schemas/longEntries'
        shortEntries:
          $ref: '#/components/schemas/shortEntries'
        longEntryNotional:
          $ref: '#/components/schemas/longEntryNotional'
        shortEntryNotional:
          $ref: '#/components/schemas/shortEntryNotional'
        smartLongEntryNotional:
          $ref: '#/components/schemas/smartLongEntryNotional'
        smartShortEntryNotional:
          $ref: '#/components/schemas/smartShortEntryNotional'
    Model505:
      type: object
      properties:
        productKey:
          type: string
          example: MNQ
        rootSymbol:
          type: string
          example: MNQ
        name:
          type: string
          example: Micro E-mini Nasdaq-100
        productGroup:
          type: string
          example: equity_index
        assetClass:
          type: string
          example: future
        peakGrossNotional:
          type: number
          description: Largest long + short exposure in the range
          example: 3120000
        entries:
          type: integer
          description: Entries in the range
          example: 412
        entryNotional:
          type: number
          example: 6210500
    Model506:
      type: object
      description: >-
        The firm series' levels now: traders long, short and in position (and
        smart money), long and short exposure, open P&L
    Model507:
      type: array
      description: >-
        The same per product in `products`, with `longQuantity`, `shortQuantity`
        and `price`
      items:
        $ref: '#/components/schemas/changes'
    longQuantity:
      type: array
      description: Gross long size in `sizeUnit`
      example:
        - 140
        - 152
        - 160
      items:
        type: number
    shortQuantity:
      type: array
      description: Gross short size in `sizeUnit`
      example:
        - 96
        - 90
        - 84
      items:
        type: number
    price:
      type: array
      description: >-
        Perpetuals only: your traders' last fill price at the end of each
        bucket. Null for futures
      example: null
      items:
        type: number
    changes:
      type: object
  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

- [Get top traders over time](https://docs.hyperprop.com/platform-api/analytics/get-top-traders-over-time.md)
- [Get long vs short positioning over time](https://docs.hyperprop.com/platform-api/trader-insights/get-long-vs-short-positioning-over-time.md)
- [Real-time trading stream](https://docs.hyperprop.com/guides/realtime-trading-stream.md)
- [Rate limits & quotas](https://docs.hyperprop.com/concepts/rate-limits.md)
- [Get active traders](https://docs.hyperprop.com/platform-api/trading-accounts/get-active-traders.md)


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