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

# Get Website Metrics — GET /api/websites/{id}/metrics

> Retrieve a ranked list of values for a single dimension — top pages, referrers, countries, browsers, events, and UTM sources — sorted by count.

Use this endpoint to get a ranked breakdown of any single dimension tracked by Betterumami. Pass the `type` parameter to select the dimension you want — for example `path` for top pages, `country` for visitor geography, or `utmSource` for campaign sources. The response is an array of `{x, y}` objects sorted from highest to lowest count, making it straightforward to render leaderboard tables or bar charts.

`GET /api/websites/{websiteId}/metrics`

## Request

### Headers

**Authorization** `string` *required*

Bearer token. Pass your API key: `Authorization: Bearer <api-key>`

### Path Parameters

**websiteId** `string` *required*

The unique UUID of the website to query.

### Query Parameters

#### Required

**type** `string` *required*

The dimension to rank. Accepted values: `path`, `entry`, `exit`, `title`, `query`, `hostname`, `referrer`, `domain`, `channel`, `event`, `tag`, `browser`, `os`, `device`, `screen`, `language`, `country`, `region`, `city`, `distinctId`, `utmSource`, `utmMedium`, `utmCampaign`, `utmContent`, `utmTerm`.

#### Date Range

**startAt** `number`

Start of the date range as a Unix timestamp in **milliseconds**.

**endAt** `number`

End of the date range as a Unix timestamp in **milliseconds**.

**startDate** `string`

Start of the date range as an ISO 8601 date or datetime.

**endDate** `string`

End of the date range as an ISO 8601 date or datetime.

**timezone** `string`

IANA time zone for date interpretation, e.g. `Asia/Tokyo`.

**compare** `string`

Comparison period: `prev` or `yoy`.

#### Pagination & Search

**limit** `number`

Maximum number of rows to return. Defaults to server-defined limit.

**offset** `number`

Number of rows to skip before returning results.

**search** `string`

Filter dimension values by a search string.

#### Filters

**path** `string`

Filter by URL path.

**referrer** `string`

Filter by referring URL.

**title** `string`

Filter by page title.

**query** `string`

Filter by URL query string.

**os** `string`

Filter by operating system.

**browser** `string`

Filter by browser name.

**device** `string`

Filter by device category.

**country** `string`

Filter by ISO 3166-1 alpha-2 country code.

**region** `string`

Filter by visitor region.

**city** `string`

Filter by visitor city.

**language** `string`

Filter by browser language.

**event** `string`

Filter by custom event name.

**utmSource** `string`

Filter by UTM source.

**utmMedium** `string`

Filter by UTM medium.

**utmCampaign** `string`

Filter by UTM campaign name.

**utmContent** `string`

Filter by UTM content.

**utmTerm** `string`

Filter by UTM term.

**tag** `string`

Filter by a tag.

**hostname** `string`

Filter by hostname.

**distinctId** `string`

Filter by custom visitor identifier.

**eventType** `integer`

Filter by event type: `1` for pageviews, `2` for custom events.

**excludeBounce** `string`

Set to any non-empty value to exclude single-pageview visits.

**segment** `string`

UUID of a saved segment to apply.

**cohort** `string`

UUID of a saved cohort to filter by.

**match** `string`

Filter combination logic: `all` (AND, default) or `any` (OR).

## Response

**200 – Success**

Returns an array of ranked rows, sorted by `y` (count) in descending order.

**\[].x** `string | null` *required*

The dimension value, e.g. `"/blog/my-post"` for `type=path`, or `"US"` for `type=country`. `null` when the dimension value is unknown.

**\[].y** `number` *required*

The count for this dimension value. For activity dimensions (`path`, `event`, etc.) this is pageviews or event fires. For visitor dimensions (`country`, `browser`, `os`, etc.) this is unique visitors.

**\[].t** `string`

An optional secondary label returned for certain dimension types.

```json 200 Response theme={null}
[
  { "x": "/pricing", "y": 4821 },
  { "x": "/docs/getting-started", "y": 3204 },
  { "x": "/blog/privacy-analytics", "y": 2987 },
  { "x": "/", "y": 2541 },
  { "x": "/features", "y": 1876 },
  { "x": null, "y": 43 }
]
```

## Code Sample

```bash theme={null}
# Top 10 pages by pageviews for the last 30 days
curl -X GET 'https://api.umami.is/v1/websites/b8d3a1f0-1c2d-4e5f-8a9b-0c1d2e3f4a5b/metrics?type=path&startAt=1754784000000&endAt=1757376000000&limit=10' \
  -H 'Authorization: Bearer <api-key>'
```


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