Pirsch

https://docs.pirsch.io
Admin
Pirsch is a simple, privacy-friendly, and open-source web analytics solution designed to provide...
Tokens:66,273
Snippets:685
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Growth Rate Example Calculation

Source: https://docs.pirsch.io/get-started/statistics

An example demonstrating the calculation of growth rate using visitor numbers from two consecutive weeks.

```text
growth = (1561 - 978) / 978
growth = 583 / 978
growth = 0.596114519

growth = +59.6% (rounded)
```

--------------------------------

### DNS Zone File for Subdomain

Source: https://docs.pirsch.io/advanced/custom-domains

Example DNS zone file configuration for a subdomain. This includes A and AAAA records required for custom domain setup.

```dns
$ORIGIN custom-domain.com.
$TTL 3600
my IN A 23.88.33.242
   IN A 49.13.203.20
   IN AAAA 2a01:4f8:1c1e:5420::1
   IN AAAA 2a01:4f8:1c1e:5420::1
```

--------------------------------

### POST /api/v1/import/fathom

Source: https://docs.pirsch.io/api-sdks/api-v1

Starts an import job for Fathom.

```APIDOC
## POST /api/v1/import/fathom

### Description
Starts the import for Fathom. The body is multi-part encoded to include the zip file.

### Method
POST

### Endpoint
/api/v1/import/fathom
```

--------------------------------

### List Access Links Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example JSON response for a GET request to list all access links for a domain.

```json
[
    {
        "id": "A5kgYzK14m",
        "def_time": "2021-05-22T10:11:12.123456Z",
        "mod_time": "2021-05-22T10:11:12.123456Z",
        "domain_id": "A5kgYzK14m",
        "code": "...",
        "description": "...",
        "valid_until": "2021-06-01T00:00:00.000000Z"
    },
    // ...
]
```

--------------------------------

### DNS Zone File for Root Domain

Source: https://docs.pirsch.io/advanced/custom-domains

Example DNS zone file configuration for a root domain. This includes A and AAAA records required for custom domain setup.

```dns
$ORIGIN custom-domain.com.
$TTL 3600
@ IN A 23.88.33.242
  IN A 49.13.203.20
  IN AAAA 2a01:4f8:1c1e:5420::1
  IN AAAA 2a01:4f8:1c1e:5420::1
```

--------------------------------

### Google Analytics Import Request

Source: https://docs.pirsch.io/api-sdks/api-v1

Example JSON request body for starting a Google Analytics import.

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

--------------------------------

### Example Console Output for Event Testing

Source: https://docs.pirsch.io/advanced/events

This is an example of how an event will appear in the browser console when testing in a production environment. Events are ignored on localhost and logged to the console instead.

```text
Pirsch event: Button Clicked {"duration":42,"meta":{"Clicks":1}}
```

--------------------------------

### Google Analytics Import Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example JSON response after starting a Google Analytics import.

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

--------------------------------

### Toggle Week Start Day

Source: https://docs.pirsch.io/api-sdks/api-v1

Set the start of the week to Sunday or Monday.

```http
POST /api/v1/domain/start-week-sunday
```

```json
{
    "domain_id": "A5kgYzK14m"
}
```

--------------------------------

### Retrieve Domain List

Source: https://docs.pirsch.io/api-sdks/api-guide-v1

Example response for the GET /api/v1/domain endpoint, which returns a list of domains associated with the account.

```json
[
    {
        "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
    }
]
```

--------------------------------

### POST /api/v1/google/import

Source: https://docs.pirsch.io/api-sdks/api-v1

Starts a Google Analytics import job.

```APIDOC
## POST /api/v1/google/import

### Description
Starts the import after connecting the dashboard to your Google account.

### Method
POST

### Endpoint
/api/v1/google/import

### Request Body
- **domain_id** (string) - Required - The domain ID.
- **property** (string) - Required - The GA view ID.
- **from** (string) - Required - Start date (YYYY-MM-DD).
- **to** (string) - Required - End date (YYYY-MM-DD).

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

--------------------------------

### List Conversion Goals

Source: https://docs.pirsch.io/api-sdks/api-v1

Example response containing a list of conversion goals.

```json
[
    {
        "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
        "tags": ["blog", "author=John"],
        "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
    },
    // ...
]
```

--------------------------------

### Start Google Analytics Import

Source: https://docs.pirsch.io/api-sdks/api-v1

Initiates a data import from Google Analytics.

```http
POST /api/v1/google/import
```

--------------------------------

### POST /api/v1/domain/start-week-sunday

Source: https://docs.pirsch.io/api-sdks/api-v1

Toggles the start day of the week.

```APIDOC
## POST /api/v1/domain/start-week-sunday

### Description
Toggles if statistics should start on Sunday or Monday.

### Method
POST

### Endpoint
/api/v1/domain/start-week-sunday

### Request Body
- **domain_id** (string) - Required - The ID of the domain
```

--------------------------------

### List Organizations Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example JSON response for the GET /api/v1/organization endpoint.

```json
[
    {
        "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
    },
    // ...
]
```

--------------------------------

### Plausible/Fathom Import Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example JSON response for Plausible or Fathom import initiation.

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

--------------------------------

### Create Organization Request and Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example request and response payloads for creating a new organization.

```json
{
    "name": "Organization"
}
```

```json
{
    "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
}
```

--------------------------------

### Start Plausible or Fathom Import

Source: https://docs.pirsch.io/api-sdks/api-v1

Initiates a data import for Plausible or Fathom using multi-part encoding.

```http
POST /api/v1/import/fathom
```

```http
POST /api/v1/import/plausible
```

--------------------------------

### GET /api/v1/client

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists all clients for a given ID.

```APIDOC
## GET /api/v1/client

### Description
Lists all clients associated with the provided ID.

### Method
GET

### Endpoint
/api/v1/client

### Parameters
#### Query Parameters
- **id** (string) - Required - The client or domain ID.
```

--------------------------------

### Plausible/Fathom Import Request

Source: https://docs.pirsch.io/api-sdks/api-v1

Example request body for Plausible or Fathom imports.

```text
domain="A5kgYzK14m"
file=<data>
```

--------------------------------

### Import Job Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example JSON response for an import job status request.

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

--------------------------------

### Get Snippet Details

Source: https://docs.pirsch.io/api-sdks/api-v1

Retrieves the current snippet configuration for a domain.

```json
{
    "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"
}
```

--------------------------------

### Billing Usage Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example JSON response for billing usage statistics.

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

--------------------------------

### Set Default Theme Request

Source: https://docs.pirsch.io/api-sdks/api-v1

Example request payload for setting the default theme for an organization.

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

--------------------------------

### GET /api/v1/goal

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists all conversion goals for a domain, with optional filtering.

```APIDOC
## GET /api/v1/goal

### Description
This endpoint lists all conversion goals. The optional search parameter can be used to filter the result set by the conversion goal name.

### Method
GET

### Endpoint
/api/v1/goal

### Parameters
#### Query Parameters
- **id** (string) - Required - The domain ID.
- **search** (string) - Optional - Filter by goal name.
```

--------------------------------

### List Webhooks JSON Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example response structure when listing all webhooks for a domain.

```json
[
    {
        "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
    },
    // ...
]
```

--------------------------------

### Visitor Statistics Response

Source: https://docs.pirsch.io/api-sdks/api-guide-v1

Example response from the visitor statistics endpoint showing daily metrics.

```json
[
    {
        "day": "2023-01-01T00:00:00Z",
        "week": null,
        "month": null,
        "year": null,
        "visitors": 42,
        "views": 56,
        "sessions": 48,
        "bounces": 23,
        "bounce_rate": 0.4791
    },
    // ...
]
```

--------------------------------

### GET /api/v1/invitation

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists all invitations for the user, a domain, or an organization.

```APIDOC
## GET /api/v1/invitation

### Description
Lists all invitations for the user, a domain, or an organization.

### Method
GET

### Endpoint
/api/v1/invitation

### Parameters
#### Query Parameters
- **domain_id** (string) - Optional - Domain ID.
- **organization_id** (string) - Optional - Organization ID.
```

--------------------------------

### Add Domain Request and Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example request and response payloads for adding a domain to an organization.

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

```json
{
    // domain
}
```

--------------------------------

### GET /api/v1/theme

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists themes for the user, an organization, a subdomain, or a custom domain.

```APIDOC
## GET /api/v1/theme

### Description
Lists themes for the user, an organization, a subdomain, or a custom domain. Use optional parameters to filter results.

### Method
GET

### Endpoint
/api/v1/theme

### Parameters
#### Query Parameters
- **search** (string) - Optional - Filter by theme name
- **include_organizations** (boolean) - Optional - Include themes from organizations
- **organization_id** (string) - Optional - Filter by organization ID
- **subdomain** (string) - Optional - Filter by subdomain
- **domain** (string) - Optional - Filter by domain name
```

--------------------------------

### GET /api/v1/statistics/growth

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns growth rates for various metrics.

```APIDOC
## GET /api/v1/statistics/growth

### Description
Returns growth rates for visitors, views, sessions, bounces, time spent, conversion rate, and custom metrics.

### Method
GET

### Endpoint
/api/v1/statistics/growth

### Response
#### Success Response (200)
- **visitors_growth** (float) - Growth rate for visitors
- **views_growth** (float) - Growth rate for views
- **sessions_growth** (float) - Growth rate for sessions
- **bounces_growth** (float) - Growth rate for bounces
- **time_spent_growth** (float) - Growth rate for time spent
- **cr_growth** (float) - Growth rate for conversion rate
- **custom_metric_avg_growth** (float) - Growth rate for custom metric average
- **custom_metric_total_growth** (float) - Growth rate for custom metric total
```

--------------------------------

### Create a New Client

Source: https://docs.pirsch.io/api-sdks/api-v1

Creates a new client with specified scopes and type.

```json
{
    "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"
}
```

```json
{
    "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"
}
```

--------------------------------

### List Domains Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example JSON response for listing domains belonging to an organization.

```json
[
    // domains
]
```

--------------------------------

### Update Organization Request and Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example request and response payloads for updating an existing organization.

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

```json
{
    "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
}
```

--------------------------------

### Create Access Link Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Example JSON response returned after successfully creating an access link.

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

--------------------------------

### Add Auto-Join Hostname Request

Source: https://docs.pirsch.io/api-sdks/api-v1

Example request payload for adding a hostname to the auto-join list.

```json
{
    "id": "Jk49fgm38",
    "auto_join": ["example.com"]
}
```

--------------------------------

### GET /api/v1/organization/domain

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists all domains belonging to an organization.

```APIDOC
## GET /api/v1/organization/domain

### Description
Lists all domains belonging to an organization. The optional `search` parameter can be used to filter the result set by the hostname.

### Method
GET

### Endpoint
/api/v1/organization/domain

### Parameters
#### Query Parameters
- **id** (string) - Required - The ID of the organization
- **search** (string) - Optional - Filter by hostname
```

--------------------------------

### GET /api/v1/filter

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists all traffic filters for a domain.

```APIDOC
## GET /api/v1/filter

### Description
This endpoint lists all traffic filters for a given domain.

### Method
GET

### Endpoint
/api/v1/filter

### Parameters
#### Query Parameters
- **domain_id** (string) - Required - The ID of the domain.
```

--------------------------------

### GET /api/v1/webhook

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists all webhooks for a specific domain.

```APIDOC
## GET /api/v1/webhook

### Description
This endpoint lists all webhooks associated with a given domain ID.

### Method
GET

### Endpoint
/api/v1/webhook

### Parameters
#### Query Parameters
- **domain_id** (string) - Required - The ID of the domain to list webhooks for.

### Response
#### Success Response (200)
- **id** (string) - Webhook ID
- **def_time** (string) - Creation timestamp
- **mod_time** (string) - Modification timestamp
- **domain_id** (string) - Domain ID
- **description** (string) - Webhook description
- **event** (string) - Event name
- **endpoint** (string) - Webhook URL
- **active** (boolean) - Active status

#### Response Example
[
    {
        "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
    }
]
```

--------------------------------

### POST /api/v1/client

Source: https://docs.pirsch.io/api-sdks/api-v1

Creates a new client.

```APIDOC
## POST /api/v1/client

### Description
Creates a new client with specified scopes and type.

### Method
POST

### Endpoint
/api/v1/client

### Request Body
- **domain_id** (string) - Required - The domain ID.
- **type** (string) - Required - 'oauth' or 'token'.
- **description** (string) - Optional - Client description.
```

--------------------------------

### GET /api/v1/report

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists all email reports for a domain.

```APIDOC
## GET /api/v1/report

### Description
Lists all email reports associated with a domain ID.

### Method
GET

### Endpoint
/api/v1/report

### Parameters
#### Query Parameters
- **id** (string) - Required - The domain ID.
```

--------------------------------

### Configure Dashboards with Access Keys

Source: https://docs.pirsch.io/advanced/cf-workers

Define your website domains and their corresponding Pirsch access keys. This is the basic setup for proxying analytics.

```javascript
const dashboards = {
    "example.com": {
        accessKey: "pa_x92lfoe..."
    }
};
```

--------------------------------

### Configure Dashboards with Rollup Views

Source: https://docs.pirsch.io/advanced/cf-workers

Set up multiple dashboards, including support for rollup views, by specifying access keys for main and rollup dashboards. This allows for aggregated analytics across different sites.

```javascript
const dashboards = {
    "example.com": {
        accessKey: "pa_x92lfoe..."
    },
    "second-with-rollup.com": {
        accessKey: "pa_a53lvpw...",
        rollup: [
            "pa_rollup1...", // access key of the rollup view dashboard
            "pa_rollup2...", // supports multiple rollup dashboards
            // ...
        ]
    }
};
```

--------------------------------

### GET /api/v1/member

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists all members for a domain or an organization.

```APIDOC
## GET /api/v1/member

### Description
Lists all members for a domain or an organization.

### Method
GET

### Endpoint
/api/v1/member

### Parameters
#### Query Parameters
- **id** (string) - Optional - Domain ID.
- **organization_id** (string) - Optional - Organization ID.
```

--------------------------------

### GET /api/v1/user/rewards

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns the affiliate rewards for the user.

```APIDOC
## GET /api/v1/user/rewards

### Description
This endpoint returns the affiliate rewards for the user. This action requires a client created for the user.

### Method
GET

### Endpoint
/api/v1/user/rewards

### Response
#### Success Response (200)
- **sum** (integer) - Total sum of rewards
- **count** (integer) - Count of rewards
- **rewards** (array) - List of reward objects
```

--------------------------------

### Create a New Domain

Source: https://docs.pirsch.io/api-sdks/api-v1

Adds a new domain dashboard. Hostname, subdomain, and timezone are mandatory fields.

```json
{
    "hostname": "example.com",
    "subdomain": "example",
    "timezone": "Europe/Berlin",
    "organization_id": null,
    "theme_id": null,
    "public": false,
	"group_by_title": false,
	"active_visitors_seconds": 0,
	"disable_scripts": false,
	"display_name": "",
	"traffic_spike_threshold": 0,
	"traffic_warning_threshold_days": 0,
    "settings": {
        "active": true,
        "active_public": true,
        "funnels": true,
        "funnels_public": true,
        "sessions": true,
        "sessions_public": true,
        "links": true,
        "links_public": true,
        "graphs": true,
        "graphs_public": true,
        "pages": true,
        "pages_public": true,
        "sources": true,
        "sources_public": true,
        "goals": true,
        "goals_public": true,
        "events": true,
        "events_public": true,
        "location": true,
        "location_public": true,
        "devices": true,
        "devices_public": true,
        "weekdays": true,
        "weekdays_public": true,
        "keywords": true,
        "keywords_public": true,
        "nav_reload": true,
        "nav_reload_public": true,
        "nav_filter": true,
        "nav_filter_public": true,
        "nav_views": true,
        "nav_views_public": true,
        "nav_period": true,
        "nav_period_public": true,
        "nav_comparison": true,
        "nav_comparison_public": true,
        "nav_period_live": true,
        "nav_period_live_public": true
    }
}
```

--------------------------------

### GET /api/v1/user/news

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns unread news for the user.

```APIDOC
## GET /api/v1/user/news

### Description
This endpoint returns the unread news for the user. This action requires a client created for the user.

### Method
GET

### Endpoint
/api/v1/user/news

### Response
#### Success Response (200)
- **news** (integer) - Number of unread news items.
- **date** (string) - Date of the news item.
- **version** (string) - Version associated with the news.
- **headline** (string) - News headline.
- **content** (string) - HTML content of the news.
```

--------------------------------

### GET /api/v1/statistics/tag/details

Source: https://docs.pirsch.io/api-sdks/api-v1

Retrieves a breakdown for a single tag.

```APIDOC
## GET /api/v1/statistics/tag/details

### Description
Returns a breakdown for a single tag.

### Method
GET

### Endpoint
/api/v1/statistics/tag/details

### Response
#### Success Response (200)
- **key** (string) - Tag key
- **value** (string) - Tag value
- **visitors** (integer) - Number of visitors
- **views** (integer) - Number of views
- **relative_visitors** (float) - Relative percentage of visitors
- **relative_views** (float) - Relative percentage of views
```

--------------------------------

### GET /api/v1/statistics/city

Source: https://docs.pirsch.io/api-sdks/api-v1

Retrieves statistics broken down by city.

```APIDOC
## GET /api/v1/statistics/city

### Description
Returns statistics for cities.

### Method
GET

### Endpoint
/api/v1/statistics/city

### Response
#### Success Response (200)
- **visitors** (integer) - Number of visitors
- **relative_visitors** (float) - Relative percentage of visitors
- **country_code** (string) - ISO country code
- **region** (string) - Region name
- **city** (string) - City name
```

--------------------------------

### Create Access Link Request

Source: https://docs.pirsch.io/api-sdks/api-v1

Example JSON request body for creating a new access link. The valid_until field is optional.

```json
{
    "domain_id": "A5kgYzK14m",
    "description": "...",
    "valid_until": "2024-10-01T00:00:00.000000Z"
}
```

--------------------------------

### GET /api/v1/statistics/region

Source: https://docs.pirsch.io/api-sdks/api-v1

Retrieves statistics broken down by region.

```APIDOC
## GET /api/v1/statistics/region

### Description
Returns statistics for regions.

### Method
GET

### Endpoint
/api/v1/statistics/region

### Response
#### Success Response (200)
- **visitors** (integer) - Number of visitors
- **relative_visitors** (float) - Relative percentage of visitors
- **country_code** (string) - ISO country code
- **region** (string) - Region name
```

--------------------------------

### Retrieve Conversion Goals

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns configured conversion goals and their associated statistics.

```json
[
    {
        "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
        }
    },
    // ...
]
```

--------------------------------

### GET /api/v1/statistics/country

Source: https://docs.pirsch.io/api-sdks/api-v1

Retrieves statistics broken down by country.

```APIDOC
## GET /api/v1/statistics/country

### Description
Returns statistics for countries.

### Method
GET

### Endpoint
/api/v1/statistics/country

### Response
#### Success Response (200)
- **visitors** (integer) - Number of visitors
- **relative_visitors** (float) - Relative percentage of visitors
- **country_code** (string) - ISO country code
```

--------------------------------

### PHP Page View Integration

Source: https://docs.pirsch.io/api-sdks/api-guide-v1

Example of constructing the request array in PHP using server superglobals.

```php
$request = array(
    // Construct the URL.
    'url' => 'http'.(isset($_SERVER['HTTPS']) ? 's' : '').'://'.$_SERVER['HTTP_HOST'].$_SERVER['REQUEST_URI'],

    // Use the remote IP or a header in case your server is behind a proxy or load balancer.
    'ip' => $_SERVER['REMOTE_ADDR'],

    // Set the User-Agent.
    'user_agent' => $_SERVER['HTTP_USER_AGENT'],

    // Set the Accept-Language header.
    'accept_language' => $_SERVER['HTTP_ACCEPT_LANGUAGE'],

    // Set the client hint headers.
    'sec_ch_ua' => $_SERVER['Sec-CH-UA'],
	'sec_ch_ua_mobile' => $_SERVER['Sec-CH-UA-Mobile'],
	'sec_ch_ua_platform' => $_SERVER['Sec-CH-UA-Platform'],
	'sec_ch_ua_platform_version' => $_SERVER['Sec-CH-UA-Platform-Version'],
	'sec_ch_width' => $_SERVER['Sec-CH-Width'],
    'sec_ch_viewport_width' => $_SERVER['Sec-CH-Viewport-Width'],

    // Set the referrer. Maybe from a query parameter, like: ?ref=My+Referrer
    'referrer' => $_SERVER['HTTP_REFERER'],

    // Other optional fields...
);

// Use $request to send the data to Pirsch.
```

--------------------------------

### GET /api/v1/statistics/browser

Source: https://docs.pirsch.io/api-sdks/api-v1

Retrieves statistics broken down by browser.

```APIDOC
## GET /api/v1/statistics/browser

### Description
Returns statistics for browsers.

### Method
GET

### Endpoint
/api/v1/statistics/browser

### Response
#### Success Response (200)
- **visitors** (integer) - Number of visitors
- **relative_visitors** (float) - Relative percentage of visitors
- **browser** (string) - Browser name
```

--------------------------------

### GET /api/v1/statistics/goals

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns conversion goal statistics.

```APIDOC
## GET /api/v1/statistics/goals

### Description
Returns conversion goal statistics.

### Method
GET

### Endpoint
/api/v1/statistics/goals

### Response
#### Success Response (200)
- **page_goal** (object) - Goal definition
- **stats** (object) - Goal statistics

### Response Example
[
    {
        "page_goal": {
            "id": "A5kgYzK14m",
            "name": "My Conversion Goal"
        },
        "stats": {
            "visitors": 432,
            "views": 563,
            "cr": 0.065
        }
    }
]
```

--------------------------------

### Configure Server-Side Client Hints Headers

Source: https://docs.pirsch.io/get-started/client-hints

Set these response headers on your server to request Client Hints and grant permission for them to be forwarded to the Pirsch API.

```http
Accept-CH: Sec-CH-UA, Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-Width, Sec-CH-Viewport-Width
Permissions-Policy: ch-ua=(self "https://api.pirsch.io"), ch-ua-mobile=(self "https://api.pirsch.io"), ch-ua-platform=(self "https://api.pirsch.io"), ch-ua-platform-version=(self "https://api.pirsch.io"), ch-width=(self "https://api.pirsch.io"), ch-viewport-width=(self "https://api.pirsch.io")
```

--------------------------------

### GET /api/v1/statistics/page/exit

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns exit page statistics.

```APIDOC
## GET /api/v1/statistics/page/exit

### Description
Returns exit page statistics.

### Method
GET

### Endpoint
/api/v1/statistics/page/exit

### Response
#### Success Response (200)
- **path** (string) - Page path
- **exits** (integer) - Number of exits

### Response Example
[
    {
        "path": "/bye",
        "exits": 56
    }
]
```

--------------------------------

### Create, Update, or Copy a Theme

Source: https://docs.pirsch.io/api-sdks/api-v1

Use this endpoint to create, update, or copy a theme by providing form data including files and a JSON configuration object.

```text
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
    }
}
```

```json
{
    "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
}
```

--------------------------------

### POST /api/v1/goal

Source: https://docs.pirsch.io/api-sdks/api-v1

Creates a new conversion goal.

```APIDOC
## POST /api/v1/goal

### Description
This endpoint creates a new conversion goal. Either the path_pattern and/or event fields must be set.

### Method
POST

### Endpoint
/api/v1/goal
```

--------------------------------

### GET /api/v1/statistics/page/entry

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns entry page statistics.

```APIDOC
## GET /api/v1/statistics/page/entry

### Description
Returns entry page statistics.

### Method
GET

### Endpoint
/api/v1/statistics/page/entry

### Response
#### Success Response (200)
- **path** (string) - Page path
- **entries** (integer) - Number of entries

### Response Example
[
    {
        "path": "/home",
        "entries": 56
    }
]
```

--------------------------------

### GET /api/v1/statistics/hostname

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns statistics grouped by hostname.

```APIDOC
## GET /api/v1/statistics/hostname

### Description
Returns statistics grouped by hostname.

### Method
GET

### Endpoint
/api/v1/statistics/hostname

### Response
#### Success Response (200)
- **hostname** (string) - The hostname
- **visitors** (integer) - Number of visitors
- **views** (integer) - Number of views

### Response Example
[
    {
        "hostname": "example.com",
        "visitors": 42,
        "views": 56
    }
]
```

--------------------------------

### List Domain Clients

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns a list of all clients associated with a domain.

```json
[
    {
        "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"
    },
    // ...
]
```

--------------------------------

### GET /api/v1/billing

Source: https://docs.pirsch.io/api-sdks/api-v1

Retrieves usage statistics for the billing cycle.

```APIDOC
## GET /api/v1/billing

### Description
Returns the total usage for a selected period or the current billing cycle.

### Method
GET

### Endpoint
/api/v1/billing

### Parameters
#### Query Parameters
- **from** (string) - Optional - Start date.
- **to** (string) - Optional - End date.

### Response
#### Success Response (200)
- **domain** (object) - Domain details.
- **page_views** (integer) - Total page views.
```

--------------------------------

### GET /api/v1/import

Source: https://docs.pirsch.io/api-sdks/api-v1

Retrieves the import job for a specified domain.

```APIDOC
## GET /api/v1/import

### Description
Returns the import job for the specified domain, regardless of whether it is for Google Analytics, Plausible, or Fathom.

### Method
GET

### Endpoint
/api/v1/import

### Parameters
#### Query Parameters
- **domain_id** (string) - Required - The ID of the domain to retrieve the import job for.

### Response
#### Success Response (200)
- **id** (string) - The import job ID.
- **def_time** (string) - Creation timestamp.
- **mod_time** (string) - Modification timestamp.
- **domain_id** (string) - The domain ID.
- **type** (string) - The import type (ga, plausible, or fathom).

#### Response Example
{
    "id": "Jk49fgm38",
    "def_time": "2021-05-22T10:11:12.123456Z",
    "mod_time": "2021-05-22T10:11:12.123456Z",
    "domain_id": "A5kgYzK14m",
    "type": "ga"
}
```

--------------------------------

### POST /api/v1/domain/alternative

Source: https://docs.pirsch.io/api-sdks/api-v1

Creates a new alternative domain for a website.

```APIDOC
## POST /api/v1/domain/alternative

### Description
This endpoint creates a new alternate domain for a Website.

### Method
POST

### Endpoint
/api/v1/domain/alternative

### Request Body
- **domain_id** (string) - Required - The ID of the website domain.
- **hostname** (string) - Required - The hostname to add.

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

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created alternative domain.
- **def_time** (string) - Creation timestamp.
- **mod_time** (string) - Modification timestamp.
- **domain_id** (string) - The associated domain ID.
- **hostname** (string) - The hostname of the alternative domain.

#### Response Example
{
    "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"
}
```

--------------------------------

### GET /api/v1/organization

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists all organizations the user belongs to or owns.

```APIDOC
## GET /api/v1/organization

### Description
Lists all organizations the user belongs to or is the owner of. The optional `search` parameter can be used to filter the result set by the organization name.

### Method
GET

### Endpoint
/api/v1/organization

### Parameters
#### Query Parameters
- **search** (string) - Optional - Filter the result set by the organization name.

### Response
#### Success Response (200)
- **id** (string) - Organization ID
- **def_time** (string) - Creation timestamp
- **mod_time** (string) - Modification timestamp
- **user_id** (string) - User ID of the owner
- **name** (string) - Organization name
- **member** (integer) - Number of members
- **domains** (integer) - Number of domains
- **themes** (integer) - Number of themes
- **role** (string) - User role
- **can_edit** (boolean) - Whether the user can edit the organization
```

--------------------------------

### Update Theme Settings Response

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns the domain object with updated settings.

```json
{
    // complete domain with the updated settings
}
```

--------------------------------

### GET /api/v1/funnel

Source: https://docs.pirsch.io/api-sdks/api-v1

Lists all funnels, optionally filtered by name.

```APIDOC
## GET /api/v1/funnel

### Description
This endpoint lists all funnels. The optional `search` parameter can be used to filter the result set by the funnel name.

### Method
GET

### Endpoint
/api/v1/funnel

### Parameters
#### Query Parameters
- **id** (string) - Required - The domain ID.
- **search** (string) - Optional - Filter funnels by name.
```

--------------------------------

### GET /api/v1/domain/snippet

Source: https://docs.pirsch.io/api-sdks/api-v1

Retrieves the snippet details for a domain and type.

```APIDOC
## GET /api/v1/domain/snippet

### Description
Returns the snippet details for a domain and type.

### Method
GET

### Endpoint
/api/v1/domain/snippet

### Parameters
#### Query Parameters
- **domain_id** (string) - Required - The ID of the domain.
- **type** (string) - Required - The snippet type ('page view', 'event', or 'session').
```

--------------------------------

### Proxy Integration Example

Source: https://docs.pirsch.io/advanced/proxy

Use this script tag to load the Pirsch JavaScript from your own domain. Page views will be sent to your domain and then forwarded to your Pirsch dashboard.

```html
<script defer src="/pirsch/pirsch.min.js" id="pirschjs"></script>
```

--------------------------------

### GET /api/v1/user

Source: https://docs.pirsch.io/api-sdks/api-v1

Reads the account details for the logged in user.

```APIDOC
## GET /api/v1/user

### Description
This endpoint returns the account details for the logged in user. This action requires a client created for the user.

### Method
GET

### Endpoint
/api/v1/user
```

--------------------------------

### GET /api/v1/statistics/session/list

Source: https://docs.pirsch.io/api-sdks/api-v1

Returns a list of sessions for the given filter.

```APIDOC
## GET /api/v1/statistics/session/list

### Description
Returns a list of sessions for the given filter. Note that visitor_id is returned as a string due to 64-bit integer size constraints.

### Method
GET

### Endpoint
/api/v1/statistics/session/list

### Response
#### Success Response (200)
- **sessions** (array) - A list of session objects containing details like visitor_id, session_id, time, duration, and device information.
```
Tokens:
Raw