API
22. Jan, 2023This document describes the REST endpoints used to interact with Pirsch. The easiest way to get started is through one of the client SDKs. If you’re looking on how you can integrate Pirsch into your backend to monitor traffic, please check out the backend integration.
To use the API, you must create a client. New clients can be created on the settings page or on the account page.
Note that all samples do not necessarily show correct data. IDs from a request might not match the response. You should also be careful not to confuse IDs in their context. Fields are oftentimes just called id, but represent different objects.
Error Handling
In case of an error, Pirsch will return a JSON object in the body describing the issue and what you can do about it together with a meaningful HTTP status code. Errors have the following structure.
|
|
validation
lists errors related to input parameterserror
lists general errors, like when an object could’nt be found. There will usually be only one error message
Getting an Access Token
To make requests to the API, you need to get an access token first. The token must be send with every request in the Authorization
header in the format Bearer <token>
. If you receive a status code 401 (unauthorized), you need to create a new access token and try again. expires_at
timezone is set to UTC.
Client IDs and secrets can be created from the domain settings page (under Developer) or from the account settings page. Domain clients are created for a specific domain and can only access and manipulate the domain they were created for. User clients have more privileges and can access all domains the user has access to (with the same permissions, viewer, or admin).
Single access tokens (starting with pa_
) can only be used to send data (page views, events, and keep alive sessions) and don’t require a client ID, nor do they need to be refreshed. Treat both, client secrets and single access tokens, as passwords and store them securely.
The examples for the other endpoints in this document will omit the header.
Example request
POST https://api.pirsch.io/api/v1/token
|
|
Example response
|
|
Sending a Page Hit
This endpoint is used to send page hits to Pirsch. It requires you to send information about the request made by the client. How you get these 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.
Example request
POST https://api.pirsch.io/api/v1/hit
|
|
One small optimization you can make is to check the DNT
(Do Not Track) header before you make 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, or otherwise they will mess up your statistics. This works well for websites that run on a single server where you can buffer page views.
Example request
POST https://api.pirsch.io/api/v1/hit/batch
|
|
Sending an Event
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 these 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.
Example request
Fields with underscores are comments.
POST https://api.pirsch.io/api/v1/event
|
|
It’s possible to send multiple events at once. If you use the batch endpoint, make sure the events are in order, or otherwise they will mess up your statistics. This works well for websites that run on a single server where you can buffer events.
Example request
POST https://api.pirsch.io/api/v1/event/batch
|
|
Keeping a Session Alive
This endpoint is used to manually keep sessions alive. A session will usually be 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 to track apps or other custom build software.
Example request
POST https://api.pirsch.io/api/v1/session
|
|
It’s possible to send multiple requests at once. If you use the batch endpoint, make sure the updates are in order, or otherwise they will mess up your statistics. This works well for websites that run on a single server where you can buffer requests.
Example request
POST https://api.pirsch.io/api/v1/session/batch
|
|
Statistics
The following endpoints can be used to read statistics from Pirsch. To receive data, you need to set the filter. It will be skipped in the example 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, like ?from=2021-05-08&to=2021-05-15&language=en
.
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 |
tz | no | Europe/Berlin | The time zone. If not set, the default time zone for the dashboard will be used. |
start | no | 600 | Queries data for the past seconds (10 minutes in this example). The date range filters will be 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 will be 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 | 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. |
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 will be 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. |
Getting the Domain ID
Before you can make requests, you need to know the domain ID for the client. Make a request to the following endpoint and store the ID for the domain. Note that the domain will be returned in an array. The endpoint usually returns all domains a user has access to, but in this case it will always have one entry (except there is some permission error, then it will be empty).
Example request
GET /api/v1/domain
Example response
|
|
Session Duration
Example request
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.
|
|
Time on Page
Example request
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 will be set.
|
|
UTM Source
Example request
GET /api/v1/statistics/utm/source
Example response
|
|
UTM Medium
Example request
GET /api/v1/statistics/utm/medium
Example response
|
|
UTM Campaign
Example request
GET /api/v1/statistics/utm/campaign
Example response
|
|
UTM Content
Example request
GET /api/v1/statistics/utm/content
Example response
|
|
UTM Term
Example request
GET /api/v1/statistics/utm/term
Example response
|
|
Total Visitors
This endpoint returns the total visitor count, views, sessions, bounces, and bounce rate. The difference to the visitors’ endpoint (see below) is that the results are not grouped by day. Manually summing up the visitors for multiple days will return a different result, as returning visitors will be counted multiple times that way.
Example request
GET /api/v1/statistics/total
Example response
|
|
Visitors
Example request
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 will be set.
|
|
Pages
Example request
GET /api/v1/statistics/page
Example response
|
|
Entry Pages
Example request
GET /api/v1/statistics/page/entry
Example response
|
|
Exit Pages
Example request
GET /api/v1/statistics/page/exit
Example response
|
|
Event Pages
This endpoint returns all pages an event was triggered on. It requires the event name filter to be set.
Example request
GET /api/v1/statistics/event/page
Example response
|
|
Conversion Goals
Example request
GET /api/v1/statistics/goals
Example response
|
|
pattern
is the regex pattern stored for the conversion goal and can be used as the pattern
parameter in the filter. path_pattern
is the path pattern as configured by the user on the dashboard. The pattern
will be generated from it.
Events
This endpoint lists all events and their metadata keys. You can use the event metadata endpoint to receive the values for the event and a key.
Example request
GET /api/v1/statistics/events
Example response
|
|
Event Metadata
This endpoint will break 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.
Example request
GET /api/v1/statistics/event/meta
Example response
|
|
Listing Events
This endpoint will list all events including metadata. Note that this can be an expensive operation if you select events without filtering. The events will be grouped by name and metadata. We recommend filtering by path (“all events on this page”) and optionally metadata key-value pairs.
Example request
GET /api/v1/statistics/event/list
Example response
|
|
Growth Rates
Example request
GET /api/v1/statistics/growth
Example response
|
|
Active Visitors
Returns active visitors and pages for the past n seconds. n can be defined by passing the start
query parameter and will be set to 10 minutes by default.
Example request
Return the active visitors for the past minute.
GET /api/v1/statistics/active?start=60
Example response
|
|
Visitors by Time of Day
Example request
GET /api/v1/statistics/hours
Example response
|
|
Languages
Example request
GET /api/v1/statistics/language
Example response
|
|
Referrer
Example request
GET /api/v1/statistics/referrer
Example response
|
|
Operating System
Example request
GET /api/v1/statistics/os
Example response
|
|
Operating System Version
Example request
GET /api/v1/statistics/os
Example response
|
|
Browser
Example request
GET /api/v1/statistics/browser
Example response
|
|
Browser Version
Example request
GET /api/v1/statistics/browser/version
Example response
|
|
Country
Example request
GET /api/v1/statistics/country
Example response
|
|
City
Example request
GET /api/v1/statistics/city
Example response
|
|
Platform
Example request
GET /api/v1/statistics/platform
Example response
|
|
Screen Classes
Example request
GET /api/v1/statistics/screen
Example response
|
|
Keywords
This endpoints requires the Google Search Console integration. We recommend using the Search Console API directly instead of calling it through Pirsch.
Example request
GET /api/v1/statistics/keywords
Example response
|
|
Filter Options
The following endpoints return available filter options for a time period. For brevity, only one example request and response is given.
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/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
Example request
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
|
|
Managing Domains
Domains can be managed by creating a user client (on the account settings page).
Creating a Domain
This endpoint adds a new domain.
Example request
POST /api/v1/domain
|
|
Example response
|
|
Deleting a Domain
This endpoint deletes a domain.
Example request
DELETE /api/v1/domain?id=A5kgYzK14m
Listing Domains
This endpoint is described in the statistics section. The only difference is that it will return all domains if you use a user client.
Resetting the Identification Code
This endpoint will reset the identifcation code for the domain and returns a new one.
Example request
PUT /api/v1/domain
|
|
Example response
|
|
Updating the Subdomain
This endpoint will update the subdomain for your dashboard (on your-sub-domain.pirsch.io
).
Example request
POST /api/v1/domain/subdomain
|
|
Toggle the Visiblity of Your Dashboard
This endpoint will toggle the visibility of your dashboard from private to public or vise-versa.
Example request
POST /api/v1/domain/public
|
|
Disable Scripts
This endpoint will toggle the option to send data via scripts for given domain.
Example request
POST /api/v1/domain/scripts
|
|
Toggle Grouping by Title
This endpoint will toggle if statistics are grouped by page title.
Example request
POST /api/v1/domain/title
|
|
Changing the Active Visitors Time
This endpoint will change the time visitors are considered active on your website in seconds.
Example request
POST /api/v1/domain/active
|
|
Changing the Time Zone
This endpoint will change the time zone for the dashboard.
Example request
POST /api/v1/domain/timezone
|
|
Setting a Domain as Favorite
This endpoint sets one of your domains as favorite. This requires a user client.
Example request
POST /api/v1/user/favorite
|
|
Showing Active Visitors in the Page Title
This endpoint toggles whether you would like to see the active visitors in the page title (tab) or not.
Example request
POST /api/v1/user/active
Managing Additional Domains
Listing Additional Domains
This endpoint lists all additional domains.
Example request
GET /api/v1/domain/alternative
Example response
|
|
Creating an Additional Domain
This endpoint creates a new additonal domain.
Example request
POST /api/v1/domain/alternative
|
|
Example response
|
|
Updating an Additional Domain
This endpoint will update the hostname for an additional domain.
Example request
PUT /api/v1/domain/alternative
|
|
Example response
|
|
Deleting an Additional Domain
This endpoint will delete an additonal domain.
Example request
DELETE /api/v1/domain/alternative?id=39JDm291x2
Managing Access Links
Listing Access Links
This endpoint lists all access links.
Example request
GET /api/v1/domain/link?domain_id=A5kgYzK14m
Example response
|
|
The code can be used to create a URL with read access to a domain. To do that, replace <subdomain>
and <code
for the domain in the following URL: https://<subdomain>.pirsch.io/?access=<code>
Creating an Access Link
This endpoint creates a new access link.
Example request
POST /api/v1/domain/link
|
|
Example response
|
|
Updating an Access Link
This endpoint updates an existing access link.
Example request
PUT /api/v1/domain/link
|
|
Deleting an Access Link
This endpoint deletes an access link.
Example request
DELETE /api/v1/domain/link?id=0DJ0mo934
Managing Members and Permissions
Listing Members
This endpoint lists all members.
Example request
GET /api/v1/member?id=A5kgYzK14m
Example response
|
|
Inviting Members
This endpoints invites new member to a domain by email. New members will have the Viewer role.
Example request
POST /api/v1/member
|
|
id
is the domain ID.
Updating the Role of a Member
This endpoint will update the role of a single member. Valid roles are Viewer and Admin (the Owner role requires a domain transfer).
Example request
PUT /api/v1/member
|
|
id
is the member ID.
Removing a Member
This endpoints removes a member from a domain.
Example request
DELETE /api/v1/member?id=0DJ0mo934
Managing Alternative Domains
Alternative domains need to be created when you send statistics to multiple dashboards or create rollup views.
Listing Alternative Domains
This endpoint returns all alternative domains belonging to a website.
Example request
GET /api/v1/domain/alternative?domain_id=0DJ0mo934
Example response
|
|
Creating Alternative Domains
This endpoint creates a new alternative domain for a website.
Example request
POST /api/v1/domain/alternative
|
|
Example response
|
|
Updating Alternative Domains
This endpoint updates the hostname for an alternative domain.
Example request
PUT /api/v1/domain/alternative
|
|
Deleting Alternative Domains
This endpoint deletes an alternative domain by ID.
Example request
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 will update a snippet for a domain and type. The type can either be page view
or event
.
Example request
POST /api/v1/domain/snippet
|
|
Getting a Snippet
This endpoint returns a snippet for a domain and type. The type can either be page view
or event
.
Example request
GET /api/v1/domain/snippet?domain_id=A5kgYzK14m&type=event
Example response
|
|
Managing Clients
It’s possible to manage domain clients with a user client.
Listing Clients
This endpoint will list all clients.
Example request
GET /api/v1/client?id=0DJ0mo934
Example response
|
|
Creating a Client
This endpoint will create a new client.
Example request
POST /api/v1/client
|
|
Scopes can give read or write access. The table below shows which values are possible for available scopes.
Scope | Read | Write |
---|---|---|
hit | x | |
event | x | |
statistics | x | |
domains | x | x |
The domains
scope has two different meanins, depending on if it’s used for a domain or user client:
- for user clients, it will give access to most of the user actions, like creating or deleting domains and settings
- for domain clients, it will give access to domain specific settings, like the subdomain or access links
Example response
|
|
Updating a Client
This endpoint will update the description for a client.
Example request
POST /api/v1/client
|
|
Example response
|
|
Deleting a Client
This endpoint will delete a client.
DELETE /api/v1/client?id=A5kgYzK14m
Managing Email Reports
Listing Email Reports
This endpoint will list all email reports.
Example request
GET /api/v1/report?id=0DJ0mo934
Example response
|
|
Creating Email Reports
This endpoint will create a new email report.
Example request
POST /api/v1/report
|
|
Example response
|
|
Updating an Email Report
This endpoint will update an existing email report.
Example request
PUT /api/v1/report
|
|
Example response
|
|
Deleting an Email Report
This endpoint will delete an email report.
Example request
DELETE /api/v1/report?id=A5kgYzK14m
Managing Conversion Goals
Listing Conversion Goals
This endpoint will list all conversion goals.
Example request
GET /api/v1/goal?id=0DJ0mo934
Example response
|
|
Creating a Conversion Goal
This endpoint will create a new conversion goal.
Example request
POST /api/v1/goal
|
|
Example response
|
|
Updating a Conversion Goal
This endpoint will update an existing converion goal.
Example request
PUT /api/v1/goal
|
|
Example response
|
|
Deleting a Conversion Goal
This endpoint will delete a conversion goal.
Example request
DELETE /api/v1/goal?id=A5kgYzK14m
Testing the Regular Expression for a Conversion Goal
This endpoint will test if 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 fist.
Example request
POST /api/v1/goal/regex
|
|
Example response
|
|
An error will be returned in case the expression is invalid. Otherwise it will return if the regular expression matches the sample.
Managing Views
Listing Views
This endpoint returns a list of views for a given domain.
Example request
GET /api/v1/view?domain_id=A5kgYzK14m
Example response
|
|
Creating/Updating a View
This endpoint creates a new view or updates an existing one. It will update an existing view if the ID is set.
Example request
POST /api/v1/view
|
|
Example response
|
|
Deleting a View
This endpoint deletes a view.
Example request
DELETE /api/v1/view?id=Jk49fgm38
Importing Data from Google Universal Analytics
Getting an Import Job
This endpoint returns the import job for given domain, if any.
Example request
GET /api/v1/google/import/job?domain_id=A5kgYzK14m
Example response
|
|
Cancel an Import Job
This endpoint cancels the import job for given domain.
Example request
DELTE /api/v1/google/import/job?domain_id=A5kgYzK14m
Listing Google Analytics Profiles
This endpoint lists available profiles (views) for the connected Google account.
Example request
GET /api/v1/google/import/profile?domain_id=A5kgYzK14m
Example response
|
|
Starting the Import
This endpoint starts the import after connecting the dashboard to the Google account.
Example request
POST /api/v1/google/import
|
|
Example response
|
|