Pirsch Statistics API
Query analytics statistics by date range and filter criteria
OpenAPI Specification
openapi: 3.0.3
info:
title: Pirsch Access Links Statistics API
description: RESTful API for sending page views, events, and session data to Pirsch, and for querying statistics including visitors, pages, referrers, UTM parameters, geo-location, device, browser, conversion goals, funnels, and real-time active visitors. Also exposes management endpoints for domains, members, clients, webhooks, email reports, traffic filters, short links, and views.
version: '1'
contact:
name: Pirsch Support
url: https://pirsch.io
license:
name: Proprietary
url: https://pirsch.io/privacy
servers:
- url: https://api.pirsch.io/api/v1
description: Pirsch production API
security:
- BearerAuth: []
tags:
- name: Statistics
description: Query analytics statistics by date range and filter criteria
paths:
/statistics/total:
get:
operationId: getTotalStatistics
summary: Get total statistics
description: Get total visitors, views, sessions, and bounce data for a date range
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
description: Domain ID
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: tz
in: query
schema:
type: string
- name: scale
in: query
schema:
type: string
enum:
- day
- week
- month
- year
responses:
'200':
description: Total statistics
content:
application/json:
schema:
$ref: '#/components/schemas/TotalStats'
/statistics/visitor:
get:
operationId: getVisitorStatistics
summary: Get visitor statistics over time
description: Get visitors grouped by time scale
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: tz
in: query
schema:
type: string
- name: scale
in: query
schema:
type: string
enum:
- day
- week
- month
- year
responses:
'200':
description: Visitor time series
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/VisitorStats'
/statistics/page:
get:
operationId: getPageStatistics
summary: Get page statistics
description: Get statistics broken down by page path
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: search
in: query
schema:
type: string
- name: offset
in: query
schema:
type: integer
- name: limit
in: query
schema:
type: integer
- name: sort
in: query
schema:
type: string
- name: direction
in: query
schema:
type: string
enum:
- asc
- desc
responses:
'200':
description: Page statistics
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PageStats'
/statistics/hostname:
get:
operationId: getHostnameStatistics
summary: Get hostname statistics
description: Get statistics broken down by hostname
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Hostname statistics
content:
application/json:
schema:
type: array
items:
type: object
properties:
hostname:
type: string
visitors:
type: integer
views:
type: integer
sessions:
type: integer
bounces:
type: integer
relative_visitors:
type: number
relative_views:
type: number
bounce_rate:
type: number
/statistics/referrer:
get:
operationId: getReferrerStatistics
summary: Get referrer statistics
description: Get statistics broken down by referrer
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: offset
in: query
schema:
type: integer
- name: limit
in: query
schema:
type: integer
responses:
'200':
description: Referrer statistics
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ReferrerStats'
/statistics/channel:
get:
operationId: getChannelStatistics
summary: Get traffic channel statistics
description: Get statistics grouped by traffic channel
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Channel statistics
content:
application/json:
schema:
type: array
items:
type: object
/statistics/utm/source:
get:
operationId: getUtmSourceStatistics
summary: Get UTM source statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: UTM source breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/utm/medium:
get:
operationId: getUtmMediumStatistics
summary: Get UTM medium statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: UTM medium breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/utm/campaign:
get:
operationId: getUtmCampaignStatistics
summary: Get UTM campaign statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: UTM campaign breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/utm/content:
get:
operationId: getUtmContentStatistics
summary: Get UTM content statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: UTM content breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/utm/term:
get:
operationId: getUtmTermStatistics
summary: Get UTM term statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: UTM term breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/country:
get:
operationId: getCountryStatistics
summary: Get country statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Country breakdown
content:
application/json:
schema:
type: array
items:
type: object
properties:
country:
type: string
visitors:
type: integer
relative_visitors:
type: number
/statistics/region:
get:
operationId: getRegionStatistics
summary: Get region statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Region breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/city:
get:
operationId: getCityStatistics
summary: Get city statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: City breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/language:
get:
operationId: getLanguageStatistics
summary: Get language statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Language breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/browser:
get:
operationId: getBrowserStatistics
summary: Get browser statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Browser breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/os:
get:
operationId: getOsStatistics
summary: Get operating system statistics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: OS breakdown
content:
application/json:
schema:
type: array
items:
type: object
/statistics/platform:
get:
operationId: getPlatformStatistics
summary: Get platform statistics
description: Get breakdown between desktop, mobile, and unknown platforms
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Platform statistics
content:
application/json:
schema:
$ref: '#/components/schemas/PlatformStats'
/statistics/events:
get:
operationId: getEventStatistics
summary: Get event list and statistics
description: Get list of tracked events with visitor counts and metadata keys
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Event statistics
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EventStats'
/statistics/goals:
get:
operationId: getGoalStatistics
summary: Get conversion goal statistics
description: Get statistics for all configured conversion goals
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Goal statistics
content:
application/json:
schema:
type: array
items:
type: object
/statistics/funnel:
get:
operationId: getFunnelStatistics
summary: Get funnel statistics
description: Get step-by-step funnel analytics
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: funnel_id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Funnel analytics
content:
application/json:
schema:
type: object
/statistics/active:
get:
operationId: getActiveVisitors
summary: Get active visitors
description: Get current real-time active visitor count
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: start
in: query
schema:
type: integer
default: 600
description: Number of seconds to consider a visitor active
responses:
'200':
description: Active visitor data
content:
application/json:
schema:
$ref: '#/components/schemas/ActiveVisitors'
/statistics/session/list:
get:
operationId: getSessionList
summary: Get session list
description: Get list of individual visitor sessions
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
- name: offset
in: query
schema:
type: integer
- name: limit
in: query
schema:
type: integer
responses:
'200':
description: Session list
content:
application/json:
schema:
type: array
items:
type: object
/statistics/session/details:
get:
operationId: getSessionDetails
summary: Get session details
description: Get page-by-page breakdown of a single session
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: visitor_id
in: query
required: true
schema:
type: string
- name: session_id
in: query
required: true
schema:
type: string
responses:
'200':
description: Session details
content:
application/json:
schema:
type: array
items:
type: object
/statistics/growth:
get:
operationId: getGrowthStatistics
summary: Get growth statistics
description: Get growth rate metrics comparing the current period to the previous
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Growth rates
content:
application/json:
schema:
type: object
/statistics/keywords:
get:
operationId: getKeywords
summary: Get Google Search Console keywords
description: Get keyword data sourced from Google Search Console integration
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: Keyword data
content:
application/json:
schema:
type: array
items:
type: object
/statistics:
get:
operationId: exportStatistics
summary: Export statistics as CSV
description: Download a ZIP archive of CSV exports for the selected date range
tags:
- Statistics
parameters:
- name: id
in: query
required: true
schema:
type: string
- name: from
in: query
required: true
schema:
type: string
format: date
- name: to
in: query
required: true
schema:
type: string
format: date
responses:
'200':
description: ZIP file with CSV exports
content:
application/zip:
schema:
type: string
format: binary
delete:
operationId: deleteStatistics
summary: Delete statistics
description: Delete all or partial statistics for a domain
tags:
- Statistics
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- id
properties:
id:
type: string
description: Domain ID
kind:
type: string
enum:
- ''
- all
- events
- imported
from:
type: string
format: date
to:
type: string
format: date
responses:
'200':
description: Statistics deleted
components:
schemas:
PageStats:
type: object
properties:
path:
type: string
title:
type: string
visitors:
type: integer
views:
type: integer
sessions:
type: integer
bounces:
type: integer
relative_visitors:
type: number
format: float
relative_views:
type: number
format: float
bounce_rate:
type: number
format: float
average_time_spent_seconds:
type: integer
EventStats:
type: object
properties:
name:
type: string
count:
type: integer
visitors:
type: integer
views:
type: integer
cr:
type: number
format: float
average_duration_seconds:
type: integer
meta_keys:
type: array
items:
type: string
TotalStats:
type: object
properties:
visitors:
type: integer
views:
type: integer
sessions:
type: integer
bounces:
type: integer
bounce_rate:
type: number
format: float
cr:
type: number
format: float
custom_metric_avg:
type: number
format: float
custom_metric_total:
type: number
format: float
VisitorStats:
type: object
properties:
day:
type: string
format: date-time
week:
type: string
format: date-time
month:
type: string
format: date-time
year:
type: string
format: date-time
visitors:
type: integer
views:
type: integer
sessions:
type: integer
bounces:
type: integer
bounce_rate:
type: number
format: float
cr:
type: number
format: float
custom_metric_avg:
type: number
format: float
custom_metric_total:
type: number
format: float
ActiveVisitors:
type: object
properties:
stats:
type: array
items:
type: object
countries:
type: array
items:
type: object
visitors:
type: integer
ReferrerStats:
type: object
properties:
referrer:
type: string
referrer_name:
type: string
referrer_icon:
type: string
visitors:
type: integer
sessions:
type: integer
relative_visitors:
type: number
format: float
bounces:
type: integer
bounce_rate:
type: number
format: float
PlatformStats:
type: object
properties:
platform_desktop:
type: integer
platform_mobile:
type: integer
platform_unknown:
type: integer
relative_platform_desktop:
type: number
format: float
relative_platform_mobile:
type: number
format: float
relative_platform_unknown:
type: number
format: float
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Pass an OAuth2 access token obtained from POST /token, or a static access key, as a Bearer token in the Authorization header.