> ## 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 organization analytics > Retrieve aggregate analytics and statistics for your organization's trading accounts in a single call. ## What you get | Section | Description | |---------|-------------| | **summary** | Total accounts, total traders, active lockouts | | **accounts.byStatus** | Counts per status: not_started, in_progress, passed, failed, expired | | **accounts.byType** | Counts per type: evaluation, sim_funded, competition | | **accounts.passRate** | Pass rate = passed / (passed + failed) × 100 | | **accounts.passRateIncludingExpired** | Stricter: passed / (passed + failed + expired) × 100 | | **accounts.avgCompletionDays** | Average days to complete (pass or fail) | | **accounts.avgTimeToPassDays** | Average days to pass | | **revenue** | Total revenue, purchase count, average per account | | **payouts** | Total paid out, payout count, average/largest payout, payout ratio (paid out ÷ revenue) | | **risk** | Open profit liability across in-progress accounts, accounts in profit vs drawdown, lockout breakdown | | **violations** | Violation reason breakdown for failed accounts | | **performance** | Average P&L, drawdown, trades, win rate | ## Filters | Parameter | Type | Example | Description | |-----------|------|---------|-------------| | `startDate` | ISO 8601 | `2026-01-01` | Only accounts created on or after this date | | `endDate` | ISO 8601 | `2026-03-31` | Only accounts created on or before this date | | `type` | string | `evaluation` | Only accounts of this type (`evaluation`, `sim_funded`, `competition`) | All filters are optional. Omit all for all-time analytics across all account types. ## Null values Fields like `passRate`, `avgCompletionDays`, `avgRevenuePerAccount`, and `performance` return `null` when there is insufficient data to compute them (e.g. no completed accounts, no purchases, no performance data). This avoids misleading zero values. ## Error codes | HTTP | Code | When | |------|------|------| | 400 | `VALIDATION_ERROR` | startDate/endDate is not valid ISO 8601, or type is not evaluation, sim_funded, or competition | | 401 | `UNAUTHORIZED` | Missing or invalid Bearer token / API key | | 403 | `FORBIDDEN` | Token does not belong to any organization | | 500 | `ANALYTICS_ERROR` | Internal error (database query failure) | ## Examples ```bash # All-time analytics (API key) curl -X GET "https://api.hyperprop.com/platform/v1/organization/analytics" \ -H "X-API-Key: hp_live_your_key_here" # Q1 2026 evaluations only (API key) curl -X GET "https://api.hyperprop.com/platform/v1/organization/analytics?startDate=2026-01-01&endDate=2026-03-31&type=evaluation" \ -H "X-API-Key: hp_live_your_key_here" # Using Bearer token (dashboard) curl -X GET "https://api.hyperprop.com/platform/v1/organization/analytics" \ -H "Authorization: Bearer eyJhbGciOi..." ``` **Authentication:** Accepts either `Authorization: Bearer ` (dashboard) or `X-API-Key: hp_live_...` (programmatic). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/organization/analytics 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 Two methods, depending on who is calling: ### Bearer Token (JWT) — users & dashboard Most endpoints accept a JWT via `Authorization: Bearer `. Used by the dashboard and client applications. ### API Key — organizations (prop firms) Organization endpoints also accept `X-API-Key: hp_live_...` for programmatic access from your backend — no browser session needed. Keys are managed by organization admins in the dashboard; each key carries permissions (`read`, `write`, `admin`) and can be rotated or revoked at any time. Keys are stored hashed (SHA-256) — the raw key is shown once at creation. Endpoints that create or modify data require `write` or `admin`. ## Quick Start ```bash # 1. List your trading plans (grab a tradingPlanId) curl "https://api.hyperprop.com/platform/v1/organization/trading-plans" \ -H "X-API-Key: hp_live_your_key_here" # 2. Create a trading account for a trader (by Hyperprop user ID or email) curl -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts" \ -H "X-API-Key: hp_live_your_key_here" \ -H "Content-Type: application/json" \ -d '{"type": "evaluation", "tradingPlanId": "", "email": "trader@example.com"}' ``` ## Response Envelope & Error Handling **Success** responses always wrap the payload: ```json { "success": true, "data": { ... }, "message": "optional human-readable note" } ``` **Errors** — including request-validation failures, auth failures, and errors proxied from the trade engine — always return this single uniform shape with a machine-readable `code` you can switch on: ```json { "success": false, "statusCode": 404, "error": "Not Found", "message": "No Hyperprop user found with that email. The trader must have a Hyperprop account before an account can be created for them.", "code": "TRADER_NOT_FOUND" } ``` Parse rule of thumb: check `success`; on `false`, switch on `code` (never on `message` text — messages can be reworded). Some errors carry additional structured context alongside these fields (e.g. payout rejections include a `consistency` block). Common codes: `VALIDATION_ERROR` (malformed payload/params), `UNAUTHORIZED`, `INSUFFICIENT_PERMISSIONS` / `NOT_ADMIN` (key lacks write/admin), `*_NOT_FOUND` (missing resource), `*_NOT_IN_ORG` (resource belongs to another organization), `IDEMPOTENCY_KEY_IN_PROGRESS` (duplicate in flight), `ENGINE_UNREACHABLE` (trade engine down — retry with the same idempotency key). Endpoint-specific codes (e.g. payout `OPEN_EXPOSURE`, `CONSISTENCY_BLOCKED`) are documented on each endpoint. ## Idempotency **Every mutating endpoint (POST, PUT, PATCH, DELETE) honors idempotency keys uniformly.** Send an `Idempotency-Key` header (the `X-Idempotency-Key` spelling is accepted as an alias) to retry any write safely without creating duplicates. How it works: - The key is scoped to your organization + the request path. The first request with a given key executes normally and its response is cached for **24 hours**. - A replay (same key, same path) within 24 hours returns the cached response with an `Idempotency-Replayed: true` response header — the operation is **not** executed again. - If a request with the same key is still in flight, the duplicate gets `409 IDEMPOTENCY_KEY_IN_PROGRESS` — back off and retry; you'll then receive the cached response. - 5xx responses are **not** cached, so retrying after a server error re-executes the request (that's what you want). 2xx-4xx responses are cached — if a request failed validation and you fix the payload, use a **fresh key**. - Keys are free-form strings up to 255 characters. Use something that identifies the operation on your side, e.g. `order-8814-attempt-1`. ```bash curl -X POST "https://api.hyperprop.com/platform/v1/organization/trading-accounts" \ -H "X-API-Key: hp_live_your_key_here" \ -H "Idempotency-Key: order-8814-attempt-1" \ -H "Content-Type: application/json" \ -d '{"type": "evaluation", "tradingPlanId": "...", "traderId": "..."}' ``` This applies to account creation, account PATCH (status, currentBalance, metadata), rules, plans, lockouts, payouts, team, webhooks — every write on the platform API. Payouts additionally forward the key to the trade engine for engine-level double-withdrawal protection. ## Pagination & Sorting List endpoints support both styles: - **Cursor (recommended):** pass `?cursor=` from the previous response's `pagination.nextCursor`. Stable under concurrent writes. - **Offset:** `?limit=&offset=` with `pagination.total` / `hasMore` in the response. Sorting uses `?sort=field:direction` (e.g. `?sort=created_at:asc`); allowed fields are listed per endpoint. Default: `created_at:desc`. ## Custom Metadata Trading accounts, purchases, traders, plans, and rules all carry a free-form `metadata` JSON object. Use it to store your own references — payment IDs, campaign tags, payout records, internal notes. Hyperprop stores and returns it verbatim (and lets you filter list endpoints by it, e.g. `?metadata=stripePaymentId:pi_123`) but never interprets it. Update endpoints support `mergeMetadata: true` for shallow (top-level) merges instead of wholesale replacement. ## Webhooks Subscribe to account lifecycle events (`account.created`, `account.status_changed`, `account.updated`, `account.passed`, `account.failed`, and more) via the Webhooks endpoints. Deliveries are HMAC-SHA256 signed — verify `X-Hyperprop-Signature` with your endpoint secret, using `X-Hyperprop-Timestamp` for replay protection; `X-Hyperprop-Delivery` gives you a unique delivery ID for deduplication. Failed deliveries are retried with backoff, and you can redeliver any event from the dashboard or API. ## MCP Connector (AI Agents) The platform ships a built-in [MCP](https://modelcontextprotocol.io) server, so AI agents and assistants (Claude, Cursor, custom agents) can operate your organization directly — no integration code required. ```http Endpoint: POST https://api.hyperprop.com/platform/v1/mcp Transport: Streamable HTTP (stateless, JSON responses) Auth: X-API-Key header, Authorization: Bearer hp_live_..., or OAuth ``` **Claude web / desktop (Add custom connector):** paste the endpoint URL and leave the OAuth Client ID/Secret fields empty — the connector registers itself automatically. Claude opens a Hyperprop consent page where an org admin pastes the organization API key once; access then follows that key's permissions and ends if the key is revoked. (Under the hood: OAuth 2.1 with PKCE and dynamic client registration.) **Cursor / Claude Code — `mcp.json`:** ```json { "mcpServers": { "hyperprop": { "url": "https://api.hyperprop.com/platform/v1/mcp", "headers": { "X-API-Key": "hp_live_your_key_here" } } } } ``` **Available tools (12):** `list_trading_plans`, `list_trading_accounts`, `get_trading_account`, `get_account_audit_log`, `list_traders`, `get_trader`, `list_purchases`, `get_purchase`, `get_billing_summary` (read) · `create_trading_account`, `update_trading_account`, `record_payout` (write). Every tool call executes the corresponding REST endpoint with your key, so organization scoping, permissions, validation, audit logging, and webhooks apply exactly as documented on each endpoint. Read tools work with any key; write tools need `write`/`admin` permission — connect a **read-only key** if you want a strictly read-only agent. `create_trading_account` accepts an optional `idempotencyKey` so agent retries can't create duplicates, and `record_payout` implements the documented payout recipe (append to `metadata.payouts`, adjust `currentBalance`, audit-logged `reason`). ## Endpoint Groups - **Authentication** — Sign up, sign in, OAuth, MFA, password reset. No auth required for most. - **User** — Profile, notifications, demo accounts, audit logs. Requires **Bearer token** (JWT). - **Organization** — Trading accounts, plans, rules, traders, purchases, lockouts, billing, bulk operations, webhooks, analytics. Accepts **Bearer token** OR **API Key**. - **System** — Health checks. No auth required. 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: Authentication description: >- User authentication - signup, signin, signout, password reset, email verification, OAuth, and MFA - name: User description: >- User account management - profile, notifications, agreements, dismissals, and audit logs. Requires Bearer token. - name: Organization description: >- Organization management - profile, team, trading accounts, plans, and rules. Supports **dual authentication**: Bearer JWT token (dashboard users) OR X-API-Key (programmatic access). - name: Demo description: >- Demo account management - import, list, and delete demo trading accounts. Requires Bearer token. - name: Market Data description: CME futures contracts and market data. Requires Bearer token. - name: System description: System endpoints - health checks and connectivity paths: /v1/organization/analytics: get: tags: - Organization summary: Get organization analytics description: >- Retrieve aggregate analytics and statistics for your organization's trading accounts in a single call. ## What you get | Section | Description | |---------|-------------| | **summary** | Total accounts, total traders, active lockouts | | **accounts.byStatus** | Counts per status: not_started, in_progress, passed, failed, expired | | **accounts.byType** | Counts per type: evaluation, sim_funded, competition | | **accounts.passRate** | Pass rate = passed / (passed + failed) × 100 | | **accounts.passRateIncludingExpired** | Stricter: passed / (passed + failed + expired) × 100 | | **accounts.avgCompletionDays** | Average days to complete (pass or fail) | | **accounts.avgTimeToPassDays** | Average days to pass | | **revenue** | Total revenue, purchase count, average per account | | **payouts** | Total paid out, payout count, average/largest payout, payout ratio (paid out ÷ revenue) | | **risk** | Open profit liability across in-progress accounts, accounts in profit vs drawdown, lockout breakdown | | **violations** | Violation reason breakdown for failed accounts | | **performance** | Average P&L, drawdown, trades, win rate | ## Filters | Parameter | Type | Example | Description | |-----------|------|---------|-------------| | `startDate` | ISO 8601 | `2026-01-01` | Only accounts created on or after this date | | `endDate` | ISO 8601 | `2026-03-31` | Only accounts created on or before this date | | `type` | string | `evaluation` | Only accounts of this type (`evaluation`, `sim_funded`, `competition`) | All filters are optional. Omit all for all-time analytics across all account types. ## Null values Fields like `passRate`, `avgCompletionDays`, `avgRevenuePerAccount`, and `performance` return `null` when there is insufficient data to compute them (e.g. no completed accounts, no purchases, no performance data). This avoids misleading zero values. ## Error codes | HTTP | Code | When | |------|------|------| | 400 | `VALIDATION_ERROR` | startDate/endDate is not valid ISO 8601, or type is not evaluation, sim_funded, or competition | | 401 | `UNAUTHORIZED` | Missing or invalid Bearer token / API key | | 403 | `FORBIDDEN` | Token does not belong to any organization | | 500 | `ANALYTICS_ERROR` | Internal error (database query failure) | ## Examples ```bash # All-time analytics (API key) curl -X GET "https://api.hyperprop.com/platform/v1/organization/analytics" \ -H "X-API-Key: hp_live_your_key_here" # Q1 2026 evaluations only (API key) curl -X GET "https://api.hyperprop.com/platform/v1/organization/analytics?startDate=2026-01-01&endDate=2026-03-31&type=evaluation" \ -H "X-API-Key: hp_live_your_key_here" # Using Bearer token (dashboard) curl -X GET "https://api.hyperprop.com/platform/v1/organization/analytics" \ -H "Authorization: Bearer eyJhbGciOi..." ``` **Authentication:** Accepts either `Authorization: Bearer ` (dashboard) or `X-API-Key: hp_live_...` (programmatic). operationId: getV1OrganizationAnalytics parameters: - description: >- Filter accounts created on or after this date (ISO 8601). Examples: `2026-01-01`, `2026-01-01T00:00:00.000Z` x-format: isoDate: true name: startDate in: query schema: type: string - description: >- Filter accounts created on or before this date (ISO 8601). Examples: `2026-03-31`, `2026-03-31T23:59:59.999Z` x-format: isoDate: true name: endDate in: query schema: type: string - description: >- Filter by account type. Only accounts of this type are included in all metrics. name: type in: query schema: type: string enum: - evaluation - sim_funded - competition responses: '200': description: Success — Returns aggregate analytics for your organization content: '*/*': schema: $ref: '#/components/schemas/Model30' '400': description: Validation error — invalid date format, date range, or account type content: '*/*': schema: $ref: '#/components/schemas/Model31' '401': description: Unauthorized — missing or invalid Bearer token / API key content: '*/*': schema: $ref: '#/components/schemas/Model32' '403': description: >- Forbidden — authenticated user is not associated with any organization content: '*/*': schema: $ref: '#/components/schemas/Model33' '500': description: Internal error — database query or aggregation failure content: '*/*': schema: $ref: '#/components/schemas/Model34' security: - Bearer: [] - X-API-Key: [] components: schemas: Model30: type: object properties: success: type: boolean example: true data: $ref: '#/components/schemas/Model29' Model31: 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: >- Date must be a valid ISO 8601 string (e.g. 2026-01-01 or 2026-01-01T00:00:00.000Z) code: type: string description: Machine-readable error code — switch on this, not on message text example: VALIDATION_ERROR Model32: type: object properties: statusCode: type: number example: 401 error: type: string example: Unauthorized message: type: string example: Invalid or expired token code: type: string example: UNAUTHORIZED Model33: type: object properties: statusCode: type: number example: 403 error: type: string example: Forbidden message: type: string example: You do not belong to any organization code: type: string example: FORBIDDEN Model34: type: object properties: statusCode: type: number example: 500 error: type: string example: Internal Server Error message: type: string example: An error occurred fetching analytics code: type: string example: ANALYTICS_ERROR Model29: type: object properties: organizationId: type: string description: Your organization ID example: a6fcc0ce-eb28-4f43-b256-96a3144b0d34 x-format: guid: true organizationName: type: string description: Your organization display name example: Apex Trading Co generatedAt: type: string description: ISO 8601 timestamp when this response was generated (always UTC) example: '2026-03-29T15:00:00.000Z' x-format: isoDate: true filters: $ref: '#/components/schemas/filters' summary: $ref: '#/components/schemas/summary' accounts: $ref: '#/components/schemas/accounts' revenue: $ref: '#/components/schemas/revenue' payouts: $ref: '#/components/schemas/payouts' risk: $ref: '#/components/schemas/risk' violations: $ref: '#/components/schemas/violations' performance: $ref: '#/components/schemas/performance' filters: type: object description: Echoes back the filters applied to this analytics request properties: startDate: type: string description: Start date filter applied (null if not set) example: '2026-01-01T00:00:00.000Z' endDate: type: string description: End date filter applied (null if not set) example: '2026-03-31T23:59:59.999Z' type: type: string description: Account type filter applied (null if not set) example: evaluation summary: type: object description: High-level summary counts properties: totalAccounts: type: integer description: Total number of trading accounts matching the filters example: 1250 totalTraders: type: integer description: >- Total registered traders in the organization (unaffected by date/type filters) example: 892 activeLockouts: type: integer description: Number of currently active lockouts across matching accounts example: 15 accounts: type: object description: Account breakdown, pass rates, and timing metrics properties: byStatus: $ref: '#/components/schemas/byStatus' byType: $ref: '#/components/schemas/byType' passRate: type: number description: >- Percentage of completed accounts that passed. Formula: passed / (passed + failed) × 100. Excludes expired, in_progress, and not_started. Returns null if no accounts have completed. example: 30 passRateIncludingExpired: type: number description: >- Stricter pass rate that treats expired as non-pass. Formula: passed / (passed + failed + expired) × 100. Returns null if denominator is zero. example: 24 avgCompletionDays: type: number description: >- Average calendar days from started_at to completed_at for passed + failed accounts. Returns null if no accounts have both timestamps. example: 12.5 avgTimeToPassDays: type: number description: >- Average calendar days from started_at to completed_at for passed accounts only. Returns null if no passed accounts have both timestamps. example: 18.3 revenue: type: object description: Revenue and purchase metrics properties: totalRevenue: type: number description: >- Sum of price_paid across all matching purchases (USD). Excludes $0 / free purchases. example: 187500 currency: type: string description: Revenue currency — always USD example: USD totalPurchases: type: integer description: Number of paid purchases (price_paid > 0) example: 1250 avgRevenuePerAccount: type: number description: totalRevenue / totalPurchases. Returns null if no paid purchases. example: 150 payouts: type: object description: Payout (balance withdrawal) aggregates for matching accounts properties: totalPaidOut: type: number description: >- Sum of all executed payouts (balance withdrawals) for matching accounts (USD). Date filters apply to the payout date. example: 48200 currency: type: string example: USD payoutCount: type: integer description: Number of executed payouts example: 31 avgPayout: type: number description: totalPaidOut / payoutCount. Null if no payouts. example: 1554.84 largestPayout: type: number description: Largest single payout. Null if no payouts. example: 5000 accountsWithPayouts: type: integer description: Distinct accounts that received at least one payout example: 18 payoutRatio: type: number description: >- totalPaidOut / totalRevenue × 100 — the share of purchase revenue paid back out to traders. The core prop-firm health metric. Null if no revenue. example: 25.7 risk: type: object description: Live risk exposure metrics properties: openProfitLiability: type: number description: >- Sum of (current balance − initial balance) across in-progress accounts currently in profit — what you would owe if every profitable in-progress account cashed out right now. example: 63400 accountsInProfit: type: integer description: In-progress accounts above their initial balance example: 120 accountsInDrawdown: type: integer description: In-progress accounts below their initial balance example: 210 activeLockouts: type: integer description: Currently active lockouts (same number as summary.activeLockouts) example: 15 lockoutsByMode: $ref: '#/components/schemas/lockoutsByMode' lockoutsByLockedBy: $ref: '#/components/schemas/lockoutsByLockedBy' violations: type: object description: >- Breakdown of violation_reason strings for failed accounts. Keys are the raw violation reason from the account, values are occurrence counts. Empty object if no failures. example: 'Daily Loss exceeded: $501.50 loss >= $500 limit': 180 'Max Loss exceeded: $2,550 loss >= $2,500 limit': 120 Max Drawdown exceeded: 95 unknown: 25 performance: type: object description: >- Aggregate performance metrics derived from the performance_data JSONB column on trading_accounts. Returns null if no accounts have performance data. properties: avgPnl: type: number description: >- Average total P&L (from performance_data.total_pnl) across all accounts with performance data example: 245.5 avgMaxDrawdown: type: number description: >- Average max drawdown (from performance_data.max_drawdown) across all accounts with performance data example: 1250.75 avgTradesPerAccount: type: number description: Average total_trades per account example: 47.3 avgWinRate: type: number description: >- Average win rate percentage: mean of (winning_trades / total_trades × 100) per account example: 38.2 byStatus: type: object description: Account counts broken down by status properties: notStarted: type: integer description: Accounts created but never started trading example: 120 inProgress: type: integer description: Accounts currently being traded example: 450 passed: type: integer description: Accounts that hit their profit target example: 180 failed: type: integer description: Accounts that violated a rule (drawdown, daily loss, max loss, etc.) example: 420 expired: type: integer description: Accounts that reached their end date without passing or failing example: 80 byType: type: object description: >- Account counts broken down by type. Keys are account types, values are counts. example: evaluation: 900 sim_funded: 300 competition: 50 lockoutsByMode: type: object description: Active lockouts broken down by mode example: admin: 5 trade_clock: 8 timed: 2 lockoutsByLockedBy: type: object description: Active lockouts broken down by who created them example: admin: 5 user: 8 system: 2 securitySchemes: Bearer: type: apiKey name: Authorization in: header description: >- JWT Bearer token for user session auth. Format: "Bearer {token}". Used by User and Organization endpoints. X-API-Key: type: apiKey name: X-API-Key in: header description: >- Organization API key for programmatic access. Format: "hp_live_{key}". Used by Organization endpoints as an alternative to Bearer token. Keys are managed in the dashboard. ```` ## Related topics - [Get purchases for your organization](/platform-api/organization/get-purchases-for-your-organization.md) - [Get your organization profile](/platform-api/organization/get-your-organization-profile.md) - [Get organization audit log](/platform-api/organization/get-organization-audit-log.md) - [Get traders for your organization](/platform-api/organization/get-traders-for-your-organization.md) - [Get trading plans for your organization](/platform-api/organization/get-trading-plans-for-your-organization.md)