Source: https://datafa.st/docs/api-hostnames
Markdown source: https://datafa.st/docs/api-hostnames.md
Description: Get analytics data broken down by hostname/domain.

# Get hostname analytics

`GET https://datafa.st/api/v1/analytics/hostnames`

Retrieve analytics data broken down by hostname. Requires [Bearer Token](/docs/api-introduction) authentication.

## Response

**Success (200 OK):** Returns hostname, visitors, and revenue for each hostname.

```json
{
  "status": "success",
  "data": [
    {
      "hostname": "example.com",
      "visitors": 15240,
      "revenue": 24560
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}
```

## Query parameters

### Optional parameters

- **`fields`** (string): Comma-separated list of fields to return. Valid fields: `hostname`, `visitors`, `revenue`. If not specified, all fields are returned.

- **`startAt`** (string): Start date/time in ISO 8601 format (e.g., 2024-01-01T00:00:00Z or 2024-01-01). If omitted, returns all-time data

- **`endAt`** (string): End date/time in ISO 8601 format. Must be provided together with `startAt` if using custom date range

- **`timezone`** (string): Timezone for data aggregation (e.g., UTC, America/New_York, Europe/Amsterdam). Defaults to your website's timezone if not specified

- **`limit`** (number): Maximum number of results to return (1-1000, default: 100)

- **`offset`** (number): Number of results to skip for pagination (default: 0)

## Filter parameters

You can filter the data using simple, direct query parameters. Pass the parameter name with comma-separated values.

### Location filters

- **`country`** (string): Filter by country name or code (e.g., United States, US)
  - Example: `country=United States,Canada`
- **`region`** (string): Filter by region/state
  - Example: `region=California,New York`
- **`city`** (string): Filter by city name
  - Example: `city=San Francisco,New York`

### Device and browser filters

- **`device`** (string): Filter by device type (desktop, mobile, tablet)
  - Example: `device=mobile,tablet`
- **`browser`** (string): Filter by browser name (e.g., Chrome, Safari, Firefox, Edge)
  - Note: Filtering by Safari automatically includes Mobile Safari
  - Example: `browser=Chrome,Safari`
- **`os`** (string): Filter by operating system (e.g., Mac OS, Windows, iOS, Android)
  - Example: `os=Mac OS,Windows`

### Traffic source filters

- **`referrer`** (string): Filter by referrer domain or popular referrer name (e.g., google.com, Google, Facebook, Direct/None)
  - Supports popular referrer names that get automatically normalized to domains
  - Example: `referrer=google.com,facebook.com`
- **`ref`** (string): Filter by ref URL parameter
  - Example: `ref=twitter,newsletter`
- **`source`** (string): Filter by source URL parameter
  - Example: `source=google,facebook`
- **`via`** (string): Filter by via URL parameter
  - Example: `via=affiliate,partner`

### UTM parameter filters

- **`utm_source`** (string): Filter by UTM source parameter
  - Example: `utm_source=google,facebook`
- **`utm_medium`** (string): Filter by UTM medium parameter (e.g., cpc, email, social)
  - Example: `utm_medium=cpc,email`
- **`utm_campaign`** (string): Filter by UTM campaign parameter
  - Example: `utm_campaign=summer_sale,product_launch`
- **`utm_term`** (string): Filter by UTM term parameter, typically used for keywords
  - Example: `utm_term=keyword1,keyword2`
- **`utm_content`** (string): Filter by UTM content parameter
  - Example: `utm_content=ad_variant_a,ad_variant_b`

### Page and content filters

- **`page`** or **`entry_page`** (string): Filter by page path/URL
  - Example: `page=/pricing,/about`
- **`hostname`** (string): Filter by hostname/domain
  - Example: `hostname=example.com,www.example.com`

### Multiple filter example

```http
GET /api/v1/analytics/hostnames?country=United States,Canada&device=mobile&utm_source=google&page=/pricing
```

See [DataFast filters documentation](/docs/datafast-filters) for more details on using filters in the dashboard.

## Code examples

### Example request

```javascript
const response = await fetch(
  "https://datafa.st/api/v1/analytics/hostnames",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${DATAFAST_API_KEY}`,
    },
  }
);
```

### Success response (200 OK)

```json
{
  "status": "success",
  "data": [
    {
      "hostname": "example.com",
      "visitors": 15240,
      "revenue": 24560
    }
  ],
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 1
  }
}
```