---
title: "Get asset metrics breakdown"
method: POST
path: "/v2/assets/{asset_id}/metrics-breakdown"
tags: ["Assets"]
---

# Get asset metrics breakdown

`POST /v2/assets/{asset_id}/metrics-breakdown`

## Request

- Base URL: `https://api.tokenterminal.com`
- URL: `https://api.tokenterminal.com/v2/assets/{asset_id}/metrics-breakdown`
- Auth: HTTP bearer

Use this endpoint to retrieve aggregated breakdown data for asset metrics across different dimensions (projects, chains, market sectors, etc.).

If an empty `metric_ids` array is provided, it defaults to `['asset_price']`.

## Path parameters

- `asset_id` string, required

## Request body

- object
  - `metric_ids` string[], required: List of metrics to include according to asset metric availability. Allows you to select one or more of the metrics available for a specific asset. If an empty array is provided, it defaults to `['asset_price']`.
  - `group_by` 'assets' | 'projects' | 'product' | 'chains' | 'market-sector' | 'reference-asset' | 'chain-asset' | 'chain-project' | 'product+chain' | 'venue' | 'asset+venue' | 'venue+chain' | 'market-sector+venue', required: Dimension to group the breakdown by. Available options: `assets`, `projects`, `product`, `chains`, `market-sector`, `reference-asset`, `chain-asset`, `chain-project`, `product+chain`, `venue`, `asset+venue`, `venue+chain`, `market-sector+venue`. `reference-asset` groups by the price reference the underlying assets track (for example `Credit fund`, `S&P 500`), and returns a `reference_asset` label on each row. Assets that track no reference asset are excluded from that breakdown. The venue composites (`asset+venue`, `venue+chain`, `market-sector+venue`) combine `venue` with a second dimension and are only meaningful for the venue-scoped metrics (`asset_tvl`, `asset_trading_volume`, `asset_notional_trading_volume`).
  - `interval` '24h' | '7d' | '30d' | '90d' | '180d' | '365d' | '1095d' | '1825d' | 'ytd' | 'max': Length of the aggregation window. Defaults to `7d`. The window ends at the latest available date, or the day before `end` if given. Ignored when both `start` and `end` are given; the window is then the date range `[start, end)`.
  - `data_ids` string[]: List of project data IDs to filter by. Allows you to select one or more projects. When including multiple projects, separate each one with a comma.
  - `product_ids` string[]: List of product IDs to filter by. Allows you to select one or more products. When including multiple products, separate each one with a comma.
  - `asset_ids` string[]: List of asset IDs to filter by. Allows you to select one or more assets. When including multiple assets, separate each one with a comma.
  - `chain_ids` string[]: List of chain IDs to filter by. Allows you to select one or more chains. When including multiple chains, separate each one with a comma.
  - `market_sector_ids` string[]: List of market sector IDs to filter by. Allows you to select one or more market sectors. When including multiple market sectors, separate each one with a comma. The full list of available market sectors can be retrieved from the `/v2/market-sectors` endpoint.
  - `reference_asset_ids` string[]: List of reference asset IDs to filter by (for example `creditfund`, `sp500`). The filter counterpart of `group_by: reference-asset`: use it to restrict the breakdown to assets tracking a specific price reference. Assets that track no reference asset are excluded. The full list of available reference assets can be retrieved from the `/v2/reference-assets` endpoint.
  - `venues` object[]: List of venues (the protocol and product a metric was earned on) to filter by. Only applies to venue-scoped metrics (`asset_tvl`, `asset_trading_volume`, `asset_notional_trading_volume`) -- distinct from `data_ids`/`product_ids`, which filter by the asset's own issuer or manager. Each entry must specify both `data_id` and `product_id` together -- a `product_id` can never be given without its matching `data_id`.
    - `data_id` string, required
    - `product_id` string, required
  - `includeSelf` boolean: Include the asset itself in the breakdown results. If not specified, defaults to `false`.
  - `start` string, date: First date of the aggregation window, inclusive (`YYYY-MM-DD`). With `end`, the window is the half-open range `[start, end)` and `interval` is ignored. Without `end`, the window spans `interval` days starting on `start`.
  - `end` string, date: End of the aggregation window, exclusive (`YYYY-MM-DD`). Data for this date is not included; must be after `start`, otherwise the request is rejected with a 400. For a full calendar month use the first day of the next month, e.g. `start=2026-08-01`, `end=2026-09-01`. Without `start`, the window spans `interval` days ending the day before `end`. If omitted entirely, the window ends at the latest date for which data is available. If the day before `end` has no data yet, the window ends at the latest available date before it.
  - `ignore_threshold` boolean: Ignore metric thresholds when calculating breakdowns. If not specified, defaults to `false`.

## Response `200`

OK

- object
  - `data` object[]
    - `asset_id` string, nullable: Asset ID (present when group_by includes assets).
    - `data_id` string, nullable: Project data ID (present when group_by includes projects).
    - `product_id` string, nullable: Product ID (present when group_by includes products).
    - `chain_id` string, nullable: Chain ID (present when group_by includes chains).
    - `market_sector_id` string, nullable: Market sector ID (present when group_by includes market sectors).
    - `reference_asset_id` string, nullable: Reference asset ID, for example `creditfund` (present when group_by is `reference-asset`). Prefer this over `reference_asset` as the stable key -- it is the value the `reference_asset_ids` filter accepts.
    - `reference_asset` string, nullable: Reference asset display name, for example `Credit fund` (present when group_by is `reference-asset`). Free-form registry text that can change; use `reference_asset_id` to identify the row.
    - `venue_data_id` string, nullable: Venue project data ID -- the protocol a value was earned on (present when group_by is venue). Only non-null for venue-scoped metrics (`asset_tvl`, `asset_trading_volume`, `asset_notional_trading_volume`).
    - `venue_product_id` string, nullable: Venue product ID, paired with venue_data_id.
    - `metrics` object: Map of metric IDs to their breakdown data.
  - `errors` union[]
    - union
      - object
        - `code` 'NOT_FOUND', required: Error code indicating the entity was not found
        - `field` 'project_ids' | 'metric_ids' | 'chain_ids' | 'product_ids' | 'market_sector_ids', required: The request parameter field that contained the invalid value
        - `value` string, required: The invalid ID value that was not found
      - object
        - `code` 'METRIC_NOT_AVAILABLE', required: Error code indicating the metric is not available for the specified project
        - `project_id` string, required: The project ID that does not have the metric available
        - `metric_id` string, required: The metric ID that is not available for the project

## Other responses

- `400`: Bad Request

## Changes

- **2026-09-17** `b8a5000df3e2`: 11 info
  - added the new optional request property `reference_asset_ids`
  - added the new optional request property `venues`
  - added the new `asset+venue` enum value to the request property `group_by`
  - added the new `market-sector+venue` enum value to the request property `group_by`
  - …7 more
- **2026-09-10** `4cf6f1da3bf9`: 5 info
  - the request property `interval` became optional
  - the `interval` request property default value `7d` was added
  - added the new `1095d` enum value to the request property `interval`
  - added the new `1825d` enum value to the request property `interval`
  - …1 more

[Operation history](https://skmtc.dev/tokenterminal/apis/token-terminal-api/changes/v2/assets/:asset_id/metrics-breakdown/post.md)

---

[API](https://skmtc.dev/tokenterminal/apis/token-terminal-api.md) - [All operations](https://skmtc.dev/tokenterminal/apis/token-terminal-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tokenterminal/apis/token-terminal-api/revisions/35b0e064e128?raw)