---
title: Get goal statistics
description: Retrieve dashboard-ready totals, comparison, and time series for any Clics conversion goal.
---

Use `clics.goals.getGoalStats` for the same conversion metrics shown for a selected goal in Dashboard. It works with page, event, outbound-link, and scroll-depth goals.

## What you need

| Field | Required | Description |
| --- | --- | --- |
| `goalId` | **Yes** | ID returned by `createGoal` or `listGoals` |
| `dateRange` | No | One of the nine presets; defaults to `last7days` |
| `start` and `end` | No | Custom `yyyy-MM-dd` or ISO8601 range; always pass both together |
| `domain` | No | One hostname, or `localhost` for development traffic |
| `timezone` | No | IANA timezone used for calendar boundaries; defaults to `UTC` |
| `referrerAiProvider` | No | `chatgpt`, `claude`, `gemini`, `perplexity`, or `copilot` |

Presets: `last24h`, `last7days`, `last30days`, `last3months`, `last12months`, `monthToDate`, `quarterToDate`, `yearToDate`, and `allTime`.

When `start` and `end` are both provided, they take precedence over `dateRange`.

## Example

```typescript
const stats = await clics.goals.getGoalStats({
  goalId: "goal_123",
  dateRange: "last30days",
  timezone: "UTC",
});

console.log(stats.totals.conversionRate);
console.log(stats.comparison.changePercent.conversions);
```

Custom range for one AI referrer:

```typescript
const stats = await clics.goals.getGoalStats({
  goalId: "goal_123",
  start: "2026-07-01",
  end: "2026-07-31",
  timezone: "Europe/London",
  referrerAiProvider: "chatgpt",
});
```

## What it returns

The response always has `totals`, `comparison`, `series`, and `meta`.

### `totals`

| Field | Type | Meaning |
| --- | --- | --- |
| `convertingVisitors` | `number` | Unique visitors who completed the goal |
| `conversions` | `number` | Total goal completions; one visitor can contribute more than one |
| `siteVisitors` | `number` | Unique visitors in the same project, period, domain, and AI-provider scope |
| `conversionRate` | `number` | Percentage of converting visitors out of `siteVisitors` |

### `comparison`

`comparison.previous` repeats all four totals for the immediately preceding equivalent period. `comparison.changePercent` contains the percentage change for `convertingVisitors`, `conversions`, and `conversionRate`.

### `series`

Each time bucket has:

| Field | Type | Meaning |
| --- | --- | --- |
| `date` | `string` | Bucket date/time label in the selected timezone |
| `convertingVisitors` | `number` | Unique visitors converting in that bucket |
| `conversions` | `number` | Goal completions in that bucket |
| `siteVisitors` | `number` | Site visitors in that bucket |
| `conversionRate` | `number` | Conversion percentage for that bucket |

`meta.timezone` is the IANA timezone actually applied to calendar boundaries and the series.

## Errors and next steps

- A missing goal returns `404`.
- Passing only `start` or only `end` returns `400`.
- API access requires a paid plan; an unavailable plan returns `403` with `UPGRADE_REQUIRED`.

Use [getGoal](/sdk/goals/getgoal) to inspect the rule first, or [queryStats](/sdk/stats/querystats) for broader site analytics.