> ## Documentation Index > Fetch the complete documentation index at: https://docs.hifi.com/llms.txt > Use this file to discover all available pages before exploring further. # Preview Metric Results > Executes a metric calculation on the fly without saving it to the database. Useful for testing parameters or ad-hoc analysis. ## OpenAPI ````yaml https://production.hifi.com/api/v2/openapi.json post /v2/reporting/metrics/preview openapi: 3.0.0 info: title: Hifi API version: 2.0.0 description: API documentation for Hifi servers: - url: https://production.hifibridge.com description: Production server - url: https://sandbox.hifibridge.com description: Sandbox server security: - bearerAuth: [] tags: - name: Common description: Common endpoints - name: User description: User endpoints - name: Kyc description: Kyc endpoints - name: Wallet description: Wallet endpoints - name: Account description: Account endpoints - name: External Account description: External Account endpoints for managing beneficiary bank accounts - name: Fiat Account description: Fiat Account endpoints - name: Virtual Account description: Virtual Account endpoints - name: Onramp description: Onramp endpoints - name: Offramp description: Offramp endpoints - name: Orchestration Address description: >- Orchestration Address endpoints — persistent on-chain wallets that automatically off-ramp incoming stablecoin deposits to a USD bank account - name: Crypto Transfer description: Crypto Transfer endpoints - name: Cross-Chain Bridge description: Cross-Chain Bridge endpoints - name: Token Swap description: Token Swap endpoints - name: Canton Offers description: Canton Offers endpoints - name: Transfer Rules description: Transfer approval rules and configuration - name: Transfer Approvals description: Transfer approval workflow and admin actions - name: File description: File endpoints - name: Reporting description: Reporting and metrics endpoints paths: /v2/reporting/metrics/preview: post: tags: - Reporting summary: Preview Metric Results description: >- Executes a metric calculation on the fly without saving it to the database. Useful for testing parameters or ad-hoc analysis. requestBody: $ref: '#/components/requestBodies/PreviewMetricBody' responses: '200': $ref: '#/components/responses/MetricCalculationResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' '404': $ref: '#/components/responses/NotFoundResponse' '500': $ref: '#/components/responses/InternalServerErrorResponse' components: requestBodies: PreviewMetricBody: required: true content: application/json: schema: $ref: '#/components/schemas/PreviewMetricRequest' examples: PreviewMetricRequestGrossVolumeExample: $ref: '#/components/examples/PreviewMetricRequestGrossVolumeExample' PreviewMetricRequestGrossVolumeMonthlyExample: $ref: >- #/components/examples/PreviewMetricRequestGrossVolumeMonthlyExample PreviewMetricRequestTransfersWithBreakdownsExample: $ref: >- #/components/examples/PreviewMetricRequestTransfersWithBreakdownsExample responses: MetricCalculationResponse: description: Metric calculation results content: application/json: schema: $ref: '#/components/schemas/MetricCalculationResponse' examples: PreviewMetricResponseGrossVolumeNoBreakdownsExample: $ref: >- #/components/examples/PreviewMetricResponseGrossVolumeNoBreakdownsExample PreviewMetricResponseGrossVolumeMonthlyExample: $ref: >- #/components/examples/PreviewMetricResponseGrossVolumeMonthlyExample PreviewMetricResponseTransfersWithBreakdownsExample: $ref: >- #/components/examples/PreviewMetricResponseTransfersWithBreakdownsExample MetricResultsNewUsersExample: $ref: '#/components/examples/MetricResultsNewUsersExample' MetricResultsGrossVolumeExample: $ref: '#/components/examples/MetricResultsGrossVolumeExample' BadRequestResponse: description: Bad request - validation error content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string details: type: object description: Field-specific validation errors UnauthorizedResponse: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Unauthorized' NotFoundResponse: description: Resource not found content: application/json: schema: type: object properties: status: type: string enum: - error error: type: object properties: code: type: string message: type: string InternalServerErrorResponse: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/InternalServerError' schemas: PreviewMetricRequest: type: object description: Request to preview a metric calculation without saving properties: template: type: string enum: - GROSS_VOLUME - TRANSACTION_COUNT - NEW_USERS description: Metric template name params: $ref: '#/components/schemas/MetricParams' required: - template - params MetricCalculationResponse: type: object description: > Response from metric calculation endpoints. The structure of `data` array items varies based on the `breakdowns` parameter in the request. **Base structure (no breakdowns):** - Each item has: `periodStart`, plus metric-specific fields (e.g., `grossVolume`, `transactionCount`) **With breakdowns:** - Each item includes breakdown dimension fields (e.g., `transactionType`, `transactionStatus`, `userId`) - Field names match the breakdown dimension names from the request **Example without breakdowns:** ```json { "status": "success", "data": [ { "periodStart": "2025-01-01T00:00:00Z", "grossVolume": 1000.50 }, { "periodStart": "2025-01-02T00:00:00Z", "grossVolume": 2000.75 } ], "metadata": { ... } } ``` **Example with breakdowns: ["transactionType"]:** ```json { "status": "success", "data": [ { "periodStart": "2025-01-01T00:00:00Z", "transactionType": "onramp", "grossVolume": 500.25 }, { "periodStart": "2025-01-01T00:00:00Z", "transactionType": "offramp", "grossVolume": 500.25 } ], "metadata": { ... } } ``` properties: status: type: string enum: - success description: Response status data: type: array description: > Array of metric calculation results. Each object structure depends on: 1. The metric template (determines metric value fields) 2. The breakdowns parameter (adds dimension fields) items: type: object description: > Metric result row. Contains: - `periodStart` (always present): ISO 8601 timestamp - Metric-specific fields (e.g., `grossVolume`, `transactionCount`, `newUserCount`) - Breakdown dimension fields (if breakdowns specified): field names match breakdown dimension names Additional properties may be present based on: - Metric template (adds template-specific value fields) - Breakdown dimensions (adds dimension fields matching breakdown names) properties: periodStart: type: string format: date-time description: Start of the calculation period grossVolume: type: number description: Gross volume amount (for GROSS_VOLUME template) grossVolumeUsd: type: number description: Gross volume in USD (for GROSS_VOLUME template) transactionCount: type: number description: Number of transactions (for TRANSACTION_COUNT template) newUserCount: type: number description: Number of new users (for NEW_USERS template) transactionType: type: string enum: - onramp - offramp - transfer description: Transaction type (present if "transactionType" in breakdowns) transactionStatus: type: string enum: - AWAITING_FUNDS - COMPLETED - CRYPTO_FAILED - CRYPTO_INITIATED - CRYPTO_PENDING - FAILED - FIAT_FAILED - FIAT_INITIATED - FIAT_PENDING - FIAT_PROCESSED - FIAT_RETURNED - INITIATED - NOT_INITIATED - PENDING - QUOTE_FAILED - REJECTED description: >- Transaction status (present if "transactionStatus" in breakdowns) userId: type: string format: uuid description: User ID (present if "userId" in breakdowns) additionalProperties: true metadata: $ref: '#/components/schemas/MetricCalculationMetadata' Unauthorized: type: object properties: code: type: integer description: Error code error: type: string description: Error type errorDetails: type: string description: Detailed error message InternalServerError: type: object properties: code: type: integer description: Error code error: type: string description: Error type errorDetails: type: string description: Detailed error message MetricParams: type: object description: > Metric parameters. Structure varies by template, but common fields include: - Date range filters - Calculation interval - Breakdown dimensions - Template-specific filters Additional properties may be present based on the metric template. Each template may define template-specific parameters. properties: createdAfter: type: string format: date description: Filter transactions created after this date (ISO 8601) createdBefore: type: string format: date description: Filter transactions created before this date (ISO 8601) calculationInterval: type: string enum: - day - week - month description: Time interval for aggregation userIds: type: array items: type: string format: uuid description: Filter by specific user IDs transactionTypes: type: array items: type: string enum: - onramp - offramp - transfer description: Filter by transaction types transactionStatuses: type: array items: type: string enum: - AWAITING_FUNDS - COMPLETED - CRYPTO_FAILED - CRYPTO_INITIATED - CRYPTO_PENDING - FAILED - FIAT_FAILED - FIAT_INITIATED - FIAT_PENDING - FIAT_PROCESSED - FIAT_RETURNED - INITIATED - NOT_INITIATED - PENDING - QUOTE_FAILED - REJECTED description: Filter by transaction statuses breakdowns: type: array items: type: string enum: - transactionType - transactionStatus - userId maxItems: 2 description: | Dimensions to group results by. Maximum 2 breakdowns allowed. Field names in response data will match these dimension names. limit: type: integer minimum: 1 maximum: 10000 default: 500 description: Maximum number of records to return additionalProperties: true MetricCalculationMetadata: type: object description: Metadata about the metric calculation properties: template: type: string enum: - GROSS_VOLUME - TRANSACTION_COUNT - NEW_USERS description: The metric template used recordCount: type: integer description: Actual number of records returned projectedRowCount: type: integer nullable: true description: Projected total row count (null if no breakdowns) filledCount: type: integer description: Number of time periods filled with zero values calculationInterval: type: string enum: - day - week - month description: The calculation interval used dateRange: type: object properties: start: type: string format: date description: Start date (ISO 8601) end: type: string format: date description: End date (ISO 8601) filters: type: object description: Information about filters that were applied additionalProperties: true breakdowns: type: object nullable: true description: Breakdown metadata (null if no breakdowns specified) properties: dimensions: type: array items: type: string enum: - transactionType - transactionStatus - userId description: List of breakdown dimensions used dimensionCounts: type: object additionalProperties: type: integer description: | Count of unique values per breakdown dimension. Keys match breakdown dimension names. metric: type: string nullable: true description: Metric name (only present for saved metrics, not previews) examples: PreviewMetricRequestGrossVolumeExample: summary: Preview GROSS_VOLUME metric (no breakdowns) value: template: GROSS_VOLUME params: createdAfter: '2025-11-01' createdBefore: '2025-11-07' calculationInterval: day transactionTypes: - onramp - offramp PreviewMetricRequestGrossVolumeMonthlyExample: summary: Preview GROSS_VOLUME metric (monthly interval) value: template: GROSS_VOLUME params: createdAfter: '2025-01-01' createdBefore: '2025-12-01' calculationInterval: month transactionTypes: - onramp - offramp PreviewMetricRequestTransfersWithBreakdownsExample: summary: Preview TRANSACTION_COUNT metric (with multiple breakdowns) value: template: TRANSACTION_COUNT params: createdAfter: '2025-11-01' createdBefore: '2025-11-07' calculationInterval: day transactionTypes: - onramp - offramp transactionStatuses: - COMPLETED - FAILED breakdowns: - transactionType - transactionStatus PreviewMetricResponseGrossVolumeNoBreakdownsExample: summary: GROSS_VOLUME calculation result (no breakdowns) value: status: success data: - periodStart: '2025-11-06' grossVolume: 0 - periodStart: '2025-11-05' grossVolume: 0 - periodStart: '2025-11-04' grossVolume: 0 - periodStart: '2025-11-03' grossVolume: 0 - periodStart: '2025-11-02' grossVolume: 0 - periodStart: '2025-11-01' grossVolume: 0 metadata: template: GROSS_VOLUME recordCount: 6 projectedRowCount: null filledCount: 6 calculationInterval: day dateRange: start: '2025-11-01' end: '2025-11-07' filters: createdAfter: applied: subset specified: true values: '2025-11-01' createdBefore: applied: subset specified: true values: '2025-11-07' calculationInterval: applied: subset specified: true values: day transactionTypes: applied: subset specified: true count: 2 values: - onramp - offramp userIds: applied: all specified: false count: 1000 note: 1000 total (list omitted for brevity) breakdowns: null PreviewMetricResponseGrossVolumeMonthlyExample: summary: GROSS_VOLUME calculation result (monthly, with data) value: status: success data: - periodStart: '2025-11-01' grossVolume: 191 - periodStart: '2025-10-01' grossVolume: 124.05 - periodStart: '2025-09-01' grossVolume: 6707.86 - periodStart: '2025-08-01' grossVolume: 3066672.14 - periodStart: '2025-07-01' grossVolume: 199916.7 - periodStart: '2025-06-01' grossVolume: 24791 - periodStart: '2025-05-01' grossVolume: 57653 - periodStart: '2025-04-01' grossVolume: 54354.2 - periodStart: '2025-03-01' grossVolume: 0 - periodStart: '2025-02-01' grossVolume: 0 - periodStart: '2025-01-01' grossVolume: 0 - periodStart: '2024-12-01' grossVolume: 0 metadata: template: GROSS_VOLUME recordCount: 12 projectedRowCount: null filledCount: 4 calculationInterval: month dateRange: start: '2025-01-01' end: '2025-12-01' filters: createdAfter: applied: subset specified: true values: '2025-01-01' createdBefore: applied: subset specified: true values: '2025-12-01' calculationInterval: applied: subset specified: true values: month transactionTypes: applied: subset specified: true count: 2 values: - onramp - offramp userIds: applied: all specified: false count: 1000 note: 1000 total (list omitted for brevity) breakdowns: null PreviewMetricResponseTransfersWithBreakdownsExample: summary: TRANSACTION_COUNT calculation result (with breakdowns) value: status: success data: - periodStart: '2025-11-06' transactionType: offramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-06' transactionType: offramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-06' transactionType: onramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-06' transactionType: onramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-05' transactionType: offramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-05' transactionType: offramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-05' transactionType: onramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-05' transactionType: onramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-04' transactionType: offramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-04' transactionType: offramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-04' transactionType: onramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-04' transactionType: onramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-03' transactionType: offramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-03' transactionType: offramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-03' transactionType: onramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-03' transactionType: onramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-02' transactionType: offramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-02' transactionType: offramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-02' transactionType: onramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-02' transactionType: onramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-01' transactionType: offramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-01' transactionType: offramp transactionStatus: COMPLETED transactionCount: 0 - periodStart: '2025-11-01' transactionType: onramp transactionStatus: FAILED transactionCount: 0 - periodStart: '2025-11-01' transactionType: onramp transactionStatus: COMPLETED transactionCount: 0 metadata: template: TRANSACTION_COUNT recordCount: 24 projectedRowCount: 180 filledCount: 24 calculationInterval: day dateRange: start: '2025-11-01' end: '2025-11-07' filters: createdAfter: applied: subset specified: true values: '2025-11-01' createdBefore: applied: subset specified: true values: '2025-11-07' calculationInterval: applied: subset specified: true values: day transactionTypes: applied: subset specified: true count: 2 values: - onramp - offramp transactionStatuses: applied: subset specified: true count: 2 values: - COMPLETED - FAILED userIds: applied: all specified: false count: 1000 note: 1000 total (list omitted for brevity) breakdowns: applied: subset specified: true count: 2 values: - transactionType - transactionStatus breakdowns: dimensions: - transactionType - transactionStatus dimensionCounts: transactionType: 3 transactionStatus: 10 MetricResultsNewUsersExample: summary: NEW_USERS metric results (no breakdowns) value: status: success data: - periodStart: '2025-12-01' newUserCount: 0 - periodStart: '2025-11-30' newUserCount: 4 - periodStart: '2025-11-29' newUserCount: 4 - periodStart: '2025-11-28' newUserCount: 0 - periodStart: '2025-11-27' newUserCount: 0 - periodStart: '2025-11-26' newUserCount: 0 - periodStart: '2025-11-25' newUserCount: 0 - periodStart: '2025-11-24' newUserCount: 0 - periodStart: '2025-11-23' newUserCount: 0 - periodStart: '2025-11-22' newUserCount: 0 - periodStart: '2025-11-21' newUserCount: 25 - periodStart: '2025-11-20' newUserCount: 0 - periodStart: '2025-11-19' newUserCount: 0 - periodStart: '2025-11-18' newUserCount: 0 - periodStart: '2025-11-17' newUserCount: 0 - periodStart: '2025-11-16' newUserCount: 0 - periodStart: '2025-11-15' newUserCount: 0 - periodStart: '2025-11-14' newUserCount: 0 - periodStart: '2025-11-13' newUserCount: 3 - periodStart: '2025-11-12' newUserCount: 14 - periodStart: '2025-11-11' newUserCount: 4 - periodStart: '2025-11-10' newUserCount: 49 - periodStart: '2025-11-09' newUserCount: 4 - periodStart: '2025-11-08' newUserCount: 1 - periodStart: '2025-11-07' newUserCount: 6 - periodStart: '2025-11-06' newUserCount: 0 - periodStart: '2025-11-05' newUserCount: 4 - periodStart: '2025-11-04' newUserCount: 3 - periodStart: '2025-11-03' newUserCount: 0 - periodStart: '2025-11-01' newUserCount: 0 metadata: template: NEW_USERS recordCount: 335 projectedRowCount: null filledCount: 135 calculationInterval: day dateRange: start: '2025-01-01' end: '2025-12-01' filters: createdAfter: applied: subset specified: true values: '2025-01-01' createdBefore: applied: subset specified: true values: '2025-12-01' calculationInterval: applied: subset specified: true values: day breakdowns: null metric: testname123 MetricResultsGrossVolumeExample: summary: GROSS_VOLUME metric results (no breakdowns, with metric name) value: status: success data: - periodStart: '2025-11-06' grossVolume: 0 - periodStart: '2025-11-05' grossVolume: 0 - periodStart: '2025-11-04' grossVolume: 0 - periodStart: '2025-11-03' grossVolume: 0 - periodStart: '2025-11-02' grossVolume: 0 - periodStart: '2025-11-01' grossVolume: 0 metadata: template: GROSS_VOLUME recordCount: 6 projectedRowCount: null filledCount: 6 calculationInterval: day dateRange: start: '2025-11-01' end: '2025-11-07' filters: createdAfter: applied: subset specified: true values: '2025-11-01' createdBefore: applied: subset specified: true values: '2025-11-07' calculationInterval: applied: subset specified: true values: day transactionTypes: applied: subset specified: true count: 2 values: - onramp - offramp userIds: applied: all specified: false count: 1000 note: 1000 total (list omitted for brevity) breakdowns: null metric: Daily Revenue Report securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````