Get goal statistics

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

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:

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.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 to inspect the rule first, or queryStats for broader site analytics.