---
title: "Preview Metric Results"
method: POST
path: "/v2/reporting/metrics/preview"
tags: ["Reporting"]
---

# Preview Metric Results

`POST /v2/reporting/metrics/preview`

Executes a metric calculation on the fly without saving it to the database. Useful for testing parameters or ad-hoc analysis.

## Request body

- PreviewMetricRequest — Request to preview a metric calculation without saving
  - `template` 'GROSS_VOLUME' | 'TRANSACTION_COUNT' | 'NEW_USERS', required — Metric template name
  - `params` MetricParams, required — 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.
    - `createdAfter` string, date — Filter transactions created after this date (ISO 8601)
    - `createdBefore` string, date — Filter transactions created before this date (ISO 8601)
    - `calculationInterval` 'day' | 'week' | 'month' | 'quarter' | 'year' — Time interval for aggregation
    - `userIds` string[] — Filter by specific user IDs
    - `transactionTypes` string[] — Filter by transaction types
    - `transactionStatuses` string[]
    - `breakdowns` string[] — Dimensions to group results by. Maximum 2 breakdowns allowed. Field names in response data will match these dimension names.
    - `limit` integer — Maximum number of records to return

## Response `200`

Metric calculation results

- MetricCalculationResponse — 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": { ... } } ```
  - `status` 'success' — Response status
  - `data` object[] — 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)
    - `periodStart` string, date-time — Start of the calculation period
    - `grossVolume` number — Gross volume amount (for GROSS_VOLUME template)
    - `grossVolumeUsd` number — Gross volume in USD (for GROSS_VOLUME template)
    - `transactionCount` number — Number of transactions (for TRANSACTION_COUNT template)
    - `newUserCount` number — Number of new users (for NEW_USERS template)
    - `transactionType` 'onramp' | 'offramp' | 'transfer' — Transaction type (present if "transactionType" in breakdowns)
    - `transactionStatus` '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' — Transaction status (present if "transactionStatus" in breakdowns)
    - `userId` string, uuid — User ID (present if "userId" in breakdowns)
  - `metadata` MetricCalculationMetadata — Metadata about the metric calculation
    - `template` 'GROSS_VOLUME' | 'TRANSACTION_COUNT' | 'NEW_USERS' — The metric template used
    - `recordCount` integer — Actual number of records returned
    - `projectedRowCount` integer, nullable — Projected total row count (null if no breakdowns)
    - `filledCount` integer — Number of time periods filled with zero values
    - `calculationInterval` 'day' | 'week' | 'month' | 'quarter' | 'year' — The calculation interval used
    - `dateRange` object
      - `start` string, date — Start date (ISO 8601)
      - `end` string, date — End date (ISO 8601)
    - `filters` object — Information about filters that were applied
    - `breakdowns` object, nullable — Breakdown metadata (null if no breakdowns specified)
      - `dimensions` string[] — List of breakdown dimensions used
      - `dimensionCounts` object — Count of unique values per breakdown dimension. Keys match breakdown dimension names.
    - `metric` string, nullable — Metric name (only present for saved metrics, not previews)

## Other responses

- `400` — Bad request - validation error
- `401` — Unauthorized
- `404` — Resource not found
- `500` — Internal Server Error

---

[API](https://skmtc.net/hifibridge/apis/hifi-api.md) · [All operations](https://skmtc.net/hifibridge/apis/hifi-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hifibridge/hifi-api/revisions/74d9e530fbea/schema)