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

# List Billable Metrics

> Retrieve a paginated list of billable metrics with optional filtering and sorting

Retrieves a paginated list of all billable metrics. You can filter and sort the results using query parameters.

## Query Parameters

<ParamField query="page" type="integer" default="1">
  The page number to retrieve (1-indexed).
</ParamField>

<ParamField query="limit" type="integer" default="10">
  The number of metrics to return per page. Must be one of: `5`, `10`, `25`, `50`, or `100`. Values exceeding `100` are capped automatically.
</ParamField>

<ParamField query="filters" type="string">
  A JSON-encoded array of filter objects. Each filter object has the following properties:

  <Expandable title="Filter Object">
    <ParamField body="field" type="string" required>
      The field to filter on. Supported fields:

      | Field               | Operators | Description                                         |
      | ------------------- | --------- | --------------------------------------------------- |
      | `eventName`         | `in`      | The event name that triggers the metric             |
      | `aggregationMethod` | `in`      | The aggregation method (e.g. `sum`, `count`, `max`) |
      | `aggregationField`  | `in`      | The event property being aggregated                 |
      | `tagIds`            | `in`      | Tag IDs associated with the metric                  |
    </ParamField>

    <ParamField body="operator" type="string" required>
      The comparison operator. All metric filter fields support the `in` operator for matching any value in a comma-separated list.
    </ParamField>

    <ParamField body="value" type="string" required>
      The value to match against. Use comma-separated values with the `in` operator.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField query="sort" type="string">
  Sort specification in `field:order` format. Order is either `asc` (ascending) or `desc` (descending).

  Sortable fields: `name`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.alguna.io/metrics?page=1&limit=25" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (with filters and sort) theme={null}
  curl -G "https://api.alguna.io/metrics" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode 'page=1' \
    --data-urlencode 'limit=10' \
    --data-urlencode 'filters=[{"field":"aggregationMethod","operator":"in","value":"sum,count"}]' \
    --data-urlencode 'sort=name:asc'
  ```

  ```javascript Node.js theme={null}
  const metrics = await alguna.metrics.list({
    page: 1,
    limit: 25,
    filters: [
      { field: "aggregationMethod", operator: "in", value: "sum,count" }
    ],
    sort: "name:asc"
  });
  ```
</RequestExample>

## Response

<Snippet file="metric-create-response.mdx" />

<ResponseField name="items" type="array">
  List of billable metric objects.

  <Expandable title="Metric Object">
    <ResponseField name="id" type="string">
      The unique identifier for the metric.
    </ResponseField>

    <ResponseField name="name" type="string">
      The name of the metric.
    </ResponseField>

    <ResponseField name="description" type="string">
      A brief description of what the metric measures.
    </ResponseField>

    <ResponseField name="eventName" type="string">
      The event that triggers the metric.
    </ResponseField>

    <ResponseField name="filters" type="[]object">
      An array of filter groups applied to the metric to narrow down the events counted.

      <Expandable title="Filter Group Properties">
        <ResponseField name="operator" type="string">
          The logical operator (e.g., "and") used to combine the filters within the group.
        </ResponseField>

        <ResponseField name="filters" type="[]object">
          An array of individual filters within the group.

          <Expandable title="Filter Properties">
            <ResponseField name="field" type="string">
              The event property to filter by.
            </ResponseField>

            <ResponseField name="operator" type="string">
              The condition to apply (e.g., "equal").
            </ResponseField>

            <ResponseField name="value" type="string">
              The value that the event property must match.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="aggregation" type="object">
      The aggregation settings that define how the events are calculated to produce the metric value.

      <Expandable title="Aggregation Properties">
        <ResponseField name="method" type="string">
          The aggregation method to apply (e.g., "sum").
        </ResponseField>

        <ResponseField name="field" type="string">
          The event property that is aggregated.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="createdAt" type="datetime">
      The timestamp when the metric was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="datetime">
      The timestamp when the metric was last updated.
    </ResponseField>

    <ResponseField name="organizationID" type="string">
      The unique identifier for the organization associated with the metric.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pageCount" type="integer">
  Total number of pages available based on the current limit.
</ResponseField>

<ResponseField name="limit" type="integer">
  The number of items per page used for this request.
</ResponseField>