> ## 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 flagged traders

> Every trader flagged by the daily risk reports in the last `days` trading days, with what flagged them and your review state, most recently flagged first. A trader is flagged by a hedge pair, a copy group, a copy pair seen on two or more days, a shared device or an address with overlapping sessions or trading, or an order that opened a position inside a news window. Set the review state with `PUT /risk/inbox/{traderId}`; a trader flagged again on a later trading day shows as `new` again.

`summary` counts all flagged traders by state. `reviewStateAvailable` is false while review states cannot be saved yet; every trader is then `new`.

Each trader's `stake` says what is at stake in money: the profit their funded accounts could still pay out, how many funded accounts they hold, and what was paid out to them after the flag was shown and before a review. Amounts are in the account currency, before your profit split. When it cannot be read in time, `stake` is null and `stakeAvailable` false; the list is still complete. It may be up to a minute old.

```bash
curl "https://api.hyperprop.com/platform/v1/organization/risk/inbox?days=7&state=new&sort=stake" \
  -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/inbox
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/inbox:
    get:
      tags:
        - Risk
      summary: List flagged traders
      description: >-
        Every trader flagged by the daily risk reports in the last `days`
        trading days, with what flagged them and your review state, most
        recently flagged first. A trader is flagged by a hedge pair, a copy
        group, a copy pair seen on two or more days, a shared device or an
        address with overlapping sessions or trading, or an order that opened a
        position inside a news window. Set the review state with `PUT
        /risk/inbox/{traderId}`; a trader flagged again on a later trading day
        shows as `new` again.


        `summary` counts all flagged traders by state. `reviewStateAvailable` is
        false while review states cannot be saved yet; every trader is then
        `new`.


        Each trader's `stake` says what is at stake in money: the profit their
        funded accounts could still pay out, how many funded accounts they hold,
        and what was paid out to them after the flag was shown and before a
        review. Amounts are in the account currency, before your profit split.
        When it cannot be read in time, `stake` is null and `stakeAvailable`
        false; the list is still complete. It may be up to a minute old.


        ```bash

        curl
        "https://api.hyperprop.com/platform/v1/organization/risk/inbox?days=7&state=new&sort=stake"
        \
          -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: getV1OrganizationRiskInbox
      parameters:
        - description: Trading days of reports to include, 1 to 30
          name: days
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 30
            default: 7
        - description: Review state to list
          name: state
          in: query
          schema:
            type: string
            enum:
              - all
              - new
              - reviewed
              - cleared
            default: new
        - description: Most traders to return
          name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - description: >-
            Lowest finding level to include; findings stored before levels
            existed are always included
          name: minLevel
          in: query
          example: medium
          schema:
            type: string
            enum:
              - low
              - medium
              - high
            default: low
        - description: >-
            `recent`: most recently flagged first. `stake`: highest level first,
            then the most profit that could still be paid out
          name: sort
          in: query
          schema:
            type: string
            enum:
              - recent
              - stake
            default: recent
        - 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: Flagged traders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model644'
        '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: this endpoint allows 60 calls per minute per
            organization. Wait the number of seconds in the `Retry-After`
            header.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Always false on errors
                    example: false
                  statusCode:
                    type: integer
                    example: 429
                  error:
                    type: string
                    example: Too Many Requests
                  message:
                    type: string
                    example: >-
                      Too many requests to this endpoint. Try again in 12
                      second(s).
                  code:
                    type: string
                    enum:
                      - RATE_LIMITED
                    example: RATE_LIMITED
                    description: >-
                      Machine-readable error code — switch on this, not on
                      message text
        '500':
          description: Internal error (`RISK_INBOX_ERROR`)
        '503':
          description: Not available yet (`RISK_REPORTS_UNAVAILABLE`)
        '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/Model645'
      security:
        - X-API-Key: []
components:
  schemas:
    Model644:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/Model643'
    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
    Model645:
      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
    Model643:
      type: object
      properties:
        organizationId:
          type: string
          x-format:
            guid: true
        from:
          type: string
          example: '2026-11-06'
        to:
          type: string
          example: '2026-11-12'
        reviewStateAvailable:
          type: boolean
          example: true
        summary:
          $ref: '#/components/schemas/Model634'
        coverage:
          $ref: '#/components/schemas/coverage'
        stakeAvailable:
          type: boolean
          description: >-
            False when the money at stake could not be read in time; every
            `stake` is then null
          example: true
        traders:
          $ref: '#/components/schemas/Model642'
    Model634:
      type: object
      properties:
        new:
          type: integer
          example: 4
        reviewed:
          type: integer
          example: 2
        cleared:
          type: integer
          example: 9
    coverage:
      type: object
      description: >-
        Which trading days the list covers; show "no findings" only when
        `complete` is true
      properties:
        from:
          type: string
          example: '2026-11-06'
        to:
          type: string
          example: '2026-11-12'
        complete:
          type: boolean
          description: >-
            True only when every closed trading day in the range has all its
            reports
          example: false
        days:
          $ref: '#/components/schemas/days'
        failedDays:
          type: integer
          example: 1
        pendingDays:
          type: integer
          example: 0
        truncatedDays:
          type: integer
          example: 0
        missingDays:
          type: integer
          example: 0
    Model642:
      type: array
      items:
        $ref: '#/components/schemas/Model641'
    days:
      type: array
      description: >-
        Closed trading days, newest first. The open day is not listed, nor
        Saturday and Sunday (no session) unless something was stored for them.
        There is no holiday calendar: holidays are computed like any weekday
      items:
        $ref: '#/components/schemas/Model624'
    Model641:
      type: object
      properties:
        traderId:
          type: string
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        userId:
          type: string
          x-format:
            guid: true
        traderName:
          type: string
        traderEmail:
          type: string
        accounts:
          $ref: '#/components/schemas/Model636'
        counts:
          $ref: '#/components/schemas/counts'
        totalFlags:
          type: integer
          example: 4
        firstDay:
          type: string
          example: '2026-11-10'
        lastDay:
          type: string
          example: '2026-11-12'
        items:
          $ref: '#/components/schemas/Model637'
        level:
          $ref: '#/components/schemas/Model638'
        levels:
          $ref: '#/components/schemas/levels'
        review:
          $ref: '#/components/schemas/Model640'
        stake:
          $ref: '#/components/schemas/stake'
    Model624:
      type: object
      properties:
        tradingDay:
          type: string
          example: '2026-11-11'
        state:
          $ref: '#/components/schemas/Model623'
        expectedAt:
          type: string
          description: >-
            Pending days only: when the nightly run is due (Sunday's day: Monday
            17:10 Chicago)
          example: '2026-11-16T23:10:00.000Z'
          x-format:
            isoDate: true
        reports:
          $ref: '#/components/schemas/reports'
        truncated:
          $ref: '#/components/schemas/truncated'
    Model636:
      type: array
      items:
        $ref: '#/components/schemas/Model635'
    counts:
      type: object
      description: Flagging findings per report
      properties:
        hedge_pairs:
          type: integer
          example: 2
        copy_pairs:
          type: integer
          example: 0
        copy_groups:
          type: integer
          example: 1
        shared_devices:
          type: integer
          example: 1
        news_window_fills:
          type: integer
          example: 0
        self_hedges:
          type: integer
          example: 1
    Model637:
      type: array
      description: Most recent flags, at most 20
      items:
        $ref: '#/components/schemas/Model625'
    Model638:
      type: string
      description: Highest level among the trader's findings
      example: high
      enum:
        - low
        - medium
        - high
    levels:
      type: object
      properties:
        low:
          type: integer
        medium:
          type: integer
        high:
          type: integer
    Model640:
      type: object
      properties:
        state:
          $ref: '#/components/schemas/Model639'
        savedState:
          $ref: '#/components/schemas/savedState'
        outcome:
          $ref: '#/components/schemas/outcome'
        reason:
          type: string
          example: same_household
        note:
          type: string
        updatedAt:
          type: string
          x-format:
            isoDate: true
    stake:
      type: object
      description: Money at stake with the trader; null when it could not be read in time
      properties:
        payableProfit:
          type: number
          description: >-
            Profit above the starting balance on the trader's funded accounts
            that are not closed: the most they could still ask to be paid,
            before your profit split and payout rules
          example: 12400.5
        fundedAccounts:
          type: integer
          description: >-
            Funded accounts the trader holds that are not failed, passed or
            expired
          example: 2
        paidBeforeReview:
          type: number
          description: >-
            Payouts (not reversed) made to the trader's funded accounts after
            the flag was first shown and before anyone recorded a review
          example: 850
        payoutPending:
          type: string
          description: 'Always null: payout requests are kept in your own system'
    Model623:
      type: string
      description: >-
        `pending`: the nightly run for the day is not due yet or ran less than
        12 hours ago; `missing`: still nothing 12 hours after it was due
      example: failed
      enum:
        - ready
        - partial
        - failed
        - truncated
        - pending
        - missing
    reports:
      type: object
      description: Per report, when not all are ready
    truncated:
      type: array
      description: Reports cut at their row limit
      items:
        type: string
    Model635:
      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
          description: Your customer id for the account (`customerId` at account creation)
          example: cust-4471
        accountType:
          type: string
          example: sim_funded
        status:
          type: string
          example: in_progress
        planId:
          type: string
          x-format:
            guid: true
        traderId:
          type: string
          description: >-
            Your trader record when the account has one, otherwise the trader's
            login
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        userId:
          type: string
          description: The trader's Hyperprop login
          x-format:
            guid: true
        traderName:
          type: string
          example: Jane Trader
        traderEmail:
          type: string
          example: jane@example.com
    Model625:
      type: object
      properties:
        report:
          $ref: '#/components/schemas/report'
        tradingDay:
          type: string
          example: '2026-11-12'
        rowId:
          type: string
          description: The finding's `id` in that day's report
          x-format:
            guid: true
        summary:
          type: string
          example: Opposite NQ positions with another trader for 412 s
        level:
          $ref: '#/components/schemas/level'
    Model639:
      type: string
      description: >-
        `new` until reviewed, and again when the trader is flagged on a later
        trading day than the review
      example: new
      enum:
        - new
        - reviewed
        - cleared
    savedState:
      type: string
      description: The state last saved, if any
      example: cleared
      enum:
        - new
        - reviewed
        - cleared
    outcome:
      type: string
      description: Outcome of the latest decision
      enum:
        - confirmed
        - innocent
        - watching
    report:
      type: string
      example: hedge_pairs
      enum:
        - hedge_pairs
        - copy_pairs
        - copy_groups
        - shared_devices
        - news_window_fills
    level:
      type: string
      example: medium
      enum:
        - low
        - medium
        - high
  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

- [Count flagged traders](https://docs.hyperprop.com/platform-api/risk/count-flagged-traders.md)
- [List the decisions on a trader](https://docs.hyperprop.com/platform-api/risk/list-the-decisions-on-a-trader.md)
- [List the traders you follow](https://docs.hyperprop.com/platform-api/trader-insights/list-the-traders-you-follow.md)
- [Record a decision on a flagged trader](https://docs.hyperprop.com/platform-api/risk/record-a-decision-on-a-flagged-trader.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.