API

This document describes the API endpoints used to interact with Pirsch. The easiest way to get started is to use one of the client SDKs. If you're looking for how to integrate Pirsch into your backend to collect traffic, please see the server-side integration.

If you're just getting started, we recommend reading the API guide.

INFO

Note that the examples do not necessarily show correct data. IDs from a request may not match the response. You should also be careful not to confuse IDs in their context. Fields are often just called id, but they represent different objects.

Getting an Access Token

In order to make requests to the API, you must first obtain an access token or use an access key (write-only). The token must be sent with each request in the Authorisation header in the format Bearer <token>. If you receive a status code of 401 (unauthorized), you must create a new token and try again. The `expires_at' timezone is set to UTC.

The examples for the other endpoints in this document omit the header.

POST https://api.pirsch.io/api/v1/token

EXAMPLE REQUEST

{
    "client_id": "<client_id>",
    "client_secret": "<client_secret>"
}

EXAMPLE RESPONSE

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
    "expires_at": "2020-12-12T00:11:39.903607271Z"
}

Sending Page Views

This endpoint is used to send page views to Pirsch. It requires you to send information about the request made by the client. How you get this information depends on the programming language and framework you're using. The example shows which fields are required and which are optional. We recommend sending all of them to make the results as accurate as possible.

POST https://api.pirsch.io/api/v1/hit

EXAMPLE REQUEST

{
    "url":                          "https://example.com/full/url?including=parameters",
    "ip":                           "123.456.789.0",
    "dnt":                          "DNT header (optional)",
    "user_agent":                   "User-Agent header",
    "accept_language":              "Accept-Language header (optional)",
    "sec_ch_ua":                    "Sec-CH-UA header (optional)",
	"sec_ch_ua_mobile":             "Sec-CH-UA-Mobile header (optional)",
	"sec_ch_ua_platform":           "Sec-CH-UA-Platform header (optional)",
	"sec_ch_ua_platform_version":   "Sec-CH-UA-Platform-Version header (optional)",
	"sec_ch_width":                 "Sec-CH-Width header (optional)",
    "sec_ch_viewport_width":        "Sec-CH-Viewport-Width header (optional)",
    "title":                        "Page title (optional)",
    "referrer" :                    "Referer header (optional)",
    "screen_width":                 1920,
    "screen_height":                1080,
    "tags": {
        "author": "John",
        "post": "My first blogpost"
    }
}

One small tweak you can make is to check the DNT (Do Not Track) header before sending the request. Check if the header is set to 1, if true you can ignore the request, otherwise send it.

It's possible to send multiple page views at once. If you use the batch endpoint, make sure the page views are in order, otherwise they throw off your statistics. This works well for sites that run on a single server where you can buffer page views.

POST https://api.pirsch.io/api/v1/hit/batch

EXAMPLE REQUEST

[
    {
        // Same parameters as for singe page views, plus the time the request was made to your server.
        "time": "2023-01-02T14:15:32Z"
    },
    // ...
]

Sending Events

This endpoint is used to send events to Pirsch. It requires you to send information about the request made by the client. How you get this depends on the programming language and framework you're using. The example shows which fields are required and which are optional. We recommend sending all of them to make the results as accurate as possible.

POST https://api.pirsch.io/api/v1/event

INFO

Fields with underscores are comments.

EXAMPLE REQUEST

{
    "event_name":       "Button Clicked",
    "_duration":        "event_duration is an optional number of seconds.",
    "event_duration":   42,
    "_metadata":        "event_meta is a single dimension object of scalar values (strings, numbers, and booleans).",
    "event_meta": {
        "key":             "value",
        "metadata fields": "are optional"
    },
    "_hit":                         "The fields below are the same as for hits.",
    "url":                          "https://example.com/full/url?including=parameters",
    "ip":                           "123.456.789.0",
    "dnt":                          "DNT header (optional)",
    "user_agent":                   "User-Agent header",
    "accept_language":              "Accept-Language header (optional)",
    "sec_ch_ua":                    "Sec-CH-UA header (optional)",
	"sec_ch_ua_mobile":             "Sec-CH-UA-Mobile header (optional)",
	"sec_ch_ua_platform":           "Sec-CH-UA-Platform header (optional)",
	"sec_ch_ua_platform_version":   "Sec-CH-UA-Platform-Version header (optional)",
	"sec_ch_width":                 "Sec-CH-Width header (optional)",
    "sec_ch_viewport_width":        "Sec-CH-Viewport-Width header (optional)",
    "title":                        "Page title (optional)",
    "referrer" :                    "Referer header (optional)",
    "screen_width":                 1920,
    "screen_height":                1080
}

It's possible to send multiple events at once. If you use the batch endpoint, make sure the events are in order or they throw off your statistics. This works well for sites that run on a single server where you can buffer events.

POST https://api.pirsch.io/api/v1/event/batch

EXAMPLE REQUEST

[
    {
        // Same parameters as for singe event, plus the time the request was made to your server.
        "time": "2023-01-02T14:15:32Z"
    },
    // ...
]

Keeping Sessions Alive

This endpoint is used to manually keep sessions alive. A session is normally reset if no request (hit or event) is sent within a 30 minute timeframe. This feature can be used to extend a session indefinitely. It's not recommended to use this for regular websites, but can be useful for tracking applications or other custom software.

POST https://api.pirsch.io/api/v1/session

EXAMPLE REQUEST

{
    "ip":                           "123.456.789.0",
    "dnt":                          "DNT header (optional)",
    "user_agent":                   "User-Agent header",
    "sec_ch_ua":                    "Sec-CH-UA header (optional)",
	"sec_ch_ua_mobile":             "Sec-CH-UA-Mobile header (optional)",
	"sec_ch_ua_platform":           "Sec-CH-UA-Platform header (optional)",
	"sec_ch_ua_platform_version":   "Sec-CH-UA-Platform-Version header (optional)",
	"sec_ch_width":                 "Sec-CH-Width header (optional)",
    "sec_ch_viewport_width":        "Sec-CH-Viewport-Width header (optional)"
}

It's possible to send multiple requests at once. If you use the batch endpoint, make sure the updates are in order or they throw off your statistics. This works well for sites that run on a single server where you can buffer requests.

POST https://api.pirsch.io/api/v1/session/batch

EXAMPLE REQUEST

[
    {
        // Same parameters as for a singe update, plus the time the request was made to your server.
        "time": "2023-01-02T14:15:32Z"
    },
    // ...
]

Statistics

The following endpoints can be used to read statistics from Pirsch. To receive data, you must set the filter. It is skipped in the sample requests for brevity.

Filter

The following list contains all possible filter options. Only the required fields need to be set when making a request. Set the fields using URL query parameters, such as ?from=2021-05-08&to=2021-05-15&language=en.

FILTER OPTIONS

Parameter	Required	Example	Format/Description
id	yes	A5kgYzK14m	The domain ID. Use the list endpoint to get the domain ID for the client.
from	yes	2021-05-08	YYYY-MM-DD
to	yes	2021-05-15	YYYY-MM-DD
from_time	no	12:34	Sets the start time to group results by minute in the format of HH:MM. This only applies if the start and end date (to and from) are equal.
to_time	no	15:07	Sets the end time to group results by minute in the format of HH:MM. This only applies if the start and end date (to and from) are equal.
tz	no	Europe/Berlin	The time zone. If not set, the default time zone for the dashboard is used.
start	no	600	Queries data for the past seconds (10 minutes in this example). The date range filters is ignored if set. The maximum is one hour (3600 seconds).
scale	no	week	The scale to group results. Can either be day (default), week, month, or year.
path	no	/home	The page path.
entry_path	no	/home	The entry page path.
exit_path	no	/yte	The exit page path.
pattern	no	(?i)^\/path/[^\/]+$	A regular expression to filter and group pages.
event	no	Button clicked	The name of an event to filter for.
event_meta_key	no	Clicks	The event meta key to filter for. This field is used to break down a single event.
meta_(key)	no	meta_key0=value0&meta_key1=value1	The event metadata key and values to filter for. Multiple keys can be set by prefixing them using meta_ and appending them to the URL. Only events with all key-value pairs are returned.
language	no	en	ISO-639-1 language code, like en for English.
country	no	jp	ISO-3166 Alpha-2 country code, like jp for Japan.
city	no	London	Name of a city.
referrer	no	https://referring-website.com/	The referrer, usually a URL or name (note that the Pirsch dashboard does trim the protocol).
referrer_name	no	referring-website.com	The referrer name, usually the hostname.
os	no	Windows	The operating system.
browser	no	Firefox	The browser.
platform	no	desktop	The platform, desktop, mobile, or unknown (not set).
screen_class	no	XXL	The screen class, XXL, XL, L, M, S.
utm_source	no	Newsletter	The UTM source.
utm_medium	no	Email	The UTM medium.
utm_campaign	no	Summer Sale	The UTM campaign.
utm_content	no	Header	The UTM content.
utm_term	no	search terms	The UTM term.
custom_metric_type	no	integer	The custom metric type used to aggregate statistics. This will be used to parse the custom_metric_key event metadata key. It can be either float or integer.
custom_metric_key	no	integer	The custom metric key used to aggregate statistics. This will be used to parse the an event metadata value. Used in combination with the custom_metric_type.
tag	no	author	The tag key to filter for. This field is used to break down a single tag.
tag_(key)	no	tag_key0=value0&tag_key1=value1	The tag key and values to filter for. Multiple keys can be set by prefixing them using tag_ and appending them to the URL. Only results with all key-value pairs are returned.
visitor_id	no	1234...	Sets the visitor ID to return details for a single session. The session_id must also be set.
session_id	no	1234...	Sets the session ID to return details for a single session. The visitor_id must also be set.
offset	no	0	Sets the offset for the result set.
limit	no	20	Limits the number of results, note that this is hard limited to 100.
include_avg_time_on_page	no	true	Set to true, to include the average time on page when reading page statistics.
sort	no	visitors	Sort results by given field. This is only available for pages, entry/exit pages, referrers, UTM statistics, conversion goals, events, demographics, and device statistics.
direction	no	desc	Sort results in ascending (asc) or descending (desc) order. This is only available for pages, entry/exit pages, referrers, UTM statistics, conversion goals, events, demographics, and device statistics.
search	no	/home	Search the primary field for given string (contains). For pages this is the path, for browsers the browser name, and so on. This is only available for pages, entry/exit pages, referrers, UTM statistics, conversion goals, events, demographics, and device statistics.

Filter Options

The following endpoints return available filtering options for a time period. For brevity, only one example request and response is given.

FILTER OPTIONS

GET /api/v1/statistics/options/referrer/name
GET /api/v1/statistics/options/page
GET /api/v1/statistics/options/referrer
GET /api/v1/statistics/options/event
GET /api/v1/statistics/options/country
GET /api/v1/statistics/options/city
GET /api/v1/statistics/options/language
GET /api/v1/statistics/options/metadata
GET /api/v1/statistics/options/utm/source
GET /api/v1/statistics/options/utm/medium
GET /api/v1/statistics/options/utm/campaign
GET /api/v1/statistics/options/utm/content
GET /api/v1/statistics/options/utm/term
GET /api/v1/statistics/options/tag
GET /api/v1/statistics/options/tag/value

/api/v1/statistics/options/tag/value requires exactly one tag to be set in the filter.

It's possible to use an access code by setting the access query parameter.

GET /api/v1/statistics/options/page?id=A5kgYzK14m&from=2022-02-01&to=2022-03-27

EXAMPLE RESPONSE

[
    "/",
    "/some/path",
    "/other/path",
    // ...
]

Overview

This endpoint returns basic statistics and the number of members for given domain ID. The results are cached.

GET /api/v1/statistics/overview?id=A5kgYzK14m

EXAMPLE RESPONSE

{
    "visitors": 52,
    "views": 102,
    "visitor_growth": 0.02,
    "views_growth": 0.23,
    "visitors_time_series": [
        {
            "day": "2024-04-10T00:00:00Z",
            "visitors": 42,
            "views": 57,
            "sessions": 48,
            "bounces": 22,
            "bounce_rate": 0.5312,
            "cr": 0,
            "custom_metric_avg": 0,
            "custom_metric_total": 0
        },
        // ...
    ],
    "member": 4
}

Session Duration

GET /api/v1/statistics/duration/session

EXAMPLE RESPONSE

Which time component is set depends on the scale filter. Setting it to day (default) sets the day field. Otherwise the corresponding field will be set.

[
    {
        "day": "2021-05-12T00:00:00Z",
        "week": null,
        "month": null,
        "year": null,
        "average_time_spent_seconds": 42
    },
    // ...
]

Time on Page

GET /api/v1/statistics/duration/page

EXAMPLE RESPONSE

Which time component is set depends on the scale filter. Setting it to day (default) sets the day field. Otherwise the corresponding field is set.

[
    {
        "day": "2021-05-12T00:00:00Z",
        "week": null,
        "month": null,
        "year": null,
        "path" "/home",
        "average_time_spent_seconds": 42
    },
    // ...
]

UTM Source

GET /api/v1/statistics/utm/source

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.342,
        "utm_source": "source"
    },
    // ...
]

UTM Medium

GET /api/v1/statistics/utm/medium

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.342,
        "utm_medium": "medium"
    },
    // ...
]

UTM Campaign

GET /api/v1/statistics/utm/campaign

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.342,
        "utm_campaign": "campaign"
    },
    // ...
]

UTM Content

GET /api/v1/statistics/utm/content

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.342,
        "utm_content": "content"
    },
    // ...
]

UTM Term

GET /api/v1/statistics/utm/term

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.342,
        "utm_term": "term"
    },
    // ...
]

Total Visitors

This endpoint returns the total number of visitors, views, sessions, bounces, bounce rate, conversion rate, and custom metrics. The difference from the visitors endpoint (see below) is that the results are not grouped by day. Manually summing visitors for multiple days gives a different result because returning visitors are counted multiple times.

GET /api/v1/statistics/total

EXAMPLE RESPONSE

{
    "visitors": 42,
    "views": 56,
    "sessions": 48,
    "bounces": 23,
    "bounce_rate": 0.4791,
    "cr": 0.25,
	"custom_metric_avg": 42.1,
	"custom_metric_total": 598
}

Total Visitors, Page Views, and Members

This endpoint returns the total number of visitors, page views, and team members. Responses are cached for up to 30 minutes.

GET /api/v1/statistics/overview

EXAMPLE RESPONSE

{
    "visitors": 42,
    "views": 56,
    "visitors_growth": 0.42,
    "views_growth": 0.57,
    "member": 7
}

Visitors

GET /api/v1/statistics/visitor

EXAMPLE RESPONSE

Which time component is set depends on the scale filter. Setting it to day (default) sets the day field. Otherwise the corresponding field is set.

[
    {
        "day": "2021-05-12T00:00:00Z",
        "week": null,
        "month": null,
        "year": null,
        "visitors": 42,
        "views": 56,
        "sessions": 48,
        "bounces": 23,
        "bounce_rate": 0.4791,
        "cr": 0.25,
        "custom_metric_avg": 42.1,
        "custom_metric_total": 598
    },
    // ...
]

Pages

GET /api/v1/statistics/page

EXAMPLE RESPONSE

[
    {
        "path": "/home",
        "title": "Home",
        "visitors": 42,
        "views": 56,
        "sessions": 48,
        "bounces": 23,
        "relative_visitors": 0.342,
        "relative_views": 0.298,
        "bounce_rate": 0.765,
        "average_time_spent_seconds": 42
    },
    // ...
]

Entry Pages

GET /api/v1/statistics/page/entry

EXAMPLE RESPONSE

[
    {
        "path": "/home",
        "title": "Home",
        "visitors": 42,
        "sessions": 67,
        "entries": 56,
        "entry_rate": 0.298,
        "average_time_spent_seconds": 42
    },
    // ...
]

Exit Pages

GET /api/v1/statistics/page/exit

EXAMPLE RESPONSE

[
    {
        "path": "/bye",
        "title": "Bye",
        "visitors": 42,
        "sessions": 67,
        "exits": 56,
        "exit_rate": 0.298
    },
    // ...
]

Event Pages

This endpoint returns all pages on which an event was triggered. It requires the event name filter to be set.

GET /api/v1/statistics/event/page

EXAMPLE RESPONSE

[
    {
        "path": "/home",
        "title": "Home",
        "visitors": 42,
        "views": 56,
        "sessions": 48,
        "bounces": 23,
        "relative_visitors": 0.342,
        "relative_views": 0.298,
        "bounce_rate": 0.765,
        "average_time_spent_seconds": 42
    },
    // ...
]

Conversion Goals

GET /api/v1/statistics/goals

EXAMPLE RESPONSE

[
    {
        "page_goal": {
            "id": "A5kgYzK14m",
            "def_time": "2021-05-22T10:11:12.123456Z",
            "mod_time": "2021-05-22T10:11:12.123456Z",
            "domain_id": "M03loiem34",
            "name": "My Conversion Goal",
            "path_pattern": "/path/**",
            "pattern": "(?i)^\/path/[^\/]+$",
            "event_name": "event",
            "event_meta_key": "currency",
            "event_meta_value": "USD",
            "custom_metric_key": "amount",
            "custom_metric_type": "float",
            "visitor_goal": 5432,
            "cr_goal": 42.11,
            "custom_metric_total_goal": 346,
	        "custom_metric_avg_goal": 95.3,
            "delete_reached": true,
            "email_reached": true
        }
        "stats": {
            "visitors": 432,
            "views": 563,
            "cr": 0.065
        }
    },
    // ...
]

pattern is the regex pattern stored for the conversion goal, which can be used as the pattern parameter in the filter. path_pattern is the path pattern as configured by the user in the dashboard. The pattern is generated from this.

path_pattern, pattern and any of the event/custom metric members are optional and null in case they're not set.

custom_metric_type can be either integer or float.

Events

This endpoint lists all events and their metadata keys. You can use the event metadata endpoint to get the values for the event and a key.

GET /api/v1/statistics/events

EXAMPLE RESPONSE

[
    {
        "name": "event name",
        "count": 499,
        "visitors": 432,
        "views": 563,
        "cr": 0.065,
        "average_duration_seconds": 42,
        "meta_keys": ["meta", "keys"]
    },
    // ...
]

Event Metadata

This endpoint breaks down the event meta keys and values for a single event. You must filter for an event name and meta key in order for this to work.

GET /api/v1/statistics/event/meta

EXAMPLE RESPONSE

[
    {
        "name": "event name",
        "count": 499,
        "visitors": 432,
        "views": 563,
        "cr": 0.065,
        "average_duration_seconds": 42,
        "meta_value": "value",
    },
    // ...
]

Listing Events

This endpoint lists all events, including metadata. Note that this can be an expensive operation if you select events without filtering. Events are grouped by name and metadata. We recommend filtering by path ("all events on this page") and optionally by metadata key-value pairs.

GET /api/v1/statistics/event/list

EXAMPLE RESPONSE

[
    {
        "name": "Read article",
        "meta": {
            "title": "How We Develop and Operate Pirsch"
        },
        "visitors": 123,
        "count": 237
    },
    {
        "name": "Read article",
        "meta": {
            "title": "How to Track the Reading Time of Blog Articles and Registrations"
        },
        "visitors": 98,
        "count": 105
    },
    // ...
]

Growth Rates

GET /api/v1/statistics/growth

EXAMPLE RESPONSE

{
    "visitors_growth": 0.34,
    "views_growth": -0.05,
    "sessions_growth": 0.32,
    "bounces_growth": 0.65,
    "time_spent_growth": 0.45,
    "cr_growth": 0.22,
	"custom_metric_avg_growth": 0.09,
	"custom_metric_total_growth": 0.11
}

Active Visitors

Returns active visitors and pages for the past n seconds. n can be defined by passing the start query parameter and is set to 10 minutes by default.

Return the active visitors for the last minute.

GET /api/v1/statistics/active?start=60

EXAMPLE RESPONSE

{
    "stats": [
        {
            "path": "/home",
            "visitors": 42
        },
        // ...
    ],
    "visitors": 298
}

Visitors by Time of Day

GET /api/v1/statistics/hours

EXAMPLE RESPONSE

[
    {
        "hour": 0,
        "visitors": 42,
        "views": 56,
        "sessions": 48,
        "bounces": 23,
        "bounce_rate": 0.4791,
        "cr": 0.25,
        "custom_metric_avg": 42.1,
        "custom_metric_total": 598
    },
    {
        "hour": 1,
        "visitors": 29,
        "views": 52,
        "sessions": 21,
        "bounces": 19,
        "bounce_rate": 0.3219,
        "cr": 0.25,
        "custom_metric_avg": 42.1,
        "custom_metric_total": 598
    },
    // ...
]

Visitors by Minute

GET /api/v1/statistics/minutes

EXAMPLE RESPONSE

[
    {
        "minute": 0,
        "visitors": 42,
        "views": 56,
        "sessions": 48,
        "bounces": 23,
        "bounce_rate": 0.4791,
        "cr": 0.25,
        "custom_metric_avg": 42.1,
        "custom_metric_total": 598
    },
    {
        "minute": 1,
        "visitors": 29,
        "views": 52,
        "sessions": 21,
        "bounces": 19,
        "bounce_rate": 0.3219,
        "cr": 0.25,
        "custom_metric_avg": 42.1,
        "custom_metric_total": 598
    },
    // ...
]

Languages

GET /api/v1/statistics/language

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.24,
        "language": "en"
    },
    // ...
]

Referrer

GET /api/v1/statistics/referrer

EXAMPLE RESPONSE

[
    {
        "referrer": "Referrer",
        "referrer_name": "Name",
        "referrer_icon": "Icon",
        "visitors": 42,
        "sessions": 123,
        "relative_visitors": 0.256,
        "bounces": 21,
        "bounce_rate": 0.5
    },
    // ...
]

Operating System

GET /api/v1/statistics/os

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.24,
        "os": "Windows"
    },
    // ...
]

Operating System Version

GET /api/v1/statistics/os

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.24,
        "os": "Windows",
        "os_version": "10.0"
    },
    // ...
]

Browser

GET /api/v1/statistics/browser

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.24,
        "browser": "Firefox"
    },
    // ...
]

Browser Version

GET /api/v1/statistics/browser/version

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.24,
        "browser": "Firefox",
        "browser_version": "89.0"
    },
    // ...
]

Country

GET /api/v1/statistics/country

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.24,
        "country": "jp"
    },
    // ...
]

City

GET /api/v1/statistics/city

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.24,
        "city": "London"
    },
    // ...
]

Platform

GET /api/v1/statistics/platform

EXAMPLE RESPONSE

{
    "platform_desktop": 457,
    "platform_mobile": 204,
    "platform_unknown": 98,
    "relative_platform_desktop": 0.56,
    "relative_platform_mobile": 0.34,
    "relative_platform_unknown": 0.17
}

Screen Classes

GET /api/v1/statistics/screen

EXAMPLE RESPONSE

[
    {
        "visitors": 42,
        "relative_visitors": 0.24,
        "screen_class": "XXL"
    },
    // ...
]

Tags

This endpoint returns a list of tag keys. To break down a single tag, use /api/v1/statistics/tag/details.

GET /api/v1/statistics/tags

EXAMPLE RESPONSE

[
    {
        "key": "author",
	    "visitors": 42,
	    "views": 57,
	    "relative_visitors": 0.24,
	    "relative_views": 0.35
    },
    // ...
]

Tag Breakdown

This endpoint returns a breakdown for a single tag.

GET /api/v1/statistics/tag/details

EXAMPLE RESPONSE

[
    {
        "key": "author",
        "value": "Alice",
	    "visitors": 42,
	    "views": 57,
	    "relative_visitors": 0.24,
	    "relative_views": 0.35
    },
    // ...
]

Sessions

This endpoint returns a list of sessions for the given filter. The visitor_id is a string, as the number is too big for JavaScript/JSON (unsigned integer 64 bit).

GET /api/v1/statistics/session/list

EXAMPLE RESPONSE

[
    {
	    "visitor_id": "12345...",
	    "session_id": 12345,
	    "time": "2024-04-10T15:16:56Z",
	    "start": "2024-04-10T15:03:31Z",
	    "duration_seconds": 42,
	    "entry_path": "/",
	    "exit_path": "/pricing",
	    "page_views": 4,
	    "is_bounce": false,
	    "entry_title": "Home",
	    "exit_title": "Pricing",
	    "language": "en",
	    "country_code": "us",
	    "city": "San Francisco",
	    "referrer": "https://google.com",
	    "referrer_name": "Google",
	    "referrer_icon": "",
	    "os": "Windows",
	    "os_version": "11.0",
	    "browser": "Firefox",
	    "browser_version": "124.0",
	    "desktop": true,
	    "mobile": false,
	    "screen_class": "XXL",
	    "utm_source": "",
	    "utm_medium": "",
	    "utm_campaign": "",
	    "utm_content": "",
	    "utm_term": "",
	    "extended": 0
    },
    // ...
]

Session Breakdown

This endpoint breaks down a single session and returns all page views and events in chronological order. The visitor_id and session_id for the filter must both be set.

GET /api/v1/statistics/session/details

EXAMPLE RESPONSE

[
    {
	    "page_view": {
	        "visitor_id": 12345,
	        "session_id": 12345,
	        "time": "2024-04-10T15:16:56Z",
	        "duration_seconds": 0,
	        "path": "/",
	        "title": "Home",
	        "language": "en",
	        "country_code": "us",
	        "city": "San Francisco",
	        "referrer": "https://google.com",
	        "referrer_name": "Google",
	        "referrer_icon": "",
	        "os": "Windows",
	        "os_version": "11.0",
            "browser": "Firefox",
            "browser_version": "124.0",
            "desktop": true,
            "mobile": false,
            "screen_class": "XXL",
            "utm_source": "",
            "utm_medium": "",
            "utm_campaign": "",
            "utm_content": "",
            "utm_term": "",
	        "tag_keys": ["author", "abtest"],
	        "tag_values": ["John", "a"]
        },
	    "event": null
    },
    {
	    "page_view": null,
	    "event": {
            "visitor_id": 12345,
	        "session_id": 12345,
	        "time": "2024-04-10T15:16:56Z",
            "name": "event",
            "meta_keys": ["key"],
            "meta_values": ["value"],
            "duration_seconds": 42,
            "path": "/",
	        "title": "Home",
	        "language": "en",
	        "country_code": "us",
	        "city": "San Francisco",
            "referrer": "https://google.com",
	        "referrer_name": "Google",
	        "referrer_icon": "",
	        "os": "Windows",
	        "os_version": "11.0",
            "browser": "Firefox",
            "browser_version": "124.0",
            "desktop": true,
            "mobile": false,
            "screen_class": "XXL",
            "utm_source": "",
            "utm_medium": "",
            "utm_campaign": "",
            "utm_content": "",
            "utm_term": ""
        }
    },
    // ...
]

Keywords

This endpoints requires the Google Search Console integration.

INFO

We recommend using the Search Console API directly instead of calling it through Pirsch.

GET /api/v1/statistics/keywords

EXAMPLE RESPONSE

[
    {
        "keys": ["key", "word"],
        "clicks": 456,
        "impressions": 920,
        "ctr": 0.49,
        "position": 4
    },
    // ...
]

Deleting Statistics

This endpoint deletes data asynchronously for given domain ID and dates.

The kind can be left empty to delete everything or set to:

• all to delete statistics collected by Pirsch (excluding imported statistics)
• events to only delete events or
• imported to only delete imported statistics

DELETE /api/v1/statistics

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m",
	"kind": "",
	"from": "2024-01-01",
	"to": "2024-02-15"
}

Managing Domains

Domains can be managed by creating a user client (on the account settings page).

Getting the Domain ID

Most API endpoints require you to set a domain ID. We call them domains, but you can also think of them as a single dashboard. The terms are used interchangeably.

For clients created for a dashboard, only one domain is returned. For clients created on the account settings page, this endpoint returns all domains that you have access to.

Don't forget to set the access token or access key in the Authorization header: Bearer <oAuth access token or access key>.

GET /api/v1/domain

EXAMPLE RESPONSE

[
    {
        "id": "A5kgYzK14m",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "user_id": "pzy1bjD1lv",
        "organization_id": null,
        "hostname": "example.com",
        "subdomain": "example",
        "identification_code": "oSdiAe...",
        "public": false,
        "google_user_id": null,
        "google_user_email": null,
        "gsc_domain": null,
        "new_owner": null,
        "timezone": "Europe/Berlin",
	    "group_by_title": false,
	    "active_visitors_seconds": 600,
        "disable_scripts": false,
        "statistics_start": null,
        "imported_statistics": false,
        "metadata": {},
        "theme_id": "x98y1bjAm72",
	    "theme": {
            // key value pairs
        },
        "custom_domain": "my.custom-domain.com",
        "user_role": "Owner", // Admin, Viewer
        "settings": {},
        "theme_settings": {
            // key value pairs
        },
        "display_name": "My Website",
        "subscription_active": true
    }
]

Creating a Domain

This endpoint adds a new domain.

POST /api/v1/domain

EXAMPLE REQUEST

{
    "hostname": "example.com",
    "subdomain": "example",
    "timezone": "Europe/Berlin",
    "organization_id": null,
    "theme_id": null
}

EXAMPLE RESPONSE

{
    "id": "A5kgYzK14m",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "user_id": "pzy1bjD1lv",
    "organization_id": null,
    "hostname": "example.com",
    "subdomain": "example",
    "identification_code": "oSdiAe...",
    "public": false,
    "google_user_id": null,
    "google_user_email": null,
    "gsc_domain": null,
    "new_owner": null,
    "timezone": "Europe/Berlin",
    "group_by_title": false,
    "active_visitors_seconds": 600,
    "disable_scripts": false,
    "statistics_start": null,
    "imported_statistics": false,
    "metadata": {},
    "theme_id": "x98y1bjAm72",
    "theme": {
        // key value pairs
    },
    "custom_domain": "my.custom-domain.com",
    "user_role": "Owner", // Admin, Viewer
    "settings": {},
    "theme_settings": {
        // key value pairs
    },
    "display_name": "My Website",
    "subscription_active": true
}

Deleting a Domain

This endpoint deletes a domain.

DELETE /api/v1/domain?id=A5kgYzK14m

Listing Domains

This endpoint is described in more detail in the Statistics section. It returns all domains for a user client or a specific domain for the ID, subdomain, custom domain, or access code.

GET /api/v1/domain?id=A5kgYzK14m
GET /api/v1/domain?subdomain=example
GET /api/v1/domain?domain=my-domain.com
GET /api/v1/domain?access=03kDM6o...

EXAMPLE RESPONSE

{
    "id": "A5kgYzK14m",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "user_id": "pzy1bjD1lv",
    "organization_id": null,
    "hostname": "example.com",
    "subdomain": "example",
    "identification_code": "oSdiAe...",
    "public": false,
    "google_user_id": null,
    "google_user_email": null,
    "gsc_domain": null,
    "new_owner": null,
    "timezone": "Europe/Berlin",
    "group_by_title": false,
    "active_visitors_seconds": 600,
    "disable_scripts": false,
    "statistics_start": null,
    "imported_statistics": false,
    "metadata": {},
    "theme_id": "x98y1bjAm72",
    "theme": {
        // key value pairs
    },
    "custom_domain": "my.custom-domain.com",
    "user_role": "Owner", // Admin, Viewer
    "settings": {},
    "theme_settings": {
        // key value pairs
    },
    "display_name": "My Website",
    "subscription_active": true
}

Resetting the Identification Code

This endpoint resets the identification code for the domain and return a new one.

PUT /api/v1/domain

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m"
}

EXAMPLE RESPONSE

{
    "identification_code": "..."
}

Updating the Hostname

This endpoint updates the hostname for your domain.

POST /api/v1/domain/hostname

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "hostname": "new-hostname.com"
}

Updating the Subdomain

This endpoint updates the subdomain for your dashboard (on your-sub-domain.pirsch.io).

POST /api/v1/domain/subdomain

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "subdomain": "new-subdomain"
}

Toggle the Visiblity of Your Dashboard

This endpoint toggles the visibility of your dashboard from private to public or vice versa.

POST /api/v1/domain/public

EXAMPLE RESPONSE

{
    "domain_id": "A5kgYzK14m"
}

Disable Scripts

This endpoint toggles the option to send data via scripts for a given domain.

POST /api/v1/domain/scripts

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m"
}

Toggle Grouping by Title

This endpoint toggles if statistics are grouped by page title.

POST /api/v1/domain/title

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m"
}

Changing the Active Visitors Time

This endpoint changes the time in seconds that visitors are considered active on your site.

POST /api/v1/domain/active

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "time": 123
}

Changing the Time Zone

This endpoint changes the time zone for the dashboard.

POST /api/v1/domain/timezone

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "timezone": "Europe/Berlin"
}

Updating the metadata field.

This endpoint will update the metadata field. The field can be used to store user defined tags or configuration. Do what you want with it.

POST /api/v1/domain/metadata

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "metadata": {
        // generic object
    }
}

Setting a Domain as Favorite

This endpoint sets one of your domains as a favorite. This requires a user client.

POST /api/v1/user/favorite

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m"
}

Pinning a Domain

This endpoint pins a domain. This requires a user client.

POST /api/v1/user/pin

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m"
}

Showing Active Visitors in the Page Title

This endpoint toggles whether or not to display active visitors in the page title (tab).

POST /api/v1/user/active

Toggle Full Width

This endpoint toggles displaying the dashboard at full width.

POST /api/v1/user/fullwidth

Managing Access Links

Listing Access Links

This endpoint lists all access links.

GET /api/v1/domain/link?domain_id=A5kgYzK14m

EXAMPLE RESPONSE

[
    {
        "id": "A5kgYzK14m",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "domain_id": "A5kgYzK14m",
        "code": "...",
        "description": "..."
    },
    // ...
]

The code can be used to create a URL with read-only access to a domain. To do that, replace <subdomain> and <code for the domain in the following URL: https://<subdomain>.pirsch.io/?access=<code>

Set Base Theme

This endpoint sets the base theme for a dashboard. The settings from the theme will be overwritten by specific settings for the dashboard.

PUT /api/v1/domain/theme

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "theme_id": "83MD02kxoe"
}

EXAMPLE RESPONSE

{
    // key value pairs with the theme settings
}

Update the Theme Settings

This endpoint updates the theme settings for given domain. The settings will overwrite the base theme.

POST /api/v1/domain/theme

EXAMPLE REQUEST

FormData:

logo_light: File
logo_dark: File
favicon: File
data: JSON {
    "domain_id": "A5kgYzK14m",
    "settings": {
        // key value pairs
    }
}

EXAMPLE RESPONSE

{
    // complete domain with the updated settings
}

Set a Custom Domain

This endpoint updates the custom domain for given dashboard.

POST /api/v1/domain/custom

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "hostname": "my-domain.com"
}

Check Whether a Custom Domain Exists

This endpoint checks whether a custom domain exists already. A custom domain can only be used for a single dashboard.

GET /api/v1/domain/custom?domain=my-domain.com

Creating an Access Link

This endpoint creates a new access link.

POST /api/v1/domain/link

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "description": "..."
}

EXAMPLE RESPONSE

{
    "id": "A5kgYzK14m",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "A5kgYzK14m",
    "code": "...",
    "description": "..."
}

Updating an Access Link

This endpoint updates an existing access link.

PUT /api/v1/domain/link

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m",
    "description": "..."
}

Deleting an Access Link

This endpoint deletes an access link.

DELETE /api/v1/domain/link?id=0DJ0mo934

Managing Members and Permissions

Listing Members

This endpoint lists all members for a domain or an organization.

GET /api/v1/member?id=A5kgYzK14m
GET /api/v1/member?organization_id=kco39ID2

EXAMPLE RESPONSE

[
    {
        "id": "A5kgYzK14m",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "user_id": "pzy1bjD1lv",
        "domain_id": "A5kgYzK14m",
        "organization_id": "kco39ID2",
        "role": "admin",
        "user": {
            "id": "0DJ0mo934",
            "email": "...",
            "full_name": "...",
            "picture": "..."
        }
    },
    // ...
]

Inviting Members

This endpoint invites new members to a domain or an organization via email. New members have the Viewer role. They'll receive an account activation if they don't have an account yet.

POST /api/v1/member

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m",
    "organization_id": null,
    "emails": ["member@foo.com", "member@bar.com" /* ... */]
}

id is the domain ID. Either the id or organization_id must be set.

Updating the Role of a Member

This endpoint updates a single member's role. Valid roles are Viewer and Admin (the Owner role requires a domain transfer). This works for domains and organizations.

PUT /api/v1/member

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m",
    "role": "admin"
}

id is the member ID.

Removing a Member

This endpoint removes a member from a domain or an organization.

DELETE /api/v1/member?id=0DJ0mo934

Listing Invitations

This endpoint lists all invitations for the user, a domain, or an organization.

GET /api/v1/invitation
GET /api/v1/invitation?domain_id=A5kgYzK14m
GET /api/v1/invitation?organization_id=39oOw9mKD31

EXAMPLE RESPONSE

[
    {
        "id": "I309Dow31",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "domain_id": "A5kgYzK14m",
        "organization_id": null,
        "email": "user@example.com",
        "domain": {
            // complete domain
        },
        "organization": null // or complete organization if ID is set
    },
    // ...
]

Deleting an Invitation

This endpoint deletes an invitation to a domain or an organization.

DELETE /api/v1/invitation

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "organization_id": null,
    "id": "I309Dow31"
}

domain_id and organization_id are optional. They are used to look up the invitationf or a domain or an organization instead of the currently signed in user.

Accepting an Invitation

This endpoint will accept an invitation for the currently signed in user.

POST /api/v1/invitation

EXAMPLE REQUEST

{
    "id": "I309Dow31"
}

Managing Alternative Domains

Alternative domains allow you to add additional traffic sources. By default, Pirsch will block a request that doesn't come from the domain configured on the dashboard. For example, if you want to create a roll-up view, you will need to add any domain that could send traffic to the dashboard as an additional domain.

Always add the domain alternatives at the receiving end.

Listing Alternative Domains

This endpoint returns all alternative domains associated with a website.

GET /api/v1/domain/alternative?domain_id=0DJ0mo934

EXAMPLE RESPONSE

[
    {
        "id": "A5kgYzK14m",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "domain_id": "0DJ0mo934",
        "hostname": "alternative.domain.com"
    },
    // ...
]

Creating Alternative Domains

This endpoint creates a new alternate domain for a Website.

POST /api/v1/domain/alternative

EXAMPLE REQUEST

{
    "domain_id": "0DJ0mo934",
    "hostname": "alternative.domain.com"
}

EXAMPLE RESPONSE

{
    "id": "A5kgYzK14m",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "0DJ0mo934",
    "hostname": "alternative.domain.com"
}

Updating Alternative Domains

This endpoint updates the hostname for an alternative domain.

PUT /api/v1/domain/alternative

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m",
    "hostname": "new-alternative.domain.com"
}

Deleting Alternative Domains

This endpoint deletes an alternative domain by ID.

DELETE /api/v1/domain/alternative?id=A5kgYzK14m

Managing Snippets

The snippets can be customized for advanced usage. There are two snippet configurations: page view and event.

Updating a Snippet

This endpoint updates a snippet for a domain and type. The type can either be page view or event.

POST /api/v1/domain/snippet

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "type": "page view",
	"dev": true,
	"include": "\/include,\/path\/.*",
	"exclude": "\/exclude,\/path\/.*",
	"domains": "example.com,domain.com",
	"endpoint": "https://pirsch.proxy.com/hit",
	"sample": "/sample,/paths"
}

Getting a Snippet

This endpoint returns the snippet details for a domain and type. The type can be either page view, event, or session.

GET /api/v1/domain/snippet?domain_id=A5kgYzK14m&type=event

EXAMPLE RESPONSE

{
    "id": "9do3JD31z",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "A5kgYzK14m",
    "type": "event",
	"dev": true,
	"include": "\/include,\/path\/.*",
	"exclude": "\/exclude,\/path\/.*",
	"domains": "example.com,domain.com",
	"endpoint": "https://pirsch.proxy.com/hit",
	"sample": "/sample,/paths"
}

Managing Clients

It's possible to manage domain clients with a user client.

Listing Clients

This endpoint lists all clients.

GET /api/v1/client?id=0DJ0mo934

EXAMPLE RESPONSE

[
    {
        "id": "A5kgYzK14m",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "domain_id": "0DJ0mo934",
        "client_id": "...", // 32 characters
        "description": "...",
        "scope_hit": "w",
        "scope_event": "w",
        "scope_session": "w",
        "scope_statistics": "r",
        "scope_domains": "w",
        "scope_organizations": "w",
	    "scope_themes": "w",
	    "scope_billing": "r"
    },
    // ...
]

Creating a Client

This endpoint creates a new client.

POST /api/v1/client

EXAMPLE REQUEST

{
    "domain_id": "0DJ0mo934",
    "type": "token",
    "description": "...",
    "scope_hit": "w",
    "scope_event": "w",
    "scope_session": "w",
    "scope_statistics": "r",
    "scope_domains": "w",
    "scope_organizations": "w",
    "scope_themes": "w",
    "scope_billing": "r"
}

The type can either be oauth or token. oauth will create an oAuth client with a client ID and secret that can be used to read and write data. The token type is read-only and typically used to send statistics.

Scopes can grant read or write access. The table below shows the possible values for available scopes.

Scope	Read	Write
hit		x
event		x
statistics	x
domains	x	x

The domains scope has two different meanings, depending on whether it's used for a domain or a user client:

• For user clients, it provides access to most user actions, such as creating or deleting domains and settings.
• For domain clients, it provides access to domain-specific settings, such as the subdomain or access links.

EXAMPLE RESPONSE

{
    "id": "A5kgYzK14m",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "0DJ0mo934",
    "client_id": "...", // 32 characters
    "client_secret": "...", // 64 characters
    "description": "...",
    "scope_hit": "w",
    "scope_event": "w",
    "scope_session": "w",
    "scope_statistics": "r",
    "scope_domains": "w",
    "scope_organizations": "w",
    "scope_themes": "w",
    "scope_billing": "r"
}

Updating a Client

This endpoint updates the description for a client.

POST /api/v1/client

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m",
    "description": "..."
}

EXAMPLE RESPONSE

{
    "id": "A5kgYzK14m",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "0DJ0mo934",
    "client_id": "...", // 32 characters
    "description": "...",
    "scope_hit": "w",
    "scope_event": "w",
    "scope_session": "w",
    "scope_statistics": "r",
    "scope_domains": "w",
    "scope_organizations": "w",
    "scope_themes": "w",
    "scope_billing": "r"
}

Deleting a Client

This endpoint deletes a client.

DELETE /api/v1/client?id=A5kgYzK14m

Managing Email Reports

Listing Email Reports

This endpoint lists all email reports.

GET /api/v1/report?id=0DJ0mo934

EXAMPLE RESPONSE

[
    {
        "id": "A5kgYzK14m",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "domain_id": "0DJ0mo934",
        "email": "...",
        "interval": 2,
        "link_to": "custom",
        "next_report": "2021-05-22T10:11:12.123456Z"
    },
    // ...
]

Creating Email Reports

This endpoint creates a new email report.

link_to sets the link to the dashboard within the email report. By default, it will link to the private dashboard (dashboard.pirsch.io). In order for it to link to public dashboards or custom domains, they need to be configured. Otherwise, the report will fall back to the private dashboard.

POST /api/v1/report

EXAMPLE REQUEST

{
    "domain_id": "0DJ0mo934",
    "emails": ["member@foo.com", "member@bar.com"],
    "interval": 1, // weeks or 0 for daily
    "link_to": "dashboard" // empty/dashboard, public, custom
}

EXAMPLE RESPONSE

[
    {
        "id": "A5kgYzK14m",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "domain_id": "0DJ0mo934",
        "email": "...",
        "interval": 1,
        "link_to": "dashboard",
        "next_report": "2021-05-22T10:11:12.123456Z"
    },
    // ...
]

Updating an Email Report

This endpoint updates an existing email report.

PUT /api/v1/report

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m",
    "interval": 4, // weeks or 0 for daily
    "link_to": "public" // empty/dashboard, public, custom
}

EXAMPLE RESPONSE

{
    "id": "A5kgYzK14m",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "0DJ0mo934",
    "email": "...",
    "interval": 4,
    "link_to": "public",
    "next_report": "2021-05-22T10:11:12.123456Z"
}

Deleting an Email Report

This endpoint deletes an email report.

DELETE /api/v1/report?id=A5kgYzK14m

Managing Webhooks

Listing Webhooks

This endpoint lists all webhooks.

GET /api/v1/webhook?domain_id=0DJ0mo934

EXAMPLE RESPONSE

[
    {
        "id": "A5kgYzK14m",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "domain_id": "0DJ0mo934",
	    "description": "Description",
	    "event": "event_name",
	    "endpoint": "https://example.com/api/webhook",
	    "active": true
    },
    // ...
]

Creating/Updating Webhooks

This endpoint creates or updates a webhook. Updating an exising webhooks, even if no fields are changed, will activate it again if it has been disabled due to failed requests.

POST /api/v1/webhook

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m", // updates the webhook if set
    "domain_id": "0DJ0mo934",
    "description": "Description",
    "event": "event_name",
    "endpoint": "https://example.com/api/webhook"
}

EXAMPLE RESPONSE

{
    "id": "A5kgYzK14m",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "0DJ0mo934",
    "description": "Description",
    "event": "event_name",
    "endpoint": "https://example.com/api/webhook",
    "active": true
}

Deleting Webhooks

This endpoint will delete a webhook.

DELETE /api/v1/webhook?id=A5kgYzK14m

Managing Traffic Spike Notifications

Enabling/Disabling Traffic Spike Notifications

This endpoint will toggle traffic spike notifications.

PUT /api/v1/traffic/spike

EXAMPLE REQUEST

{
    "domain_id": "0DJ0mo934"
}

Configuring Traffic Spike Notifications

This endpoint will configure traffic spike notifications. Don't forget to enable them using the endpoint above. threshold is the number of unique visitors that need to be on the site at the same time to trigger the warning.

POST /api/v1/traffic/spike

EXAMPLE REQUEST

{
    "domain_id": "0DJ0mo934",
    "threshold": 100
}

Managing Traffic Warnings

Enabling/Disabling Traffic Warnings

This endpoint will toggle traffic warnings.

PUT /api/v1/traffic/warning

EXAMPLE REQUEST

{
    "domain_id": "0DJ0mo934"
}

Configuring Traffic Warnings

This endpoint will configure traffic warnings. Don't forget to enable them using the endpoint above. threshold is the number of days that might pass before a notification is send.

POST /api/v1/traffic/warning

EXAMPLE REQUEST

{
    "domain_id": "0DJ0mo934",
    "threshold": 5
}

Managing Conversion Goals

Listing Conversion Goals

This endpoint lists all conversion goals.

GET /api/v1/goal?id=0DJ0mo934

EXAMPLE RESPONSE

[
    {
        "id": "A5kgYzK14m",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "domain_id": "0DJ0mo934",
        "name": "...",
        "path_pattern": "...", // regex, null if not set
        "pattern": "/checkout/**", // or null if not set
        "event_name": "event", // or null if not set
        "event_meta_key": "currency", // or null if not set
        "event_meta_value": "USD", // or null if not set
        "custom_metric_key": "amount", // or null if not set
        "custom_metric_type": "float", // integer, float, or null if not set
        "visitor_goal": 123, // or null if not set
        "cr_goal": 1.23, // or null if not set
        "custom_metric_total_goal": 346, // or null if not set
        "custom_metric_avg_goal": 95.3, // or null if not set
        "delete_reached": false,
        "email_reached": true
    },
    // ...
]

Creating a Conversion Goal

This endpoint creates a new conversion goal.

POST /api/v1/goal

Either the path_pattern and/or event fields must be set.

EXAMPLE REQUEST

{
    "domain_id": "0DJ0mo934",
    "name": "...",
    "path_pattern": "/checkout/**", // or null
    "event_name": "event", // or null
    "event_meta_key": "currency", // or null
    "event_meta_value": "USD", // or null
    "custom_metric_key": "amount", // or null
    "custom_metric_type": "float", // integer, float, or null
    "visitors": 123, // 0 to pass
    "cr": 1.23, // 0 to pass
    "custom_metric_total_goal": 346, // 0 to pass
    "custom_metric_avg_goal": 95.3, // 0 to pass
    "delete_reached": false,
    "email_reached": true
}

EXAMPLE RESPONSE

{
    "id": "A5kgYzK14m",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "0DJ0mo934",
    "name": "...",
    "path_pattern": "...", // regex or null if not set
    "pattern": "/checkout/**", // or null if not set
    "event_name": "event", // or null if not set
    "event_meta_key": "currency", // or null if not set
    "event_meta_value": "USD", // or null if not set
    "custom_metric_key": "amount", // or null if not set
    "custom_metric_type": "float", // integer, float, or null
    "visitor_goal": 123, // or null if not set
    "cr_goal": 1.23, // or null if not set
    "custom_metric_total_goal": 346, // or null if not set
    "custom_metric_avg_goal": 95.3, // or null if not set
    "delete_reached": false,
    "email_reached": true
}

Updating a Conversion Goal

This endpoint updates an existing converion goal.

PUT /api/v1/goal

EXAMPLE REQUEST

{
    "id": "A5kgYzK14m",
    "domain_id": "0DJ0mo934",
    "name": "...",
    "path_pattern": "/checkout/**", // or null
    "event_name": "event", // or null
    "event_meta_key": "currency", // or null
    "event_meta_value": "USD", // or null
    "custom_metric_key": "amount", // or null
    "custom_metric_type": "float", // integer, float, or null
    "visitors": 123, // 0 to pass
    "cr": 1.23, // 0 to pass
    "custom_metric_total_goal": 346, // 0 to pass
    "custom_metric_avg_goal": 95.3, // 0 to pass
    "delete_reached": false,
    "email_reached": true
}

EXAMPLE RESPONSE

{
    "id": "A5kgYzK14m",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "0DJ0mo934",
    "name": "...",
    "path_pattern": "...", // regex or null if not set
    "pattern": "/checkout/**", // or null if not set
    "event_name": "event", // or null if not set
    "event_meta_key": "currency", // or null if not set
    "event_meta_value": "USD", // or null if not set
    "custom_metric_key": "amount", // or null if not set
    "custom_metric_type": "float", // integer, float, or null
    "visitor_goal": 123, // or null if not set
    "cr_goal": 1.23, // or null if not set
    "custom_metric_total_goal": 346, // or null if not set
    "custom_metric_avg_goal": 95.3, // or null if not set
    "delete_reached": false,
    "email_reached": true
}

Deleting a Conversion Goal

This endpoint deletes a conversion goal.

DELETE /api/v1/goal?id=A5kgYzK14m

Testing the Regular Expression for a Conversion Goal

This endpoint tests whether a regular expression is valid for a conversion goal. Use it to see if you can use an expression before creating or updating a conversion goal.

POST /api/v1/goal/regex

EXAMPLE REQUEST

{
    "regex": "(?i)^/regular/expression/[^/]*$",
    "sample": "/regular/expression/example"
}

EXAMPLE RESPONSE

{
    "match": true
}

An error is returned if the expression is invalid. Otherwise, it returns if the regular expression matches the pattern.

Managing Views

Listing Views

This endpoint returns a list of views for a given domain.

GET /api/v1/view?domain_id=A5kgYzK14m

EXAMPLE RESPONSE

[
    {
        "id": "Jk49fgm38",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "domain_id": "A5kgYzK14m",
        "user_id": "94jO3jDM2",
        "name": "My View",
        "from": "2022-01-02",
        "to": "2022-03-04",
        "from_time": "14:56",
	    "to_time": "15:07",
        "period": 5,
        "compare": null, // previous, year, custom
        "compare_from": null, // date
        "compare_to": null, // date
        "compare_weekday": true,
        "path": ["/sample/path"],
        "entry_path": null,
        "exit_path": null,
        "pattern": null,
        "language": null,
        "country": null,
        "city": null,
        "referrer": null,
        "referrer_name": null,
        "os": null,
        "browser": null,
        "platform": null,
        "screen_class": null,
        "utm_source": null,
        "utm_medium": null,
        "utm_campaign": null,
        "utm_content": null,
        "utm_term": null,
        "event": ["event"],
        "event_meta_key": ["meta_key"],
        "event_meta_value": ["meta_value"],
        "tag": ["tag"],
        "tag_key": ["tag_key"],
        "tag_value": ["tag_value"],
        "visitor_id": 12345,
	    "session_id": 12345
    },
    // ...
]

Creating/Updating a View

This endpoint creates a new view or updates an existing view. It updates an existing view if the ID is set.

POST /api/v1/view

EXAMPLE REQUEST

{
    "id": "Jk49fgm38",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "A5kgYzK14m",
    "user_id": "94jO3jDM2",
    "name": "My View",
    "from": "2022-01-02",
    "to": "2022-03-04",
    "from_time": "14:56",
    "to_time": "15:07",
    "period": 5,
    "compare": null, // previous, year, custom
    "compare_from": null, // date
    "compare_to": null, // date
    "compare_weekday": true,
    "path": ["/sample/path"],
    "entry_path": null,
    "exit_path": null,
    "pattern": null,
    "language": null,
    "country": null,
    "city": null,
    "referrer": null,
    "referrer_name": null,
    "os": null,
    "browser": null,
    "platform": null,
    "screen_class": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "event": ["event"],
    "event_meta_key": ["meta_key"],
    "event_meta_value": ["meta_value"],
    "tag": ["tag"],
    "tag_key": ["tag_key"],
    "tag_value": ["tag_value"],
    "visitor_id": 12345,
    "session_id": 12345
}

EXAMPLE RESPONSE

{
    "id": "Jk49fgm38",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "A5kgYzK14m",
    "user_id": "94jO3jDM2",
    "name": "My View",
    "from": "2022-01-02",
    "to": "2022-03-04",
    "from_time": "14:56",
    "to_time": "15:07",
    "period": 5,
    "compare": null, // previous, year, custom
    "compare_from": null, // date
    "compare_to": null, // date
    "compare_weekday": true,
    "path": ["/sample/path"],
    "entry_path": null,
    "exit_path": null,
    "pattern": null,
    "language": null,
    "country": null,
    "city": null,
    "referrer": null,
    "referrer_name": null,
    "os": null,
    "browser": null,
    "platform": null,
    "screen_class": null,
    "utm_source": null,
    "utm_medium": null,
    "utm_campaign": null,
    "utm_content": null,
    "utm_term": null,
    "event": ["event"],
    "event_meta_key": ["meta_key"],
    "event_meta_value": ["meta_value"],
    "tag": ["tag"],
    "tag_key": ["tag_key"],
    "tag_value": ["tag_value"],
    "visitor_id": 12345,
    "session_id": 12345
}

Deleting a View

This endpoint deletes a view.

DELETE /api/v1/view?id=Jk49fgm38

Managing Organizations

Listing Organizations

This endpoint lists all organizations the user belongs to or is the owner of.

GET /api/v1/organization

EXAMPLE RESPONSE

[
    {
        "id": "Jk49fgm38",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "user_id": "oOD28xa97",
        "name": "Organization",
        "member": 4,
        "domains": 5,
        "themes": 6,
        "role": "Owner",
        "can_edit": true
    },
    // ...
]

Can edit will be set to true if a Pirsch Plus subscription is active and the current user is the owner of the organization.

Creating an Organization

This endpoint creates a new organization.

POST /api/v1/organization

EXAMPLE REQUEST

{
    "name": "Organization"
}

EXAMPLE RESPONSE

{
    "id": "Jk49fgm38",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "user_id": "oOD28xa97",
    "name": "Organization",
    "member": 4,
    "role": "Owner",
    "can_edit": true
}

Updating an Organization

This endpoint updates an existing organization.

PUT /api/v1/organization

EXAMPLE REQUEST

{
    "id": "Jk49fgm38",
    "name": "New Name"
}

EXAMPLE RESPONSE

{
    "id": "Jk49fgm38",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "user_id": "oOD28xa97",
    "name": "New Name",
    "member": 4,
    "role": "Owner",
    "can_edit": true
}

Deleting an Organization

This endpoint deletes an organization. If delete_domains is set to true, all domains belonging to this organization will also be deleted! Otherwise they will be removed from the organization.

DELETE /api/v1/organization?id=Jk49fgm38&delete_domains=true

Setting a Default Theme

This endpoint will set the default theme for given organization. The default theme is pre-selected when new websites are added to the organization.

PUT /api/v1/organization/theme

EXAMPLE REQUEST

{
    "organization_id": "Jk49fgm38",
    "theme_id": "93ODk5o1sL"
}

Listing Domains

This endpoint will list all domains belonging to an organization.

GET /api/v1/organization/domain?id=Jk49fgm38

EXAMPLE RESPONSE

[
    // domains
]

Adding a Domain

This endpoint adds an existing domain to an organization.

POST /api/v1/organization/domain

EXAMPLE REQUEST

{
    "id": "Jk49fgm38",
    "domain_id": "93ODk5o1sL"
}

EXAMPLE RESPONSE

{
    // domain
}

Removing a Domain

This endpoint removes a domain from given organization.

DELETE /api/v1/organization/domain?id=Jk49fgm38&domain_id=93ODk5o1sL

Managing Themes

Themes can either belong to a user or an organization. They are also used on domains to overwrite settings.

Creating/Updating/Copying a Theme

This endpoint creates, updates, or copies a theme.

POST /api/v1/theme

EXAMPLE REQUEST

FormData:

logo_light: File
logo_dark: File
favicon: File
data: JSON {
    "id": "Jk49fgm38",
	"copy_id": null,
	"domain_id": null,
	"organization_id": null,
	"name": "My Theme",
	"settings": {
        // key value pairs
    }
}

If neither the domain_id nor the organization_id are set, the theme will be created for the user.

EXAMPLE RESPONSE

{
    "id": "Jk49fgm38",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "user_id": "93ODk5o1sL",
    "organization_id": null,
    "name": "My Theme",
    "settings": {
        // key value pairs
    },
    "is_default": false
}

Listing Themes

This endpoint lists themes for the user, an organization, a subdomain, or a custom domain. If include_organizations is set to true, the list will contain all themes the user has directly or indirectly access to.

GET /api/v1/theme
GET /api/v1/theme?include_organizations=true
GET /api/v1/theme?organization_id=Jk49fgm38
GET /api/v1/theme?subdomain=sub
GET /api/v1/theme?domain=my-domain.com

EXAMPLE RESPONSE

[
    // themes
]

Deleting a Theme

This endpoint deletes a theme. If keep_settings is set to true, the settings will be applied to the domains the themes is used in before deletion.

DELETE /api/v1/theme?id=Jk49fgm38&keep_settings=true

Deleting a Theme File

This endpoint will delete a theme file for a them or a domain. The file can either be logo_light, logo_dark, or favicon.

DELETE /api/v1/theme/file?theme_id=Jk49fgm38&file=logo_light
DELETE /api/v1/theme/file?domain_id=93ODk5o1sL&file=favicon

Importing Data from Google Universal Analytics

Getting an Import Job

This endpoint returns the import job, if any, for the specified domain.

GET /api/v1/google/import/job?domain_id=A5kgYzK14m

EXAMPLE RESPONSE

{
    "id": "Jk49fgm38",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "A5kgYzK14m",
	"google_user_id": "...",
	"google_user_email": "...",
	"domain": null,
    "from": null,
	"to": null
}

Canceling an Import Job

This endpoint cancels the import job for given domain.

DELTE /api/v1/google/import/job?domain_id=A5kgYzK14m

Listing Google Analytics Profiles

This endpoint lists available profiles (views) for the connected Google Account.

GET /api/v1/google/import/profile?domain_id=A5kgYzK14m

EXAMPLE RESPONSE

[
    {
        "name": "Name",
        "id": "..."
    },
    // ...
]

Starting the Import

This endpoint starts the import after connecting the dashboard to your Google account.

POST /api/v1/google/import

EXAMPLE REQUEST

{
    "domain_id": "A5kgYzK14m",
    "property": "<GA view ID>",
    "from": "2022-01-01",
    "to": "2022-08-01"
}

EXAMPLE RESPONSE

{
    "id": "Jk49fgm38",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "A5kgYzK14m",
	"google_user_id": "...",
	"google_user_email": "...",
	"domain": "<GA view ID>",
    "from": "2022-01-01",
	"to": "2022-08-01"
}

Billing

Usage

This endpoint returns the total usage for a selected period or the current billing cycle, including page views for deleted domains. from and to are optional and can be left blank, in which case the current billing cycle will be used.

If there are more than 50 dashboards on an account, this endpoint will return only one result called All.

API clients require the scope statistics to use this endpoint.

GET /api/v1/billing?from=2023-11-01&to=2023-11-12

EXAMPLE RESPONSE

[
    {
        "domain": {
            "id": "Jk49fgm38",
            // ...
        },
        "page_views": 42
    },
    // ...
]