> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Metrics

> List governed metrics with field selection and cursor pagination

# List Metrics

List metrics with optional relationship fields and cursor-based pagination.

## Query Parameters

<ParamField query="limit" type="integer" default="10">
  Maximum number of results to return, from 0 through 1,000,000.
</ParamField>

<ParamField query="before" type="string">
  Cursor for the previous page. Do not combine with `after`.
</ParamField>

<ParamField query="after" type="string">
  Cursor for the next page. Do not combine with `before`.
</ParamField>

<ParamField query="fields" type="string">
  Comma-separated relationship and extension fields to include. See [Supported Fields](#supported-fields).
</ParamField>

<ParamField query="include" type="string" default="non-deleted">
  Include `all`, `deleted`, or `non-deleted` metrics.
</ParamField>

<RequestExample dropdown>
  ```python GET /v1/metrics theme={null}
  from metadata.sdk import configure
  from metadata.sdk.entities import Metrics

  configure(
      host="https://your-org.getcollate.io/api",
      jwt_token="your-jwt-token"
  )

  # Fetch one page with governance relationships.
  page = Metrics.list(
      limit=50,
      fields=["owners", "reviewers", "relatedMetrics", "domains", "dataProducts"]
  )

  for metric in page.entities:
      print(f"{metric.fullyQualifiedName}: {metric.metricType}")

  # Fetch every metric using automatic cursor pagination.
  for metric in Metrics.list_all(batch_size=100):
      print(metric.fullyQualifiedName)
  ```

  ```java GET /v1/metrics theme={null}
  import org.openmetadata.sdk.models.ListParams;

  // client is an initialized OpenMetadataClient.
  var params = new ListParams()
      .setLimit(50)
      .setFields("owners,reviewers,relatedMetrics,domains,dataProducts");

  var page = client.metrics().list(params);
  for (var metric : page.getData()) {
      System.out.println(
          metric.getFullyQualifiedName() + ": " + metric.getMetricType());
  }
  ```

  ```bash GET /v1/metrics theme={null}
  # List the first page.
  curl "{base_url}/api/v1/metrics?limit=50" \
    -H "Authorization: Bearer {access_token}"

  # Include governance relationships.
  curl "{base_url}/api/v1/metrics?fields=owners,reviewers,relatedMetrics,domains,dataProducts&limit=50" \
    -H "Authorization: Bearer {access_token}"

  # Fetch the next page using the cursor from the previous response.
  curl "{base_url}/api/v1/metrics?limit=50&after={after_cursor}" \
    -H "Authorization: Bearer {access_token}"
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "data": [
      {
        "id": "b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10",
        "name": "customer_retention_rate",
        "displayName": "Customer Retention Rate",
        "fullyQualifiedName": "customer_retention_rate",
        "description": "Percentage of customers retained during the month.",
        "metricExpression": {
          "language": "SQL",
          "code": "retained_customers * 100.0 / NULLIF(total_customers, 0)"
        },
        "metricType": "RATIO",
        "unitOfMeasurement": "PERCENTAGE",
        "granularity": "MONTH",
        "version": 0.1,
        "updatedAt": 1787760000000,
        "updatedBy": "admin",
        "href": "https://your-org.getcollate.io/api/v1/metrics/b8a9d6e4-2f7c-4f3a-9c1e-6d5b8a7f2e10",
        "deleted": false,
        "owners": [],
        "reviewers": [],
        "relatedMetrics": [],
        "domains": [],
        "dataProducts": []
      }
    ],
    "paging": {
      "after": "eyJmdWxseVF1YWxpZmllZE5hbWUiOiJjdXN0b21lcl9yZXRlbnRpb25fcmF0ZSJ9",
      "total": 24
    }
  }
  ```
</ResponseExample>

***

## Returns

Returns a `data` array and a `paging` object. Pass `paging.after` or `paging.before` to retrieve an adjacent page.

## Supported Fields

| Field | Description |
| - | - |
| `owners` | Users or teams that own the metric |
| `reviewers` | Users or teams responsible for reviewing the metric |
| `relatedMetrics` | Metrics related to this metric |
| `followers` | Users following the metric |
| `tags` | Classification and glossary labels |
| `extension` | Custom property values |
| `domains` | Domains the metric belongs to |
| `dataProducts` | Data products that include the metric |

***

## Error Handling

| Code | Error Type | Description |
| - | - | - |
| `400` | `BAD_REQUEST` | Invalid cursor, limit, field, or include value |
| `401` | `UNAUTHORIZED` | Invalid or missing authentication token |
| `403` | `FORBIDDEN` | User lacks permission to list metrics |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.