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

# Get goal analytics

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

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

## Response

**Success (200 OK):**

```json
{
  "status": "success",
  "data": [
    {
      "goal": "faq_what_do_i_get",
      "completions": 49730,
      "visitors": 27797
    },
    {
      "goal": "scroll_to_problem",
      "completions": 35100,
      "visitors": 30807
    },
    {
      "goal": "faq_who_is_this_for",
      "completions": 32731,
      "visitors": 19905
    },
    {
      "goal": "faq_tech_stack",
      "completions": 29262,
      "visitors": 18708
    },
    {
      "goal": "faq_refund_policy",
      "completions": 27843,
      "visitors": 16861
    }
  ],
  "pagination": {
    "limit": 5,
    "offset": 0,
    "total": 48
  }
}
```

## Query parameters

### Optional parameters

- **`fields`** (string): Comma-separated list of fields to return. Valid fields: `name`, `completions`, `visitors`. 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/goals?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 (Node.js/Express)

```javascript
// Get all goal data
const response = await fetch(
  "https://datafa.st/api/v1/analytics/goals",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${DATAFAST_API_KEY}`,
      "Content-Type": "application/json",
    },
  }
);

// Get only specific fields
const response2 = await fetch(
  "https://datafa.st/api/v1/analytics/goals?fields=name,completions",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${DATAFAST_API_KEY}`,
      "Content-Type": "application/json",
    },
  }
);
```

### Success response (200 OK)

```json
{
  "status": "success",
  "data": [
    {
      "goal": "faq_what_do_i_get",
      "completions": 49730,
      "visitors": 27797
    },
    {
      "goal": "scroll_to_problem",
      "completions": 35100,
      "visitors": 30807
    },
    {
      "goal": "faq_who_is_this_for",
      "completions": 32731,
      "visitors": 19905
    },
    {
      "goal": "faq_tech_stack",
      "completions": 29262,
      "visitors": 18708
    },
    {
      "goal": "faq_refund_policy",
      "completions": 27843,
      "visitors": 16861
    }
  ],
  "pagination": {
    "limit": 5,
    "offset": 0,
    "total": 48
  }
}
```