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

# List the entries and exits of the traders you follow

> The latest fills of the traders your organization follows, newest first, on every one of their accounts at your organization. Each fill says whether it opened, added to, reduced, closed or reversed the account's position in the contract, with the size, price and, for exits, the profit or loss it realized.

- The list comes from trading history, so it is the same whenever you read it. To stay current, read it once and then apply the fills the trading stream sends for `streamAccountIds` (see the watchlist read).
- Positions are worked out from fills starting 7 days before the range; a fill reducing a position opened before that reads as an entry.
- Page with `nextCursor`: pass it as `before` until `hasMore` is false.
- With `assetClass` or `market`, only positions and executions in contracts of those markets count.

Pages are shared for a few seconds. About 120 requests per minute per organization.

## Example

```bash
curl "https://api.hyperprop.com/platform/v1/organization/insights/watchlist/activity?range=24h&limit=50" \
  -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/watchlist/activity
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/watchlist/activity:
    get:
      tags:
        - Trader insights
      summary: List the entries and exits of the traders you follow
      description: >-
        The latest fills of the traders your organization follows, newest first,
        on every one of their accounts at your organization. Each fill says
        whether it opened, added to, reduced, closed or reversed the account's
        position in the contract, with the size, price and, for exits, the
        profit or loss it realized.


        - The list comes from trading history, so it is the same whenever you
        read it. To stay current, read it once and then apply the fills the
        trading stream sends for `streamAccountIds` (see the watchlist read).

        - Positions are worked out from fills starting 7 days before the range;
        a fill reducing a position opened before that reads as an entry.

        - Page with `nextCursor`: pass it as `before` until `hasMore` is false.

        - With `assetClass` or `market`, only positions and executions in
        contracts of those markets count.


        Pages are shared for a few seconds. About 120 requests per minute per
        organization.


        ## Example


        ```bash

        curl
        "https://api.hyperprop.com/platform/v1/organization/insights/watchlist/activity?range=24h&limit=50"
        \
          -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: getV1OrganizationInsightsWatchlistActivity
      parameters:
        - description: '`24h` or `7d` back from now'
          name: range
          in: query
          example: 24h
          schema:
            type: string
            enum:
              - 24h
              - 7d
            default: 7d
        - description: Fills per page, at most 200
          name: limit
          in: query
          example: 50
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - description: '`nextCursor` of the previous page'
          name: before
          in: query
          required: false
          example: MjAyNi0xMS0wM1QxNTo1ODoxMi4wMDBafDNmNmMyYTFl
          schema:
            type: string
            maxLength: 200
        - 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: Entries and exits, newest first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model997'
        '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; or a
            cursor this endpoint did not issue (`INVALID_CURSOR`)
          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 (`ACTIVITY_ERROR`)
        '503':
          description: >-
            Not available yet (`ACTIVITY_UNAVAILABLE`). The report took too long
            right now (`REPORT_TIMEOUT`). Wait the seconds in the `Retry-After`
            header (also `retryAfterSeconds` in the body) before asking again;
            the wait grows while the report keeps running out of time.
        '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/Model998'
      security:
        - X-API-Key: []
components:
  schemas:
    Model997:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/Model996'
    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
    Model998:
      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
    Model996:
      type: object
      properties:
        organizationId:
          type: string
          example: 55555555-5555-4555-8555-555555555555
        range:
          $ref: '#/components/schemas/Model988'
        since:
          type: string
          description: Start of the range
          example: '2026-10-27T16:41:07.118Z'
        asOf:
          type: string
          example: '2026-11-03T16:41:07.118Z'
        marketFilter:
          $ref: '#/components/schemas/marketFilter'
        traders:
          type: integer
          description: Traders you follow
          example: 5
        items:
          $ref: '#/components/schemas/Model995'
        hasMore:
          type: boolean
          example: true
        nextCursor:
          type: string
          description: Pass as `before` for the next page; null on the last page
          example: MjAyNi0xMS0wM1QxNTo1ODoxMi4wMDBafDNmNmMyYTFl
    Model988:
      type: string
      example: 7d
      enum:
        - 24h
        - 7d
    marketFilter:
      type: object
      description: The market filter applied
      properties:
        assetClass:
          $ref: '#/components/schemas/Model501'
        markets:
          $ref: '#/components/schemas/Model502'
    Model995:
      type: array
      description: Newest first
      items:
        $ref: '#/components/schemas/Model994'
    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
    Model994:
      type: object
      properties:
        id:
          type: string
          description: The fill
          example: 3f6c2a1e-9b8d-4c7e-a5f4-1d2c3b4a5e6f
        time:
          type: string
          description: When it filled
          example: '2026-11-03T15:58:12.000Z'
        type:
          $ref: '#/components/schemas/Model989'
        action:
          $ref: '#/components/schemas/Model990'
        side:
          $ref: '#/components/schemas/Model991'
        size:
          type: number
          description: Executed size in `sizeUnit`
          example: 2
        sizeUnit:
          type: string
          description: '`contracts` for futures, the base asset for perpetuals (`BTC`)'
          example: contracts
        positionBefore:
          type: number
          description: >-
            The account's position in the contract before the fill, in
            `sizeUnit`; negative = short
          example: 2
        positionAfter:
          type: number
          description: The position after the fill
          example: 0
        price:
          type: number
          example: 21034.25
        realizedPnl:
          type: number
          description: >-
            Exits: profit or loss the fill realized, before fees. Null for
            entries
          example: 412.5
        copied:
          type: boolean
          description: A fill made by copy trading
          example: false
        initiatedBy:
          $ref: '#/components/schemas/initiatedBy'
        trader:
          $ref: '#/components/schemas/Model992'
        account:
          $ref: '#/components/schemas/Model993'
        instrument:
          $ref: '#/components/schemas/instrument'
    Model989:
      type: string
      description: >-
        `entry` opens or adds to a position; `exit` reduces, closes or reverses
        one
      example: exit
      enum:
        - entry
        - exit
    Model990:
      type: string
      description: >-
        `open`, `add`, `reduce`, `close` or `reverse` (closes the position and
        opens one on the other side)
      example: close
      enum:
        - open
        - add
        - reduce
        - close
        - reverse
    Model991:
      type: string
      description: 'Entries: the side opened or added to. Exits: the side reduced or closed'
      example: long
      enum:
        - long
        - short
    initiatedBy:
      type: string
      description: >-
        Who started the order: the trader, an automatic rule (stop, liquidation,
        risk setting), your staff, or copy trading; null when unknown
      example: trader
      enum:
        - trader
        - automatic
        - admin
        - copy_trading
    Model992:
      type: object
      properties:
        traderId:
          type: string
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        name:
          type: string
          example: Jane Trader
        email:
          type: string
          example: jane@example.com
    Model993:
      type: object
      properties:
        accountId:
          type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
        accountNumber:
          type: string
          example: ACC-50K-000123
        accountType:
          type: string
          example: sim_funded
        planName:
          type: string
          example: 50K Pro
    instrument:
      type: object
      properties:
        contract:
          type: string
          example: MNQZ6
        rootSymbol:
          type: string
          example: MNQ
        productKey:
          type: string
          description: Futures root (`MNQ`) or the perpetual's base asset (`BTC-PERP`)
          example: MNQ
        name:
          type: string
          example: Micro E-mini Nasdaq-100
        productGroup:
          type: string
          description: Sector
          example: equity_index
        market:
          type: string
          example: CME
        assetClass:
          $ref: '#/components/schemas/assetClass'
    assetClass:
      type: string
      example: future
      enum:
        - future
        - perpetual
  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

- [List the traders you follow](https://docs.hyperprop.com/platform-api/trader-insights/list-the-traders-you-follow.md)
- [Follow a trader](https://docs.hyperprop.com/platform-api/trader-insights/follow-a-trader.md)
- [Stop following a trader](https://docs.hyperprop.com/platform-api/trader-insights/stop-following-a-trader.md)
- [List your top traders by realized performance](https://docs.hyperprop.com/platform-api/trader-insights/list-your-top-traders-by-realized-performance.md)
- [List the trader's API keys](https://docs.hyperprop.com/trade-api/account/list-the-traders-api-keys.md)


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