Goals

List goals for a website

curl -X GET https://analytics.example.com/api/websites/site_abc123/goals \
  -H "Authorization: Bearer spk_selfhosted_abc123..."

Path Parameters

website_id

string

required

Website ID (format: site_*)

Response (200 OK)

data

array

Array of goal objects

Show Goal object

string

required

Goal ID (format: goal_ + 10 alphanumeric chars)

website_id

string

required

Parent website ID

name

string

required

Goal display name (1-100 characters)

goal_type

string

required

Type of goal: event or pageview

match_value

string

required

Value to match against (1-500 characters)

For event goals: event name (e.g., signup_click)
For pageview goals: URL path (e.g., /thank-you)

match_operator

string

required

How to match: equals, starts_with, ends_with, or contains

value_mode

string

required

How to track value: none, fixed, or event_property

fixed_value

number | null

Fixed numeric value (required when value_mode=fixed, must be non-negative)

value_property_key

string | null

Event property key to extract value from (required when value_mode=event_property)

currency

string

required

Currency code (1-8 characters, default USD)

created_at

string

required

ISO 8601 timestamp

updated_at

string

required

ISO 8601 timestamp

Response Example

{
  "data": [
    {
      "id": "goal_abc123",
      "website_id": "site_xyz789",
      "name": "Pro Signup",
      "goal_type": "event",
      "match_value": "signup_click",
      "match_operator": "equals",
      "value_mode": "fixed",
      "fixed_value": 99.0,
      "value_property_key": null,
      "currency": "USD",
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-01T10:00:00Z"
    }
  ]
}

Create a goal

Maximum of 50 goals per website. Creating more will return a 422 Unprocessable Entity error.

curl -X POST https://analytics.example.com/api/websites/site_abc123/goals \
  -H "Authorization: Bearer spk_selfhosted_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Signup",
    "goal_type": "event",
    "match_value": "signup_click",
    "match_operator": "equals",
    "value_mode": "fixed",
    "fixed_value": 99.0,
    "currency": "USD"
  }'

Path Parameters

website_id

string

required

Website ID (format: site_*)

Request Body

name

string

required

Goal display name (1-100 characters, must not be empty or whitespace-only)Must be unique per website — duplicate names return a 422 error.

goal_type

string

required

Type of goal:

event — Match custom event names (tracked via window.sparklytics.track('event_name'))
pageview — Match page URLs

match_value

string

required

Value to match (1-500 characters)

For event: event name (e.g., signup_click)
For pageview: URL path (e.g., /thank-you, /checkout)

match_operator

string

default:"equals"

How to match the value:

equals — Exact match (default)
starts_with — Value starts with match_value
ends_with — Value ends with match_value
contains — Value contains match_value

value_mode

string

default:"none"

How to track goal value:

none — No value tracking (default)
fixed — Use a fixed numeric value (requires fixed_value)
event_property — Extract value from event property (requires value_property_key)

fixed_value

number

Fixed numeric value (required when value_mode=fixed, must be non-negative)Example: 99.0 for a $99 conversion

value_property_key

string

Event property key to extract value from (required when value_mode=event_property)Example: If you track window.sparklytics.track('purchase', { amount: 49.99 }), use "amount"

currency

string

default:"USD"

Currency code (1-8 characters, e.g., USD, EUR, GBP)

Response (201 Created)

data

object

Created goal object (same structure as in list endpoint)

Response Example

{
  "data": {
    "id": "goal_abc123",
    "website_id": "site_xyz789",
    "name": "Pro Signup",
    "goal_type": "event",
    "match_value": "signup_click",
    "match_operator": "equals",
    "value_mode": "fixed",
    "fixed_value": 99.0,
    "value_property_key": null,
    "currency": "USD",
    "created_at": "2026-03-01T10:00:00Z",
    "updated_at": "2026-03-01T10:00:00Z"
  }
}

Error Responses

422 Unprocessable Entity

Validation errors:Duplicate name:

{
  "error": {
    "code": "duplicate_name",
    "message": "goal name already exists for this website",
    "field": "name"
  }
}

Limit exceeded:

{
  "error": {
    "code": "limit_exceeded",
    "message": "maximum of 50 goals per website reached",
    "field": "goals"
  }
}

Invalid name:

{
  "error": {
    "code": "validation_error",
    "message": "name must not be empty",
    "field": "name"
  }
}

Missing fixed_value:

{
  "error": {
    "code": "validation_error",
    "message": "fixed_value is required when value_mode=fixed",
    "field": "fixed_value"
  }
}

404 Not Found

Website does not exist

Update a goal

curl -X PUT https://analytics.example.com/api/websites/site_abc123/goals/goal_xyz789 \
  -H "Authorization: Bearer spk_selfhosted_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro Signup (Updated)",
    "fixed_value": 149.0
  }'

Path Parameters

website_id

string

required

Website ID (format: site_*)

goal_id

string

required

Goal ID (format: goal_*)

Request Body

All fields are optional. Only provided fields will be updated.

name

string

New goal name (must be unique per website, 1-100 characters)

match_value

string

New match value (1-500 characters)

match_operator

string

New match operator: equals, starts_with, ends_with, or contains

value_mode

string

New value mode: none, fixed, or event_property

fixed_value

number

New fixed value (must be non-negative)

value_property_key

string

New event property key

currency

string

New currency code (1-8 characters)

Response (200 OK)

data

object

Updated goal object (same structure as in list endpoint)

Error Responses

422 Unprocessable Entity

Validation errors (same as create endpoint)

404 Not Found

Website or goal does not exist

Delete a goal

This permanently deletes the goal. Historical conversion data is preserved but will no longer be associated with this goal definition.

curl -X DELETE https://analytics.example.com/api/websites/site_abc123/goals/goal_xyz789 \
  -H "Authorization: Bearer spk_selfhosted_abc123..."

Path Parameters

website_id

string

required

Website ID (format: site_*)

goal_id

string

required

Goal ID (format: goal_*)

Response (204 No Content)

Empty response body on successful deletion.

Error Responses

404 Not Found

Website or goal does not exist

Get goal statistics

Returns conversion metrics for a specific goal over a date range.

curl -X GET "https://analytics.example.com/api/websites/site_abc123/goals/goal_xyz789/stats?start_date=2026-03-01&end_date=2026-03-07" \
  -H "Authorization: Bearer spk_selfhosted_abc123..."

Path Parameters

website_id

string

required

Website ID (format: site_*)

goal_id

string

required

Goal ID (format: goal_*)

Query Parameters

start_date

string

default:"6 days ago"

Start date in YYYY-MM-DD format (defaults to 6 days before end_date)

end_date

string

default:"today"

End date in YYYY-MM-DD format (defaults to today)

timezone

string

IANA timezone for date range calculation (defaults to website’s timezone)

filter_country

string

Filter by ISO country code (e.g., US, GB)

filter_page

string

Filter by page URL path

filter_referrer

string

Filter by referrer domain

filter_browser

string

Filter by browser name (e.g., Chrome, Safari)

filter_os

string

Filter by operating system (e.g., macOS, Windows)

filter_device

string

Filter by device type: desktop, mobile, or tablet

filter_language

string

Filter by browser language (e.g., en-US)

filter_utm_source

string

Filter by UTM source parameter

filter_utm_medium

string

Filter by UTM medium parameter

filter_utm_campaign

string

Filter by UTM campaign parameter

filter_region

string

Filter by region/state (e.g., California, TX)

filter_city

string

Filter by city name

filter_hostname

string

Filter by hostname (useful for multi-domain tracking)

include_bots

boolean

Include bot traffic (defaults to website’s bot policy setting)

Response (200 OK)

data

object

Show Goal statistics

goal_id

string

required

Goal ID

conversions

integer

required

Total number of conversions in date range

converting_sessions

integer

required

Number of unique sessions that converted

total_sessions

integer

required

Total number of sessions in date range

conversion_rate

number

required

Conversion rate (converting_sessions / total_sessions)

prev_conversions

integer | null

Conversions in previous period (for comparison)

prev_conversion_rate

number | null

Conversion rate in previous period

trend_pct

number | null

Percentage change from previous period

Response Example

{
  "data": {
    "goal_id": "goal_abc123",
    "conversions": 42,
    "converting_sessions": 38,
    "total_sessions": 1250,
    "conversion_rate": 0.0304,
    "prev_conversions": 35,
    "prev_conversion_rate": 0.0287,
    "trend_pct": 5.92
  }
}

Error Responses

404 Not Found

Website or goal does not exist

Goal Types

Event Goals

Track custom JavaScript events triggered by user actions. Example: Track signup button clicks

{
  "name": "Signup Clicks",
  "goal_type": "event",
  "match_value": "signup_click",
  "match_operator": "equals"
}

Trigger in your app:

window.sparklytics.track('signup_click', { plan: 'pro' })

Pageview Goals

Track visits to specific pages (e.g., thank-you pages, checkout completion). Example: Track checkout completions

{
  "name": "Checkout Complete",
  "goal_type": "pageview",
  "match_value": "/checkout/success",
  "match_operator": "equals"
}

Converts automatically when users visit /checkout/success.

Value Tracking

Fixed Value

Assign a fixed monetary value to each conversion.

{
  "name": "Pro Plan Signup",
  "goal_type": "event",
  "match_value": "signup_pro",
  "value_mode": "fixed",
  "fixed_value": 99.0,
  "currency": "USD"
}

Event Property Value

Extract value from event data (useful for dynamic pricing).

{
  "name": "Purchase",
  "goal_type": "event",
  "match_value": "purchase",
  "value_mode": "event_property",
  "value_property_key": "amount",
  "currency": "USD"
}

Trigger with value:

window.sparklytics.track('purchase', { amount: 49.99 })

Sparklytics extracts 49.99 from the amount property.

Overview

Event Collection

Analytics

Website Management

List goals for a website

Path Parameters

Response (200 OK)

Response Example

Create a goal

Path Parameters

Request Body

Response (201 Created)

Response Example

Error Responses

Update a goal

Path Parameters

Request Body

Response (200 OK)

Error Responses

Delete a goal

Path Parameters

Response (204 No Content)

Error Responses

Get goal statistics

Path Parameters

Query Parameters

Response (200 OK)

Response Example

Error Responses

Goal Types

Event Goals

Pageview Goals

Value Tracking

Fixed Value

Event Property Value

Build docs developers (and LLMs) love

Overview

Event Collection

Analytics

Website Management

​List goals for a website

​Path Parameters

​Response (200 OK)

​Response Example

​Create a goal

​Path Parameters

​Request Body

​Response (201 Created)

​Response Example

​Error Responses

​Update a goal

​Path Parameters

​Request Body

​Response (200 OK)

​Error Responses

​Delete a goal

​Path Parameters

​Response (204 No Content)

​Error Responses

​Get goal statistics

​Path Parameters

​Query Parameters

​Response (200 OK)

​Response Example

​Error Responses

​Goal Types

​Event Goals

​Pageview Goals

​Value Tracking

​Fixed Value

​Event Property Value

Build docs developers (and LLMs) love

List goals for a website

Path Parameters

Response (200 OK)

Response Example

Create a goal

Path Parameters

Request Body

Response (201 Created)

Response Example

Error Responses

Update a goal

Path Parameters

Request Body

Response (200 OK)

Error Responses

Delete a goal

Path Parameters

Response (204 No Content)

Error Responses

Get goal statistics

Path Parameters

Query Parameters

Response (200 OK)

Response Example

Error Responses

Goal Types

Event Goals

Pageview Goals

Value Tracking

Fixed Value

Event Property Value