Analytics REST API
The Privatus analytics REST API: add .json to any app URL and send a token. Read the conventions and a reference of every operation, generated from the code.
Every page and action in Privatus is also an API endpoint. There's no
separate /api/v1: add .json to a URL and send an API token.
sh
curl https://privatusanalytics.com/sites/pa_7Q2K9XH3AB/stats/aggregate.json?period=7d \
-H "Authorization: Bearer $PRIVATUS_TOKEN"
json
{
"data": {
"period": { "from": "2026-09-23T00:00:00Z", "to": "2026-09-30T00:00:00Z" },
"metrics": {
"visitors": 1840, "visits": 2310, "pageviews": 5122,
"views_per_visit": 2.22, "bounce_rate": 41.3,
"visit_duration": 48000, "revenue": 129900
}
}
}
The reference below lists every operation with its method, path, permission, input schema and response schema. It's generated from the running code, as is the OpenAPI 3.1 document, so neither can drift from what the server does. The same operations are MCP tools.
Conventions#
| Base URL | https://privatusanalytics.com |
| Format | JSON. Add .json to the path (or send Accept: application/json) |
| Auth | Authorization: Bearer pat_… (Authentication) |
| Ids | Public ids with a prefix: ws_… workspaces, pa_… sites, seg_… segments, wh_… webhooks |
| Reads | GET with query parameters |
| Writes | POST, PATCH, DELETE with a JSON body of flat fields |
| Success | { "data": … }, plus "meta" for lists |
| Errors | { "error": { "code", "message", "details" } } (Errors) |
| Lists | page and per_page (max 100) (Pagination) |
| Times | ISO 8601 in UTC. Date parameters (from, to) are days in the site's timezone |
| Money | Minor units (cents) in the site currency, e.g. revenue: 129900 = 1,299.00 |
| Durations | Milliseconds |
Common tasks#
| Task | Operation |
|---|---|
| List workspaces | GET /workspaces.json |
| List sites | GET /workspaces/{workspace_id}/sites.json |
| Headline metrics | GET /sites/{site_id}/stats/aggregate.json |
| Chart data | GET /sites/{site_id}/stats/timeseries.json |
| Top pages, sources, countries… | GET /sites/{site_id}/breakdown/{dimension}.json |
| Everything on the Overview | GET /sites/{site_id}/overview.json |
| Live visitors | GET /sites/{site_id}/live.json |
| Add a note (e.g. a deploy) | POST /sites/{site_id}/notes.json |
See Stats endpoints and Examples.
In this section#
Authentication · Errors · Pagination · Rate limits · Filters · Stats endpoints · Examples · Webhooks · Changelog and deprecation
Sending data in is a different API: see Server-side ingest.
Every operation
Authentication
Send Authorization: Bearer pat_…. Create tokens under Workspace settings, API tokens. Authentication guide.
JSON everywhere
Add .json to any path. Responses are { "data": … } and errors are { "error": { "code", "message" } }. Errors.
MCP
POST JSON-RPC to https://privatusanalytics.com/mcp with the same token. Each operation below is a tool. MCP guide.
Download openapi.json · 279 operations
API tokens
POST
/workspaces/:workspace_id/api_tokens.json
Create an API token (the token is returned once)
api_tokens_create
Permission: member
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/api_tokens.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "A name to recognize the token by",
"examples": [
"CI deploys"
]
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"analytics.read",
"analytics.export",
"content.write",
"sites.manage",
"uptime.manage",
"members.manage",
"tokens.manage",
"billing.manage",
"workspace.manage"
]
},
"description": "Permissions (omit for all of yours, an empty list is refused)"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Restrict to these site ids (pa_…). Empty = all",
"default": []
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Expiry time (ISO 8601). Empty = never"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only accept requests from these IPs/CIDRs",
"default": []
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"token": {
"anyOf": [
{
"type": "string",
"description": "The token itself: only returned when created"
},
{
"type": "null"
}
]
},
"token_prefix": {
"type": "string",
"description": "First characters, to recognize the token"
},
"owner": {
"type": "string",
"description": "Email of the member who owns it"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Restricted to these sites (empty = all)"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
}
},
"oauth_client": {
"anyOf": [
{
"type": "string",
"description": "MCP client that received it"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "active, expired or revoked"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/api_tokens/:id.json
Revoke an API token
api_tokens_delete
Permission: member
Example
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/api_tokens/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"token": {
"anyOf": [
{
"type": "string",
"description": "The token itself: only returned when created"
},
{
"type": "null"
}
]
},
"token_prefix": {
"type": "string",
"description": "First characters, to recognize the token"
},
"owner": {
"type": "string",
"description": "Email of the member who owns it"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Restricted to these sites (empty = all)"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
}
},
"oauth_client": {
"anyOf": [
{
"type": "string",
"description": "MCP client that received it"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "active, expired or revoked"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/api_tokens.json
List API tokens
api_tokens_list
Permission: member
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/api_tokens.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"include_revoked": {
"type": "boolean",
"description": "Also list revoked and expired tokens",
"default": false
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"token": {
"anyOf": [
{
"type": "string",
"description": "The token itself: only returned when created"
},
{
"type": "null"
}
]
},
"token_prefix": {
"type": "string",
"description": "First characters, to recognize the token"
},
"owner": {
"type": "string",
"description": "Email of the member who owns it"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Restricted to these sites (empty = all)"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
}
},
"oauth_client": {
"anyOf": [
{
"type": "string",
"description": "MCP client that received it"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "active, expired or revoked"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
Account
GET
/account.json
Get your profile and preferences
account_get
Permission: member
Example
curl https://privatusanalytics.com/account.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {},
"required": []
}
Response data
{
"type": "object",
"properties": {
"email": {
"type": "string"
},
"unconfirmed_email": {
"anyOf": [
{
"type": "string",
"description": "New email awaiting confirmation"
},
{
"type": "null"
}
]
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"theme": {
"type": "string"
},
"default_landing": {
"type": "string"
},
"locale": {
"type": "string",
"description": "Language code of the app for this account (en by default)"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"shortcuts_enabled": {
"type": "boolean"
},
"reduce_motion": {
"type": "boolean"
},
"product_emails": {
"type": "boolean"
},
"marketing_emails": {
"type": "boolean",
"description": "Whether marketing emails (drip campaigns) may be sent. false after an unsubscribe"
},
"newsletter": {
"type": "boolean"
},
"two_factor": {
"type": "boolean"
},
"passkeys": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/account.json
Update your profile and preferences
account_update
Permission: member
Example
curl -X PATCH https://privatusanalytics.com/account.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Your name"
},
"email": {
"type": "string",
"description": "New email address (confirmed by email first)"
},
"theme": {
"type": "string",
"description": "Color theme",
"enum": [
"system",
"light",
"dark"
]
},
"default_landing": {
"type": "string",
"description": "Page after login: sites or last_site",
"enum": [
"sites",
"last_site"
]
},
"locale": {
"type": "string",
"description": "Language of the app when you are signed in, as a language code (en, de, fr and so on). Public pages and the API stay as they are",
"enum": [
"en",
"de",
"es",
"fr",
"it",
"nl",
"pt",
"pl",
"sv",
"da",
"no",
"fi",
"ja",
"ko",
"zh-CN",
"zh-TW"
]
},
"timezone": {
"type": "string",
"description": "Your timezone (IANA name)"
},
"shortcuts_enabled": {
"type": "boolean",
"description": "Keyboard shortcuts"
},
"reduce_motion": {
"type": "boolean",
"description": "Reduce animations"
},
"product_emails": {
"type": "boolean",
"description": "Product update and tips emails"
},
"marketing_emails": {
"type": "boolean",
"description": "Marketing emails such as onboarding tips. Turning them back on after an unsubscribe needs a signed-in browser"
},
"newsletter": {
"type": "boolean",
"description": "Monthly newsletter"
}
},
"required": []
}
Response data
{
"type": "object",
"properties": {
"email": {
"type": "string"
},
"unconfirmed_email": {
"anyOf": [
{
"type": "string",
"description": "New email awaiting confirmation"
},
{
"type": "null"
}
]
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"theme": {
"type": "string"
},
"default_landing": {
"type": "string"
},
"locale": {
"type": "string",
"description": "Language code of the app for this account (en by default)"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"shortcuts_enabled": {
"type": "boolean"
},
"reduce_motion": {
"type": "boolean"
},
"product_emails": {
"type": "boolean"
},
"marketing_emails": {
"type": "boolean",
"description": "Whether marketing emails (drip campaigns) may be sent. false after an unsubscribe"
},
"newsletter": {
"type": "boolean"
},
"two_factor": {
"type": "boolean"
},
"passkeys": {
"type": "integer"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Affiliate program
GET
/account/affiliate/commissions.json
List your affiliate commissions
affiliate_commissions_list
Commissions, refund and chargeback clawbacks and reversals, newest first. Amounts are in cents.
Permission: member
Example
curl https://privatusanalytics.com/account/affiliate/commissions.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Only commissions with this status",
"enum": [
"pending",
"approved",
"paid",
"void"
]
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": []
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Commission id"
},
"kind": {
"type": "string",
"description": "commission, clawback (refund or chargeback) or reversal"
},
"status": {
"type": "string",
"description": "pending (on hold), approved (payable), paid or void"
},
"amount_cents": {
"type": "integer",
"description": "Your share in cents (negative for a clawback)"
},
"basis_cents": {
"type": "integer",
"description": "The net payment (excluding tax) it was calculated from, in cents"
},
"currency": {
"type": "string",
"description": "ISO currency code"
},
"earned_at": {
"type": "string",
"format": "date-time",
"description": "When the payment (or refund) happened"
},
"approved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When it became payable"
},
{
"type": "null"
}
]
},
"paid_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When it was paid out"
},
{
"type": "null"
}
]
}
}
}
}
GET
/account/affiliate.json
Get your affiliate status, referral link and stats
affiliate_get
Your affiliate application status, referral link, signups and paying customers you referred, and balances per currency (on hold, payable, paid). status is none when you have not applied.
Permission: member
Example
curl https://privatusanalytics.com/account/affiliate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {},
"required": []
}
Response data
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "none (not applied), pending, approved, rejected or suspended"
},
"code": {
"anyOf": [
{
"type": "string",
"description": "Your referral code"
},
{
"type": "null"
}
]
},
"referral_url": {
"anyOf": [
{
"type": "string",
"description": "The link to share (approved affiliates only)"
},
{
"type": "null"
}
]
},
"payout_method": {
"anyOf": [
{
"type": "string",
"description": "wise or credit"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "Why the last application was rejected"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When you applied"
},
{
"type": "null"
}
]
},
"approved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the application was approved"
},
{
"type": "null"
}
]
},
"credit_blocked": {
"anyOf": [
{
"type": "string",
"description": "Why account credit is waiting: program (the workspace is in a discount program), no_subscription or no_workspace. null when nothing blocks it"
},
{
"type": "null"
}
]
},
"signups": {
"type": "integer",
"description": "Accounts created through your link or code"
},
"customers": {
"type": "integer",
"description": "Referred workspaces that have paid"
},
"balances": {
"type": "array",
"description": "Per currency: pending_cents (on hold), approved_cents (payable) and paid_cents"
},
"payouts": {
"type": "array",
"description": "Recent payouts with amount_cents, currency, payout_method, status (applied: account credit waiting for your next renewal, or paid), applied_at and paid_at"
},
"terms": {
"type": "object",
"description": "Commission percent, months, hold days and the Wise payout threshold in cents"
}
}
}
Alerts
POST
/alerts/:id/acknowledge.json
Acknowledge the latest incident
alerts_acknowledge
Permission: analytics.read
Example
curl -X POST https://privatusanalytics.com/alerts/:id/acknowledge.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Alert id, e.g. alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id (null for usage alerts)"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold, anomaly, goal, no_data, usage, uptime, ssl or vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt, gte, lt or lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly sensitivity"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channel ids"
},
"state": {
"type": "string",
"description": "ok or triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/alerts.json
Create an alert
alerts_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/alerts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id (pa_…). Required except for usage alerts"
},
"metric": {
"type": "string",
"description": "threshold/anomaly: visitors, visits, pageviews, bounce_rate or conversion. vitals: lcp, inp, cls, fcp or ttfb"
},
"operator": {
"type": "string",
"description": "Comparison (gt, gte, lt, lte). anomaly: lt only drops, gt only spikes, empty both",
"enum": [
"gt",
"gte",
"lt",
"lte"
]
},
"threshold": {
"type": "number",
"description": "threshold: metric value, goal: completions, no_data: hours, usage: percent, ssl: days, vitals: ms (CLS: score)"
},
"window_minutes": {
"type": "integer",
"description": "Evaluation window in minutes (5 to 10080)"
},
"sensitivity": {
"type": "string",
"description": "anomaly: low, medium or high",
"enum": [
"low",
"medium",
"high"
]
},
"goal_id": {
"type": "string",
"description": "goal and conversion alerts: goal id (goal_…)"
},
"uptime_check_id": {
"type": "string",
"description": "uptime/ssl: check id (default: all the site's checks)"
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channel ids (nch_…)"
},
"enabled": {
"type": "boolean",
"description": "Evaluate this alert"
},
"name": {
"type": "string",
"description": "Alert name",
"examples": [
"Traffic dropped"
]
},
"kind": {
"type": "string",
"description": "threshold, anomaly, goal, no_data, usage, uptime, ssl or vitals",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"kind",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Alert id, e.g. alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id (null for usage alerts)"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold, anomaly, goal, no_data, usage, uptime, ssl or vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt, gte, lt or lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly sensitivity"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channel ids"
},
"state": {
"type": "string",
"description": "ok or triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/alerts/:id.json
Delete an alert
alerts_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/alerts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Alert id, e.g. alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id (null for usage alerts)"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold, anomaly, goal, no_data, usage, uptime, ssl or vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt, gte, lt or lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly sensitivity"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channel ids"
},
"state": {
"type": "string",
"description": "ok or triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/alerts/:id/history.json
Incident history of an alert
alerts_history
Permission: analytics.read
Example
curl https://privatusanalytics.com/alerts/:id/history.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"open": {
"type": "boolean",
"description": "Only unresolved incidents",
"default": false
},
"id": {
"type": "string",
"description": "Id of the resource"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"triggered_at": {
"type": "string",
"format": "date-time"
},
"resolved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"value": {
"anyOf": [
{
"type": "number",
"description": "Measured value when triggered"
},
{
"type": "null"
}
]
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"acknowledged_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"acknowledged_by": {
"anyOf": [
{
"type": "string",
"description": "Name of the member who acknowledged"
},
{
"type": "null"
}
]
}
}
}
}
GET
/workspaces/:workspace_id/alerts.json
List alerts
alerts_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/alerts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Only alerts for this site (pa_…)"
},
"state": {
"type": "string",
"description": "Only ok or triggered alerts",
"enum": [
"ok",
"triggered"
]
},
"kind": {
"type": "string",
"description": "Only this kind",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Alert id, e.g. alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id (null for usage alerts)"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold, anomaly, goal, no_data, usage, uptime, ssl or vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt, gte, lt or lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly sensitivity"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channel ids"
},
"state": {
"type": "string",
"description": "ok or triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/alerts/:id/mute.json
Mute (or unmute) an alert’s notifications
alerts_mute
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/alerts/:id/mute.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"minutes": {
"type": "integer",
"description": "Mute for this many minutes (0 unmutes, max 30 days)",
"default": 60
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Alert id, e.g. alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id (null for usage alerts)"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold, anomaly, goal, no_data, usage, uptime, ssl or vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt, gte, lt or lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly sensitivity"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channel ids"
},
"state": {
"type": "string",
"description": "ok or triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/alerts/:id.json
Get an alert
alerts_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/alerts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Alert id, e.g. alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id (null for usage alerts)"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold, anomaly, goal, no_data, usage, uptime, ssl or vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt, gte, lt or lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly sensitivity"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channel ids"
},
"state": {
"type": "string",
"description": "ok or triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/alerts/:id.json
Update an alert
alerts_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/alerts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id (pa_…). Required except for usage alerts"
},
"metric": {
"type": "string",
"description": "threshold/anomaly: visitors, visits, pageviews, bounce_rate or conversion. vitals: lcp, inp, cls, fcp or ttfb"
},
"operator": {
"type": "string",
"description": "Comparison (gt, gte, lt, lte). anomaly: lt only drops, gt only spikes, empty both",
"enum": [
"gt",
"gte",
"lt",
"lte"
]
},
"threshold": {
"type": "number",
"description": "threshold: metric value, goal: completions, no_data: hours, usage: percent, ssl: days, vitals: ms (CLS: score)"
},
"window_minutes": {
"type": "integer",
"description": "Evaluation window in minutes (5 to 10080)"
},
"sensitivity": {
"type": "string",
"description": "anomaly: low, medium or high",
"enum": [
"low",
"medium",
"high"
]
},
"goal_id": {
"type": "string",
"description": "goal and conversion alerts: goal id (goal_…)"
},
"uptime_check_id": {
"type": "string",
"description": "uptime/ssl: check id (default: all the site's checks)"
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channel ids (nch_…)"
},
"enabled": {
"type": "boolean",
"description": "Evaluate this alert"
},
"name": {
"type": "string",
"description": "Alert name"
},
"kind": {
"type": "string",
"description": "Alert kind",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Alert id, e.g. alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id (null for usage alerts)"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold, anomaly, goal, no_data, usage, uptime, ssl or vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt, gte, lt or lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly sensitivity"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channel ids"
},
"state": {
"type": "string",
"description": "ok or triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/alerts.json
List alerts for a site
site_alerts_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/alerts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"state": {
"type": "string",
"description": "Only ok or triggered alerts",
"enum": [
"ok",
"triggered"
]
},
"kind": {
"type": "string",
"description": "Only this kind",
"enum": [
"threshold",
"anomaly",
"goal",
"no_data",
"usage",
"uptime",
"ssl",
"vitals"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Alert id, e.g. alr_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id (null for usage alerts)"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "threshold, anomaly, goal, no_data, usage, uptime, ssl or vitals"
},
"metric": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"operator": {
"anyOf": [
{
"type": "string",
"description": "gt, gte, lt or lte"
},
{
"type": "null"
}
]
},
"threshold": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"window_minutes": {
"type": "integer"
},
"sensitivity": {
"type": "string",
"description": "anomaly sensitivity"
},
"goal_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"channel_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notification channel ids"
},
"state": {
"type": "string",
"description": "ok or triggered"
},
"enabled": {
"type": "boolean"
},
"muted_until": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_triggered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_evaluated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
Analytics
GET
/sites/:site_id/overview.json
Site overview: metrics, chart series, top panels, live visitors and notes
stats_overview
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/overview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"interval": {
"type": "string",
"description": "Chart bucket size",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"panels": {
"type": "array",
"items": {
"type": "string"
},
"description": "Dimensions to include top values for",
"default": [
"channel",
"referrer",
"page",
"entry_page",
"country",
"device",
"browser",
"os",
"utm_campaign",
"event",
"goal"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/experiments.json
Experiment report: conversion rate per variant, uplift vs control and significance (two-proportion z-test)
experiments_report
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/experiments.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"property": {
"type": "string",
"description": "Event property holding the variant, e.g. variant",
"examples": [
"variant"
]
},
"goal_id": {
"type": "string",
"description": "Goal counted as a conversion (goal_…)"
},
"control": {
"type": "string",
"description": "Control variant (defaults to \"control\" if present, else the variant with most visits)"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"property",
"goal_id",
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/insights.json
Notable changes vs the previous period, in plain English (biggest movers, goal conversion changes)
insights_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/insights.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Complete days up to yesterday, compared with the same number of days before",
"enum": [
"7d",
"14d",
"28d",
"30d"
],
"default": "7d"
},
"limit": {
"type": "integer",
"description": "Maximum number of insights (1 to 20)",
"default": 8
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/journeys.json
Journeys: top 3-step paths after a page (or any entrance), or before a page or goal
journeys_explore
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/journeys.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"mode": {
"type": "string",
"description": "forward: pages after the start page, reverse: pages leading to the end page or goal",
"enum": [
"forward",
"reverse"
],
"default": "forward"
},
"path": {
"type": "string",
"description": "Start page (forward) or end page (reverse). Blank means any entrance (forward only)"
},
"goal_id": {
"type": "string",
"description": "Reverse mode: end at this goal (goal_…) instead of a page"
},
"limit": {
"type": "integer",
"description": "Pages shown per step (max 12)",
"default": 6
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/pages/detail.json
Page detail: metrics, previous and next pages, sources, Web Vitals, events and click map for one path
pages_detail
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/pages/detail.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"path": {
"type": "string",
"description": "Page path, e.g. /pricing",
"examples": [
"/pricing"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"path",
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/stats/aggregate.json
Headline metrics for a period (with comparison)
stats_aggregate
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/stats/aggregate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/breakdown/:dimension.json
Top values of a dimension (pages, sources, countries…)
stats_breakdown
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/breakdown/:dimension.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"dimension": {
"type": "string",
"description": "Dimension of the resource"
},
"limit": {
"type": "integer",
"description": "Rows per page (max 1000)",
"default": 10
},
"page": {
"type": "integer",
"description": "Page number",
"default": 1
},
"sort": {
"type": "string",
"description": "Sort metric",
"enum": [
"visitors",
"visits",
"pageviews",
"revenue"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"dimension",
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/stats/timeseries.json
Metrics per time bucket for charts
stats_timeseries
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/stats/timeseries.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"interval": {
"type": "string",
"description": "Bucket size. auto picks one for the range",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
Assistant
POST
/sites/:site_id/ask.json
Ask a question in a new conversation (counts toward the monthly AI questions limit)
assistant_ask
Permission: analytics.read
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/ask.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "Your first question in plain English",
"examples": [
"How many visitors did we have last week?"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"question",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Conversation id, e.g. ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "The first question, shortened"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Time of the last message"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Deleted automatically after this time (30 days after the last message)"
},
"messages": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Message id within the conversation"
},
"role": {
"type": "string",
"description": "user (the question) or assistant (the answer)"
},
"content": {
"type": "string",
"description": "Question, or the answer in Markdown"
},
"queries": {
"type": "array",
"items": {
"type": "object"
},
"description": "How I got this: the exact API queries behind the answer, as [{tool, input, status, error}]"
},
"chart": {
"anyOf": [
{
"type": "object",
"description": "Chart of the answer: {type: line, labels, series, comparison, metric, format} or {type: table, columns, rows}"
},
{
"type": "null"
}
]
},
"goal_draft": {
"anyOf": [
{
"type": "object",
"description": "A goal proposed by the assistant, to confirm with goals_create"
},
{
"type": "null"
}
]
},
"input_tokens": {
"anyOf": [
{
"type": "integer",
"description": "Model input tokens used"
},
{
"type": "null"
}
]
},
"output_tokens": {
"anyOf": [
{
"type": "integer",
"description": "Model output tokens used"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"description": "Questions and answers, oldest first"
}
}
}
DELETE
/sites/:site_id/ask/:id.json
Delete an Ask conversation and its messages
assistant_conversations_delete
Permission: analytics.read
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/ask/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Conversation id, e.g. ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "The first question, shortened"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Time of the last message"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Deleted automatically after this time (30 days after the last message)"
}
}
}
GET
/sites/:site_id/ask.json
List your Ask conversations for a site
assistant_conversations_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/ask.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Conversation id, e.g. ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "The first question, shortened"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Time of the last message"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Deleted automatically after this time (30 days after the last message)"
}
}
}
}
GET
/sites/:site_id/ask/:id.json
An Ask conversation: questions, answers, the queries behind them and charts
assistant_conversations_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/ask/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Conversation id, e.g. ask_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site id"
},
{
"type": "null"
}
]
},
"title": {
"anyOf": [
{
"type": "string",
"description": "The first question, shortened"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Time of the last message"
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Deleted automatically after this time (30 days after the last message)"
},
"messages": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Message id within the conversation"
},
"role": {
"type": "string",
"description": "user (the question) or assistant (the answer)"
},
"content": {
"type": "string",
"description": "Question, or the answer in Markdown"
},
"queries": {
"type": "array",
"items": {
"type": "object"
},
"description": "How I got this: the exact API queries behind the answer, as [{tool, input, status, error}]"
},
"chart": {
"anyOf": [
{
"type": "object",
"description": "Chart of the answer: {type: line, labels, series, comparison, metric, format} or {type: table, columns, rows}"
},
{
"type": "null"
}
]
},
"goal_draft": {
"anyOf": [
{
"type": "object",
"description": "A goal proposed by the assistant, to confirm with goals_create"
},
{
"type": "null"
}
]
},
"input_tokens": {
"anyOf": [
{
"type": "integer",
"description": "Model input tokens used"
},
{
"type": "null"
}
]
},
"output_tokens": {
"anyOf": [
{
"type": "integer",
"description": "Model output tokens used"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
},
"description": "Questions and answers, oldest first"
}
}
}
POST
/sites/:site_id/ask/:ask_conversation_id/messages.json
Ask a follow-up question in a conversation (counts toward the monthly AI questions limit). Returns the answer.
assistant_ask_followup
Permission: analytics.read
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/ask/:ask_conversation_id/messages.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "Your question in plain English",
"examples": [
"Which pages had the most visitors last week?"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"ask_conversation_id": {
"type": "string",
"description": "Ask conversation of the resource"
}
},
"required": [
"question",
"site_id",
"ask_conversation_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Message id within the conversation"
},
"role": {
"type": "string",
"description": "user (the question) or assistant (the answer)"
},
"content": {
"type": "string",
"description": "Question, or the answer in Markdown"
},
"queries": {
"type": "array",
"items": {
"type": "object"
},
"description": "How I got this: the exact API queries behind the answer, as [{tool, input, status, error}]"
},
"chart": {
"anyOf": [
{
"type": "object",
"description": "Chart of the answer: {type: line, labels, series, comparison, metric, format} or {type: table, columns, rows}"
},
{
"type": "null"
}
]
},
"goal_draft": {
"anyOf": [
{
"type": "object",
"description": "A goal proposed by the assistant, to confirm with goals_create"
},
{
"type": "null"
}
]
},
"input_tokens": {
"anyOf": [
{
"type": "integer",
"description": "Model input tokens used"
},
{
"type": "null"
}
]
},
"output_tokens": {
"anyOf": [
{
"type": "integer",
"description": "Model output tokens used"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Audit log
GET
/workspaces/:workspace_id/audit_log.json
List audit log entries (add .csv to export)
audit_logs_get
Permission: workspace.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/audit_log.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"actor": {
"type": "string",
"description": "Only changes by this member (email)"
},
"item_type": {
"type": "string",
"description": "Only this kind of record, e.g. Site"
},
"event": {
"type": "string",
"description": "Only this action",
"enum": [
"create",
"update",
"destroy"
]
},
"from": {
"type": "string",
"format": "date",
"description": "From date (inclusive)"
},
"to": {
"type": "string",
"format": "date",
"description": "To date (inclusive)"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When"
},
"event": {
"type": "string",
"description": "create, update or destroy"
},
"item_type": {
"type": "string",
"description": "Kind of record, e.g. Site"
},
"item_id": {
"type": "string",
"format": "uuid"
},
"target": {
"type": "string",
"description": "The record, by name where known"
},
"actor_email": {
"anyOf": [
{
"type": "string",
"description": "Member who made the change"
},
{
"type": "null"
}
]
},
"actor_name": {
"type": "string"
},
"token_name": {
"anyOf": [
{
"type": "string",
"description": "API token used, if any"
},
{
"type": "null"
}
]
},
"changes": {
"type": "object",
"description": "Changed fields: { field: [before, after] }"
},
"ip": {
"anyOf": [
{
"type": "string",
"description": "The member's IP address"
},
{
"type": "null"
}
]
}
}
}
}
Billing
POST
/workspaces/:workspace_id/billing/badge.json
Opt in or out of the badge bonus (free plan)
billing_badge
Permission: billing.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/badge.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "true to verify the badge and earn the bonus"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"enabled",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events a month in the paid tier"
},
"allowance": {
"type": "integer",
"description": "Events a month including any badge bonus"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month or year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "USD per billing interval"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none, trialing, active, past_due, paused or canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Renews or ends at"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit, education, open_source, open_source_free or agency"
},
"status": {
"type": "string",
"description": "pending, approved (not yet on the subscription), active, rejected or revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business (null for the free open-source program)"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "Free events a month (free open-source program only)"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "Organization, school, project or agency name"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "Website"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "Proof link or repository URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI license (open source)"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "Note for the review"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "Why the application was not approved"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Applied at"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Reviewed at"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Discount active since"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Program ended at"
},
{
"type": "null"
}
]
}
},
"description": "The latest discount program application, or null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business from an approved program, or null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "Badge bonus (free plan)"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "First day of the month reported"
},
"events": {
"type": "integer",
"description": "Billable events (pageviews and custom events)"
},
"bots": {
"type": "integer",
"description": "Bot hits filtered out (not billed)"
},
"allowance": {
"type": "integer",
"description": "Events included, with any badge bonus"
},
"percent": {
"type": "number",
"description": "Events as a percent of the allowance"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "Projected events at month end"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "Days left in the month"
},
"status": {
"type": "string",
"description": "ok, warning (80%+), over (a past month at or over the allowance), locked or paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "Pageviews and custom events this month"
},
"share": {
"type": "number",
"description": "Percent of the workspace total"
}
}
},
"description": "Events by site"
},
"history": {
"type": "array",
"description": "Previous months, newest first"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Dashboards locked by Privatus staff since"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "True while new events are dropped (the monthly limit is reached, or staff paused collection)"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "Why collection is paused: limit (the monthly allowance is reached) or staff. null when collecting"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When staff paused collection"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a limit pause lifts: the start of next month (UTC), or earlier on an upgrade. null otherwise"
},
{
"type": "null"
}
]
}
},
"description": "This month so far"
}
}
}
POST
/workspaces/:workspace_id/billing/cancel.json
Cancel at the end of the billing period
billing_cancel
Permission: billing.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/cancel.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Main reason for canceling (optional survey)",
"enum": [
"too_expensive",
"missing_features",
"switching_tool",
"not_using",
"temporary",
"other"
]
},
"comment": {
"type": "string",
"description": "Anything we could do better"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events a month in the paid tier"
},
"allowance": {
"type": "integer",
"description": "Events a month including any badge bonus"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month or year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "USD per billing interval"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none, trialing, active, past_due, paused or canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Renews or ends at"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit, education, open_source, open_source_free or agency"
},
"status": {
"type": "string",
"description": "pending, approved (not yet on the subscription), active, rejected or revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business (null for the free open-source program)"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "Free events a month (free open-source program only)"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "Organization, school, project or agency name"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "Website"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "Proof link or repository URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI license (open source)"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "Note for the review"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "Why the application was not approved"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Applied at"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Reviewed at"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Discount active since"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Program ended at"
},
{
"type": "null"
}
]
}
},
"description": "The latest discount program application, or null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business from an approved program, or null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "Badge bonus (free plan)"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "First day of the month reported"
},
"events": {
"type": "integer",
"description": "Billable events (pageviews and custom events)"
},
"bots": {
"type": "integer",
"description": "Bot hits filtered out (not billed)"
},
"allowance": {
"type": "integer",
"description": "Events included, with any badge bonus"
},
"percent": {
"type": "number",
"description": "Events as a percent of the allowance"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "Projected events at month end"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "Days left in the month"
},
"status": {
"type": "string",
"description": "ok, warning (80%+), over (a past month at or over the allowance), locked or paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "Pageviews and custom events this month"
},
"share": {
"type": "number",
"description": "Percent of the workspace total"
}
}
},
"description": "Events by site"
},
"history": {
"type": "array",
"description": "Previous months, newest first"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Dashboards locked by Privatus staff since"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "True while new events are dropped (the monthly limit is reached, or staff paused collection)"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "Why collection is paused: limit (the monthly allowance is reached) or staff. null when collecting"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When staff paused collection"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a limit pause lifts: the start of next month (UTC), or earlier on an upgrade. null otherwise"
},
{
"type": "null"
}
]
}
},
"description": "This month so far"
}
}
}
POST
/workspaces/:workspace_id/billing/change_plan.json
Change plan, tier or interval (prorated)
billing_change_plan
Permission: billing.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/change_plan.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "Plan to switch to: pro or business",
"enum": [
"pro",
"business"
]
},
"events": {
"type": "integer",
"description": "Events a month of the tier, from GET /plans",
"examples": [
1000000
]
},
"interval": {
"type": "string",
"description": "Billing interval. Yearly is 2 months free",
"enum": [
"month",
"year"
],
"default": "month"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"plan",
"events",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events a month in the paid tier"
},
"allowance": {
"type": "integer",
"description": "Events a month including any badge bonus"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month or year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "USD per billing interval"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none, trialing, active, past_due, paused or canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Renews or ends at"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit, education, open_source, open_source_free or agency"
},
"status": {
"type": "string",
"description": "pending, approved (not yet on the subscription), active, rejected or revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business (null for the free open-source program)"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "Free events a month (free open-source program only)"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "Organization, school, project or agency name"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "Website"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "Proof link or repository URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI license (open source)"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "Note for the review"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "Why the application was not approved"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Applied at"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Reviewed at"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Discount active since"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Program ended at"
},
{
"type": "null"
}
]
}
},
"description": "The latest discount program application, or null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business from an approved program, or null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "Badge bonus (free plan)"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "First day of the month reported"
},
"events": {
"type": "integer",
"description": "Billable events (pageviews and custom events)"
},
"bots": {
"type": "integer",
"description": "Bot hits filtered out (not billed)"
},
"allowance": {
"type": "integer",
"description": "Events included, with any badge bonus"
},
"percent": {
"type": "number",
"description": "Events as a percent of the allowance"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "Projected events at month end"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "Days left in the month"
},
"status": {
"type": "string",
"description": "ok, warning (80%+), over (a past month at or over the allowance), locked or paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "Pageviews and custom events this month"
},
"share": {
"type": "number",
"description": "Percent of the workspace total"
}
}
},
"description": "Events by site"
},
"history": {
"type": "array",
"description": "Previous months, newest first"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Dashboards locked by Privatus staff since"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "True while new events are dropped (the monthly limit is reached, or staff paused collection)"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "Why collection is paused: limit (the monthly allowance is reached) or staff. null when collecting"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When staff paused collection"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a limit pause lifts: the start of next month (UTC), or earlier on an upgrade. null otherwise"
},
{
"type": "null"
}
]
}
},
"description": "This month so far"
}
}
}
POST
/workspaces/:workspace_id/billing/checkout.json
Start a Paddle checkout for a paid plan
billing_checkout
Permission: billing.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/checkout.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "Plan to switch to: pro or business",
"enum": [
"pro",
"business"
]
},
"events": {
"type": "integer",
"description": "Events a month of the tier, from GET /plans",
"examples": [
1000000
]
},
"interval": {
"type": "string",
"description": "Billing interval. Yearly is 2 months free",
"enum": [
"month",
"year"
],
"default": "month"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"plan",
"events",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Paddle transaction id (txn_...)"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "Hosted checkout URL"
},
{
"type": "null"
}
]
},
"price_id": {
"type": "string"
},
"plan": {
"type": "string"
},
"events": {
"type": "integer"
},
"interval": {
"type": "string"
},
"amount": {
"type": "integer",
"description": "USD per interval"
},
"client_token": {
"anyOf": [
{
"type": "string",
"description": "Paddle.js client-side token"
},
{
"type": "null"
}
]
},
"environment": {
"type": "string",
"description": "sandbox or production"
},
"custom_data": {
"type": "object",
"description": "Passed to Paddle to link the subscription"
},
"discount_id": {
"anyOf": [
{
"type": "string",
"description": "Paddle discount id of an approved program, applied to this checkout"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/billing/discount.json
Apply for a discount program (nonprofit, education, open source or agency)
billing_discount
Permission: billing.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/discount.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit, education, open_source (50% off), open_source_free (free Pro up to 1M events a month) or agency (20% off every workspace you own)",
"enum": [
"nonprofit",
"education",
"open_source",
"open_source_free",
"agency"
]
},
"organization_name": {
"type": "string",
"description": "Name of the organization, school, project or agency"
},
"website": {
"type": "string",
"description": "Its website"
},
"proof_url": {
"type": "string",
"description": "Proof link. For open source, the repository URL"
},
"license": {
"type": "string",
"description": "OSI license of the project (open source only)"
},
"note": {
"type": "string",
"description": "Anything that helps the review, up to 1,000 characters"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"program",
"organization_name",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit, education, open_source, open_source_free or agency"
},
"status": {
"type": "string",
"description": "pending, approved (not yet on the subscription), active, rejected or revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business (null for the free open-source program)"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "Free events a month (free open-source program only)"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "Organization, school, project or agency name"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "Website"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "Proof link or repository URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI license (open source)"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "Note for the review"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "Why the application was not approved"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Applied at"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Reviewed at"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Discount active since"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Program ended at"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/billing/payment_method.json
Get a link to update the payment method
billing_payment_method
Permission: billing.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/payment_method.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "portal, payment_method or invoice"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "Short-lived Paddle URL"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/billing/portal.json
Get a Paddle customer portal link
billing_portal
Permission: billing.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/portal.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "portal, payment_method or invoice"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "Short-lived Paddle URL"
},
{
"type": "null"
}
]
}
}
}
GET
/workspaces/:workspace_id/billing/preview.json
Preview a plan change with proration
billing_preview
Permission: billing.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/preview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "Plan to switch to: pro or business",
"enum": [
"pro",
"business"
]
},
"events": {
"type": "integer",
"description": "Events a month of the tier, from GET /plans",
"examples": [
1000000
]
},
"interval": {
"type": "string",
"description": "Billing interval. Yearly is 2 months free",
"enum": [
"month",
"year"
],
"default": "month"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"plan",
"events",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"plan": {
"type": "string"
},
"events": {
"type": "integer"
},
"interval": {
"type": "string"
},
"price_id": {
"type": "string"
},
"amount": {
"type": "integer",
"description": "New price in USD per interval"
},
"currency": {
"type": "string"
},
"charge_minor": {
"type": "integer",
"description": "Charged now, in minor units"
},
"credit_minor": {
"type": "integer",
"description": "Credit for unused time, minor units"
},
"result_action": {
"anyOf": [
{
"type": "string",
"description": "charge or credit"
},
{
"type": "null"
}
]
},
"result_minor": {
"type": "integer",
"description": "Net charge or credit, minor units"
},
"next_billed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Usage or limits the new plan would not cover"
}
}
}
POST
/workspaces/:workspace_id/billing/resume.json
Undo a scheduled cancellation or resume a pause
billing_resume
Permission: billing.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/billing/resume.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events a month in the paid tier"
},
"allowance": {
"type": "integer",
"description": "Events a month including any badge bonus"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month or year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "USD per billing interval"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none, trialing, active, past_due, paused or canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Renews or ends at"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit, education, open_source, open_source_free or agency"
},
"status": {
"type": "string",
"description": "pending, approved (not yet on the subscription), active, rejected or revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business (null for the free open-source program)"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "Free events a month (free open-source program only)"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "Organization, school, project or agency name"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "Website"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "Proof link or repository URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI license (open source)"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "Note for the review"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "Why the application was not approved"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Applied at"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Reviewed at"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Discount active since"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Program ended at"
},
{
"type": "null"
}
]
}
},
"description": "The latest discount program application, or null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business from an approved program, or null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "Badge bonus (free plan)"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "First day of the month reported"
},
"events": {
"type": "integer",
"description": "Billable events (pageviews and custom events)"
},
"bots": {
"type": "integer",
"description": "Bot hits filtered out (not billed)"
},
"allowance": {
"type": "integer",
"description": "Events included, with any badge bonus"
},
"percent": {
"type": "number",
"description": "Events as a percent of the allowance"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "Projected events at month end"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "Days left in the month"
},
"status": {
"type": "string",
"description": "ok, warning (80%+), over (a past month at or over the allowance), locked or paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "Pageviews and custom events this month"
},
"share": {
"type": "number",
"description": "Percent of the workspace total"
}
}
},
"description": "Events by site"
},
"history": {
"type": "array",
"description": "Previous months, newest first"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Dashboards locked by Privatus staff since"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "True while new events are dropped (the monthly limit is reached, or staff paused collection)"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "Why collection is paused: limit (the monthly allowance is reached) or staff. null when collecting"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When staff paused collection"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a limit pause lifts: the start of next month (UTC), or earlier on an upgrade. null otherwise"
},
{
"type": "null"
}
]
}
},
"description": "This month so far"
}
}
}
GET
/workspaces/:workspace_id/billing.json
Get the plan, subscription and usage
billing_get
Permission: billing.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/billing.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events a month in the paid tier"
},
"allowance": {
"type": "integer",
"description": "Events a month including any badge bonus"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month or year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "USD per billing interval"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none, trialing, active, past_due, paused or canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Renews or ends at"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit, education, open_source, open_source_free or agency"
},
"status": {
"type": "string",
"description": "pending, approved (not yet on the subscription), active, rejected or revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business (null for the free open-source program)"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "Free events a month (free open-source program only)"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "Organization, school, project or agency name"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "Website"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "Proof link or repository URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI license (open source)"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "Note for the review"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "Why the application was not approved"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Applied at"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Reviewed at"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Discount active since"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Program ended at"
},
{
"type": "null"
}
]
}
},
"description": "The latest discount program application, or null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business from an approved program, or null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "Badge bonus (free plan)"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "First day of the month reported"
},
"events": {
"type": "integer",
"description": "Billable events (pageviews and custom events)"
},
"bots": {
"type": "integer",
"description": "Bot hits filtered out (not billed)"
},
"allowance": {
"type": "integer",
"description": "Events included, with any badge bonus"
},
"percent": {
"type": "number",
"description": "Events as a percent of the allowance"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "Projected events at month end"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "Days left in the month"
},
"status": {
"type": "string",
"description": "ok, warning (80%+), over (a past month at or over the allowance), locked or paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "Pageviews and custom events this month"
},
"share": {
"type": "number",
"description": "Percent of the workspace total"
}
}
},
"description": "Events by site"
},
"history": {
"type": "array",
"description": "Previous months, newest first"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Dashboards locked by Privatus staff since"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "True while new events are dropped (the monthly limit is reached, or staff paused collection)"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "Why collection is paused: limit (the monthly allowance is reached) or staff. null when collecting"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When staff paused collection"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a limit pause lifts: the start of next month (UTC), or earlier on an upgrade. null otherwise"
},
{
"type": "null"
}
]
}
},
"description": "This month so far"
}
}
}
PATCH
/workspaces/:workspace_id/billing.json
Update billing emails, tax id and auto-upgrade
billing_update
Permission: billing.manage
Example
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/billing.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"billing_emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra addresses for invoices and billing notices (up to 5)"
},
"tax_id": {
"type": "string",
"description": "VAT/GST/tax id shown on invoices"
},
"auto_upgrade": {
"type": "boolean",
"description": "true to move to the next tier and charge the difference when the monthly limit is reached, instead of pausing collection. Off by default. Turning it on while collection is paused at the limit upgrades and charges right away"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events a month in the paid tier"
},
"allowance": {
"type": "integer",
"description": "Events a month including any badge bonus"
},
"billing_interval": {
"anyOf": [
{
"type": "string",
"description": "month or year"
},
{
"type": "null"
}
]
},
"price": {
"anyOf": [
{
"type": "integer",
"description": "USD per billing interval"
},
{
"type": "null"
}
]
},
"subscription_status": {
"type": "string",
"description": "none, trialing, active, past_due, paused or canceled"
},
"current_period_ends_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Renews or ends at"
},
{
"type": "null"
}
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"auto_upgrade": {
"type": "boolean"
},
"discount": {
"anyOf": [
{
"type": "object",
"properties": {
"program": {
"type": "string",
"description": "nonprofit, education, open_source, open_source_free or agency"
},
"status": {
"type": "string",
"description": "pending, approved (not yet on the subscription), active, rejected or revoked"
},
"percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business (null for the free open-source program)"
},
{
"type": "null"
}
]
},
"comp_events": {
"anyOf": [
{
"type": "integer",
"description": "Free events a month (free open-source program only)"
},
{
"type": "null"
}
]
},
"organization_name": {
"type": "string",
"description": "Organization, school, project or agency name"
},
"website": {
"anyOf": [
{
"type": "string",
"description": "Website"
},
{
"type": "null"
}
]
},
"proof_url": {
"anyOf": [
{
"type": "string",
"description": "Proof link or repository URL"
},
{
"type": "null"
}
]
},
"license": {
"anyOf": [
{
"type": "string",
"description": "OSI license (open source)"
},
{
"type": "null"
}
]
},
"note": {
"anyOf": [
{
"type": "string",
"description": "Note for the review"
},
{
"type": "null"
}
]
},
"rejection_reason": {
"anyOf": [
{
"type": "string",
"description": "Why the application was not approved"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Applied at"
},
"reviewed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Reviewed at"
},
{
"type": "null"
}
]
},
"applied_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Discount active since"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Program ended at"
},
{
"type": "null"
}
]
}
},
"description": "The latest discount program application, or null"
},
{
"type": "null"
}
]
},
"discount_percent": {
"anyOf": [
{
"type": "integer",
"description": "Percent off Pro and Business from an approved program, or null"
},
{
"type": "null"
}
]
},
"billing_emails": {
"type": "array",
"items": {
"type": "string"
}
},
"tax_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"badge": {
"type": "object",
"description": "Badge bonus (free plan)"
},
"usage": {
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "First day of the month reported"
},
"events": {
"type": "integer",
"description": "Billable events (pageviews and custom events)"
},
"bots": {
"type": "integer",
"description": "Bot hits filtered out (not billed)"
},
"allowance": {
"type": "integer",
"description": "Events included, with any badge bonus"
},
"percent": {
"type": "number",
"description": "Events as a percent of the allowance"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "Projected events at month end"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "Days left in the month"
},
"status": {
"type": "string",
"description": "ok, warning (80%+), over (a past month at or over the allowance), locked or paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "Pageviews and custom events this month"
},
"share": {
"type": "number",
"description": "Percent of the workspace total"
}
}
},
"description": "Events by site"
},
"history": {
"type": "array",
"description": "Previous months, newest first"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Dashboards locked by Privatus staff since"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "True while new events are dropped (the monthly limit is reached, or staff paused collection)"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "Why collection is paused: limit (the monthly allowance is reached) or staff. null when collecting"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When staff paused collection"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a limit pause lifts: the start of next month (UTC), or earlier on an upgrade. null otherwise"
},
{
"type": "null"
}
]
}
},
"description": "This month so far"
}
}
}
GET
/workspaces/:workspace_id/billing/usage.json
Get this month's usage, forecast and per-site split
billing_usage
Permission: billing.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/usage.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "Any day in the month to report (defaults to this month)",
"examples": [
"2026-09-01"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"month": {
"type": "string",
"format": "date",
"description": "First day of the month reported"
},
"events": {
"type": "integer",
"description": "Billable events (pageviews and custom events)"
},
"bots": {
"type": "integer",
"description": "Bot hits filtered out (not billed)"
},
"allowance": {
"type": "integer",
"description": "Events included, with any badge bonus"
},
"percent": {
"type": "number",
"description": "Events as a percent of the allowance"
},
"forecast": {
"anyOf": [
{
"type": "integer",
"description": "Projected events at month end"
},
{
"type": "null"
}
]
},
"forecast_percent": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"days_left": {
"type": "integer",
"description": "Days left in the month"
},
"status": {
"type": "string",
"description": "ok, warning (80%+), over (a past month at or over the allowance), locked or paused"
},
"sites": {
"type": "array",
"items": {
"type": "object",
"properties": {
"site_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"events": {
"type": "integer",
"description": "Pageviews and custom events this month"
},
"share": {
"type": "number",
"description": "Percent of the workspace total"
}
}
},
"description": "Events by site"
},
"history": {
"type": "array",
"description": "Previous months, newest first"
},
"access_locked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Dashboards locked by Privatus staff since"
},
{
"type": "null"
}
]
},
"collection_paused": {
"type": "boolean",
"description": "True while new events are dropped (the monthly limit is reached, or staff paused collection)"
},
"pause_reason": {
"anyOf": [
{
"type": "string",
"description": "Why collection is paused: limit (the monthly allowance is reached) or staff. null when collecting"
},
{
"type": "null"
}
]
},
"collection_paused_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When staff paused collection"
},
{
"type": "null"
}
]
},
"resumes_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a limit pause lifts: the start of next month (UTC), or earlier on an upgrade. null otherwise"
},
{
"type": "null"
}
]
}
}
}
GET
/workspaces/:workspace_id/billing/invoices.json
List invoices
billing_invoices_list
Permission: billing.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/invoices.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Paddle transaction id"
},
"invoice_number": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "paid, completed, payment_failed, ..."
},
"amount_minor": {
"type": "integer",
"description": "Total in minor units (cents)"
},
"currency": {
"type": "string"
},
"billed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
}
}
}
GET
/workspaces/:workspace_id/billing/invoices/:id.json
Get the PDF link for an invoice
billing_invoices_get
Permission: billing.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/billing/invoices/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "portal, payment_method or invoice"
},
"url": {
"anyOf": [
{
"type": "string",
"description": "Short-lived Paddle URL"
},
{
"type": "null"
}
]
}
}
}
Campaigns
POST
/sites/:site_id/campaigns/costs.json
Set the spend for a campaign in a month
campaign_costs_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/campaigns/costs.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"campaign": {
"type": "string",
"description": "utm_campaign value the spend belongs to",
"examples": [
"spring_sale"
]
},
"month": {
"type": "string",
"description": "Month, YYYY-MM",
"examples": [
"2026-09"
]
},
"amount": {
"type": "number",
"description": "Spend in major units, e.g. 1250.50"
},
"currency": {
"type": "string",
"description": "ISO 4217 currency (defaults to the site currency)"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"campaign",
"month",
"amount",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Cost entry id"
},
"campaign": {
"type": "string",
"description": "utm_campaign value"
},
"month": {
"type": "string",
"description": "Month, YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "Spend in minor units"
},
"currency": {
"type": "string",
"description": "ISO 4217 currency of the amount"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/campaigns/costs/:id.json
Delete a campaign cost entry
campaign_costs_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/campaigns/costs/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Cost entry id"
},
"campaign": {
"type": "string",
"description": "utm_campaign value"
},
"month": {
"type": "string",
"description": "Month, YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "Spend in minor units"
},
"currency": {
"type": "string",
"description": "ISO 4217 currency of the amount"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/campaigns/costs/import.json
Import campaign costs from CSV (campaign,month,amount[,currency])
campaign_costs_import
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/campaigns/costs/import.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "CSV file upload (multipart forms)"
},
"csv": {
"type": "string",
"description": "CSV text: campaign,month,amount[,currency]"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"imported": {
"type": "integer",
"description": "Rows saved"
},
"failed": {
"type": "integer",
"description": "Rows skipped"
},
"errors": {
"type": "array",
"items": {
"type": "string"
},
"description": "Why rows were skipped (first 50)"
}
}
}
GET
/sites/:site_id/campaigns/costs.json
List campaign cost entries
campaign_costs_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/campaigns/costs.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"campaign": {
"type": "string",
"description": "Only this campaign"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Cost entry id"
},
"campaign": {
"type": "string",
"description": "utm_campaign value"
},
"month": {
"type": "string",
"description": "Month, YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "Spend in minor units"
},
"currency": {
"type": "string",
"description": "ISO 4217 currency of the amount"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/sites/:site_id/campaigns/costs/:id.json
Change a campaign cost entry
campaign_costs_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/campaigns/costs/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"campaign": {
"type": "string",
"description": "utm_campaign value"
},
"month": {
"type": "string",
"description": "Month, YYYY-MM"
},
"amount": {
"type": "number",
"description": "Spend in major units"
},
"currency": {
"type": "string",
"description": "ISO 4217 currency"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Cost entry id"
},
"campaign": {
"type": "string",
"description": "utm_campaign value"
},
"month": {
"type": "string",
"description": "Month, YYYY-MM"
},
"amount_minor": {
"type": "integer",
"description": "Spend in minor units"
},
"currency": {
"type": "string",
"description": "ISO 4217 currency of the amount"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/campaigns/builder.json
Build and validate a UTM-tagged URL
campaigns_builder
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/campaigns/builder.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"destination": {
"type": "string",
"description": "Landing page URL (https://…)",
"examples": [
"https://example.com/pricing"
]
},
"preset": {
"type": "string",
"description": "Fill utm_source/utm_medium for a channel when blank",
"enum": [
"newsletter",
"social",
"paid_search",
"paid_social",
"print",
"partner"
]
},
"utm_source": {
"type": "string",
"description": "Where the traffic comes from"
},
"utm_medium": {
"type": "string",
"description": "Marketing medium, e.g. email, cpc"
},
"utm_campaign": {
"type": "string",
"description": "Campaign name, e.g. spring_sale"
},
"utm_content": {
"type": "string",
"description": "Variant, e.g. header_button"
},
"utm_term": {
"type": "string",
"description": "Paid search keyword"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"url": {
"anyOf": [
{
"type": "string",
"description": "Tagged URL (null while there are errors)"
},
{
"type": "null"
}
]
},
"valid": {
"type": "boolean",
"description": "True when there are no errors"
},
"destination": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"preset": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_source": {
"anyOf": [
{
"type": "string",
"description": "Normalized utm_source"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string",
"description": "Normalized utm_medium"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string",
"description": "Normalized utm_campaign"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string",
"description": "Normalized utm_content"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string",
"description": "Normalized utm_term"
},
{
"type": "null"
}
]
},
"issues": {
"type": "array",
"items": {
"type": "object"
},
"description": "field, level (error or warning) and message"
},
"presets": {
"type": "object",
"description": "Channel presets: utm_source/utm_medium per preset"
}
}
}
GET
/sites/:site_id/campaigns/hygiene.json
UTM hygiene: near-duplicate values, style issues and unknown sources
campaigns_hygiene
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/campaigns/hygiene.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "from/to of the period (UTC)"
},
"duplicates": {
"type": "array",
"items": {
"type": "object"
},
"description": "Near-duplicate values: field, suggestion and variants [{value, visits}]"
},
"style_issues": {
"type": "array",
"items": {
"type": "object"
},
"description": "Values that are not lowercase with underscores: field, value, visits, suggestion"
},
"unknown_sources": {
"type": "array",
"items": {
"type": "object"
},
"description": "utm_source values we do not recognize: value, visits"
}
}
}
GET
/sites/:site_id/campaigns.json
Campaign rollup with conversions, revenue, cost, CPA and ROAS
campaigns_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/campaigns.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"goal_id": {
"type": "string",
"description": "Goal (goal_…) whose conversions to count. Defaults to the first active goal"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "from/to of the period (UTC)"
},
"currency": {
"type": "string",
"description": "Site currency for revenue and cost"
},
"goal_id": {
"anyOf": [
{
"type": "string",
"description": "Goal counted as a conversion"
},
{
"type": "null"
}
]
},
"goal_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"campaigns": {
"type": "array",
"items": {
"type": "object"
},
"description": "Per utm_campaign: visitors, visits, conversions, conversion_rate, revenue, cost, cpa (minor units), roas (revenue ÷ cost) and sources [{source, medium, visitors, visits, conversions, conversion_rate, revenue}]"
},
"totals": {
"type": "object",
"description": "Sums over all listed campaigns"
}
}
}
POST
/sites/:site_id/campaigns/links.json
Save a UTM-tagged link to the library
links_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/campaigns/links.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Link name",
"examples": [
"Spring newsletter"
]
},
"destination": {
"type": "string",
"description": "Landing page URL (https://…)",
"examples": [
"https://example.com/pricing"
]
},
"utm_source": {
"type": "string",
"description": "utm_source value (lowercased, spaces become underscores)"
},
"utm_medium": {
"type": "string",
"description": "utm_medium value (lowercased, spaces become underscores)"
},
"utm_campaign": {
"type": "string",
"description": "utm_campaign value (lowercased, spaces become underscores)"
},
"utm_content": {
"type": "string",
"description": "utm_content value (lowercased, spaces become underscores)"
},
"utm_term": {
"type": "string",
"description": "utm_term value (lowercased, spaces become underscores)"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags. Comma-separated values are split",
"default": []
},
"notes": {
"type": "string",
"description": "Free-text notes"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"destination",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Link id, e.g. lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "Landing page URL"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "Full tagged URL to share"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/campaigns/links/:id.json
Delete a saved link
links_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/campaigns/links/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Link id, e.g. lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "Landing page URL"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "Full tagged URL to share"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/campaigns/links.json
List saved campaign links
links_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/campaigns/links.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search name, destination or campaign"
},
"tag": {
"type": "string",
"description": "Only links with this tag"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Link id, e.g. lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "Landing page URL"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "Full tagged URL to share"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/campaigns/links/:id/qr.json
QR code (SVG) for a saved link
links_qr
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/campaigns/links/:id/qr.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"size": {
"type": "integer",
"description": "Module size in pixels (2 to 20)",
"default": 6
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"link_id": {
"type": "string",
"description": "Link id"
},
"url": {
"type": "string",
"description": "The encoded (tagged) URL"
},
"svg": {
"type": "string",
"description": "Standalone SVG document of the QR code"
}
}
}
GET
/sites/:site_id/campaigns/links/:id.json
Get a saved campaign link
links_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/campaigns/links/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Link id, e.g. lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "Landing page URL"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "Full tagged URL to share"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/campaigns/links/:id.json
Change a saved link
links_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/campaigns/links/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Link name",
"examples": [
"Spring newsletter"
]
},
"destination": {
"type": "string",
"description": "Landing page URL (https://…)",
"examples": [
"https://example.com/pricing"
]
},
"utm_source": {
"type": "string",
"description": "utm_source value (lowercased, spaces become underscores)"
},
"utm_medium": {
"type": "string",
"description": "utm_medium value (lowercased, spaces become underscores)"
},
"utm_campaign": {
"type": "string",
"description": "utm_campaign value (lowercased, spaces become underscores)"
},
"utm_content": {
"type": "string",
"description": "utm_content value (lowercased, spaces become underscores)"
},
"utm_term": {
"type": "string",
"description": "utm_term value (lowercased, spaces become underscores)"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags. Comma-separated values are split"
},
"notes": {
"type": "string",
"description": "Free-text notes"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Link id, e.g. lnk_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"destination": {
"type": "string",
"description": "Landing page URL"
},
"utm_source": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_medium": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_campaign": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"utm_term": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "Full tagged URL to share"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"notes": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
Channel rules
POST
/sites/:site_id/channel_rules.json
Add a channel rule
channel_rules_create
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/channel_rules.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "Channel name to assign, e.g. Partners"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Conditions that must all match: [{\"field\": \"utm_source\", \"operator\": \"is\", \"value\": \"newsletter\"}]. Fields: referrer_host, utm_source, utm_medium, utm_campaign, ref, path. Operators: is, contains, starts_with, regex."
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"channel",
"conditions",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Rule id"
},
"channel": {
"type": "string",
"description": "Channel assigned when all conditions match"
},
"position": {
"type": "integer",
"description": "Evaluation order (first match wins)"
},
"conditions": {
"type": "array",
"description": "Conditions: field, operator, value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/channel_rules/:id.json
Delete a channel rule
channel_rules_delete
Permission: sites.manage
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/channel_rules/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Rule id"
},
"channel": {
"type": "string",
"description": "Channel assigned when all conditions match"
},
"position": {
"type": "integer",
"description": "Evaluation order (first match wins)"
},
"conditions": {
"type": "array",
"description": "Conditions: field, operator, value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/channel_rules.json
List channel rules in order
channel_rules_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/channel_rules.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Rule id"
},
"channel": {
"type": "string",
"description": "Channel assigned when all conditions match"
},
"position": {
"type": "integer",
"description": "Evaluation order (first match wins)"
},
"conditions": {
"type": "array",
"description": "Conditions: field, operator, value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/channel_rules/:id/move.json
Move a channel rule up or down
channel_rules_move
Permission: sites.manage
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/channel_rules/:id/move.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"direction": {
"type": "string",
"description": "Where to move the rule",
"enum": [
"up",
"down",
"top",
"bottom"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"direction",
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Rule id"
},
"channel": {
"type": "string",
"description": "Channel assigned when all conditions match"
},
"position": {
"type": "integer",
"description": "Evaluation order (first match wins)"
},
"conditions": {
"type": "array",
"description": "Conditions: field, operator, value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/channel_rules/preview.json
Preview the channel for a sample referrer and UTM tags
channel_rules_preview
Permission: analytics.read
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/channel_rules/preview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"referrer": {
"type": "string",
"description": "Referrer URL or hostname"
},
"utm_source": {
"type": "string",
"description": "utm_source value"
},
"utm_medium": {
"type": "string",
"description": "utm_medium value"
},
"utm_campaign": {
"type": "string",
"description": "utm_campaign value"
},
"ref": {
"type": "string",
"description": "ref / via / source parameter"
},
"path": {
"type": "string",
"description": "Landing page path, e.g. /pricing"
},
"paid_click": {
"type": "boolean",
"description": "The URL had a click id such as gclid",
"default": false
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
PATCH
/sites/:site_id/channel_rules/:id.json
Change a channel rule
channel_rules_update
Permission: sites.manage
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/channel_rules/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "Channel name to assign"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string"
},
"value": {
"type": "string"
}
}
},
"description": "Conditions that must all match: [{\"field\": \"utm_source\", \"operator\": \"is\", \"value\": \"newsletter\"}]. Fields: referrer_host, utm_source, utm_medium, utm_campaign, ref, path. Operators: is, contains, starts_with, regex."
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Rule id"
},
"channel": {
"type": "string",
"description": "Channel assigned when all conditions match"
},
"position": {
"type": "integer",
"description": "Evaluation order (first match wins)"
},
"conditions": {
"type": "array",
"description": "Conditions: field, operator, value"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Collection
POST
/api/logs.json
Send server access logs for AI crawler reporting (JSON {lines: [...]} or combined log text, with the site ingest key as Bearer token)
crawler_logs_create
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/api/logs.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ts": {
"type": "string"
},
"path": {
"type": "string",
"default": "/"
},
"status": {
"type": "integer"
},
"user_agent": {
"type": "string",
"default": ""
}
}
},
"description": "Log lines: [{ts, path, status, user_agent}] (max 1000)"
}
},
"required": [
"lines"
]
}
Response data
{
"type": "object"
}
POST
/api/event.json
Collect a browser hit (used by /js/pa.js)
ingest_event
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/api/event.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site": {
"type": "string",
"description": "Site id (pa_…)"
},
"type": {
"type": "string",
"description": "Hit type",
"enum": [
"pageview",
"event",
"engagement",
"vital",
"click"
]
},
"url": {
"type": "string",
"description": "Full page URL"
},
"referrer": {
"type": "string",
"description": "document.referrer"
},
"name": {
"type": "string",
"description": "Event name (type=event) or vital name"
},
"props": {
"type": "object",
"additionalProperties": true,
"description": "Event properties: up to 30 string/number/boolean values",
"default": {}
},
"screen_width": {
"type": "integer",
"description": "Screen width in pixels"
},
"language": {
"type": "string",
"description": "navigator.language"
},
"engaged_ms": {
"type": "integer",
"description": "Visible time on page (engagement)"
},
"scroll_depth": {
"type": "integer",
"description": "Max scroll depth % (engagement)"
},
"value": {
"type": "number",
"description": "Web Vital value (type=vital)"
},
"selector": {
"type": "string",
"description": "Clicked element selector (type=click)"
},
"hash_mode": {
"type": "boolean",
"description": "Keep the #fragment (hash-routed sites)",
"default": false
},
"dnt": {
"type": "boolean",
"description": "Do Not Track is on",
"default": false
},
"gpc": {
"type": "boolean",
"description": "Global Privacy Control is on",
"default": false
},
"revenue": {
"type": "number",
"description": "Revenue in major units, e.g. 49.99"
},
"currency": {
"type": "string",
"description": "ISO 4217 currency of revenue"
}
},
"required": [
"site",
"type",
"url"
]
}
Response data
{
"type": "object"
}
POST
/api/events.json
Collect server-side events with a site ingest key
ingest_events
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/api/events.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Up to 100 events"
}
},
"required": [
"events"
]
}
Response data
{
"type": "object"
}
GET
/api/pixel.json
Collect a pageview without JavaScript (1×1 GIF)
ingest_pixel
Permission: public
· HTTP only (not an MCP tool)
Example
curl https://privatusanalytics.com/api/pixel.jsonInputs
{
"type": "object",
"properties": {},
"required": []
}
Response data
{
"type": "object"
}
Crawlers
GET
/sites/:site_id/crawlers.json
AI crawlers report: hits by crawler over time, top paths per crawler, by category
crawlers_report
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/crawlers.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"category": {
"type": "string",
"description": "ai, search, seo, other or all",
"enum": [
"all",
"ai",
"search",
"seo",
"other"
],
"default": "ai"
},
"crawler": {
"type": "string",
"description": "Only this crawler, e.g. GPTBot"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
Dashboards
GET
/workspaces/:workspace_id/dashboards/:id/cards/:index.json
Data for one card of a custom dashboard
dashboards_card
Permission: analytics.read
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id/cards/:index.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
},
"index": {
"type": "string",
"description": "Index of the resource"
}
},
"required": [
"workspace_id",
"id",
"index"
]
}
Response data
{
"type": "object"
}
POST
/workspaces/:workspace_id/dashboards.json
Create a custom dashboard
dashboards_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/dashboards.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Dashboard name",
"examples": [
"Client: Acme"
]
},
"cards": {
"type": "array",
"items": {},
"description": "Cards in order (max 40): [{\"type\": \"metric|chart|breakdown|goal|live|funnel|uptime|vitals\", \"site_id\": \"pa_…\", \"title\": \"optional\", \"params\": {\"period\": \"30d\", \"metric\": \"visitors\", \"dimension\": \"page\", \"funnel_id\": \"fun_…\"}}]. Params a type does not use are ignored",
"default": []
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Dashboard id, e.g. dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "Cards in order: [{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/dashboards/:id.json
Delete a custom dashboard
dashboards_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Dashboard id, e.g. dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "Cards in order: [{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/dashboards.json
List custom dashboards
dashboards_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Dashboard id, e.g. dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "Cards in order: [{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/workspaces/:workspace_id/dashboards/:id.json
Get a custom dashboard and its cards
dashboards_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Dashboard id, e.g. dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "Cards in order: [{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/workspaces/:workspace_id/dashboards/:id.json
Rename a custom dashboard or replace its cards
dashboards_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/dashboards/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "New name (unchanged when empty)"
},
"cards": {
"type": "array",
"items": {},
"description": "Replaces all cards. Cards in order (max 40): [{\"type\": \"metric|chart|breakdown|goal|live|funnel|uptime|vitals\", \"site_id\": \"pa_…\", \"title\": \"optional\", \"params\": {\"period\": \"30d\", \"metric\": \"visitors\", \"dimension\": \"page\", \"funnel_id\": \"fun_…\"}}]. Params a type does not use are ignored"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Dashboard id, e.g. dash_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"cards": {
"type": "array",
"items": {
"type": "object"
},
"description": "Cards in order: [{type, site_id, title, params}]"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
Documentation
GET
/docs/api.json
List every API operation and MCP tool
docs_api
Permission: public
Example
curl https://privatusanalytics.com/docs/api.jsonInputs
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": []
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"tool_name": {
"type": "string",
"description": "MCP tool name and OpenAPI operationId"
},
"summary": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"group": {
"type": "string"
},
"verb": {
"type": "string",
"description": "HTTP method"
},
"path": {
"type": "string",
"description": "Path template. Add .json for JSON"
},
"permission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"input_schema": {
"type": "object",
"description": "JSON Schema of the inputs"
},
"response_schema": {
"type": "object",
"description": "JSON Schema of `data`"
}
}
}
}
GET
/docs.json
List documentation pages
docs_list
Permission: public
Example
curl https://privatusanalytics.com/docs.jsonInputs
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": []
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Page title"
},
"description": {
"type": "string",
"description": "One-line summary"
},
"path": {
"type": "string",
"description": "Page path. Add .md for Markdown or .json for JSON"
},
"section": {
"type": "string",
"description": "Section slug, e.g. tracker"
}
}
}
}
GET
/openapi.json
OpenAPI 3.1 document for the whole API
docs_openapi
Permission: public
Example
curl https://privatusanalytics.com/openapi.jsonInputs
{
"type": "object",
"properties": {},
"required": []
}
Response data
{
"type": "object"
}
GET
/docs/search.json
Search the documentation
docs_search
Permission: public
Example
curl https://privatusanalytics.com/docs/search.jsonInputs
{
"type": "object",
"properties": {
"q": {
"type": "string",
"description": "Search text. Blank returns every page.",
"examples": [
"content security policy"
]
},
"limit": {
"type": "integer",
"description": "Maximum results (default: 20 with q, all without)"
}
},
"required": []
}
Response data
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Page title"
},
"path": {
"type": "string",
"description": "Page path"
},
"section": {
"type": "string",
"description": "Section title"
},
"headings": {
"type": "array",
"items": {
"type": "object"
},
"description": "Headings on the page: { id, text }"
},
"excerpt": {
"type": "string",
"description": "Description or first sentences"
},
"score": {
"anyOf": [
{
"type": "integer",
"description": "Relevance (only when searching with q)"
},
{
"type": "null"
}
]
}
}
}
GET
/docs/:section/:page.json
Read a documentation page (Markdown and HTML)
docs_get
section and page come from the page path /docs/<section>/<page>. Use page "index" for a section overview.
Permission: public
Example
curl https://privatusanalytics.com/docs/:section/:page.jsonInputs
{
"type": "object",
"properties": {
"section": {
"type": "string",
"description": "Section of the resource"
},
"page": {
"type": "string",
"description": "Page of the resource"
}
},
"required": [
"section",
"page"
]
}
Response data
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Page title"
},
"description": {
"type": "string",
"description": "One-line summary"
},
"path": {
"type": "string",
"description": "Page path. Add .md for Markdown or .json for JSON"
},
"section": {
"type": "string",
"description": "Section slug, e.g. tracker"
},
"headings": {
"type": "array",
"items": {
"type": "object"
},
"description": "Sections on the page (id and text)"
},
"full_markdown": {
"type": "string",
"description": "The page as Markdown (title included)"
},
"html": {
"type": "string",
"description": "The page body rendered as HTML"
}
}
}
Email reports
DELETE
/recipients/:id.json
Remove a recipient from an email report
email_report_recipients_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/recipients/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient id, e.g. rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "The address"
},
"status": {
"type": "string",
"description": "active, pending, declined or unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the last invite was sent"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a pending invite expires"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the address became active"
},
{
"type": "null"
}
]
}
}
}
GET
/reports/:report_id/recipients.json
List the recipients of an email report with their status
email_report_recipients_list
Statuses: active (gets reports), pending (invited, not yet accepted), declined or unsubscribed. Add or remove addresses through the report's recipients list.
Permission: analytics.read
Example
curl https://privatusanalytics.com/reports/:report_id/recipients.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Only recipients with this status",
"enum": [
"pending",
"active",
"declined",
"unsubscribed"
]
},
"report_id": {
"type": "string",
"description": "Report of the resource"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"report_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient id, e.g. rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "The address"
},
"status": {
"type": "string",
"description": "active, pending, declined or unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the last invite was sent"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a pending invite expires"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the address became active"
},
{
"type": "null"
}
]
}
}
}
}
POST
/recipients/:id/resend.json
Resend a pending report invite
email_report_recipients_resend
Sends the invite again with new links. Allowed once every 7 days per address per report.
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/recipients/:id/resend.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient id, e.g. rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "The address"
},
"status": {
"type": "string",
"description": "active, pending, declined or unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the last invite was sent"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a pending invite expires"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the address became active"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces/:workspace_id/reports.json
Create an email report
email_reports_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/reports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids (pa_…) included in the report"
},
"frequency": {
"type": "string",
"description": "daily, weekly (on weekday) or monthly (on the 1st)",
"enum": [
"daily",
"weekly",
"monthly"
]
},
"hour": {
"type": "integer",
"description": "Hour of day to send (0 to 23, workspace timezone)"
},
"weekday": {
"type": "integer",
"description": "Weekly reports: 0 = Sunday … 6 = Saturday"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "Email addresses (no account needed). Entries may be comma or newline separated. Members of the workspace are added at once. Anyone else gets an invite and only receives reports after accepting it. Addresses that opted out of reports are refused"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Content: kpis, chart, pages, sources, goals, campaigns, vitals, uptime"
},
"attach_pdf": {
"type": "boolean",
"description": "Attach a PDF version"
},
"intro": {
"type": "string",
"description": "Custom intro text (max 2000 chars)"
},
"enabled": {
"type": "boolean",
"description": "Send on schedule"
},
"name": {
"type": "string",
"description": "Report name",
"examples": [
"Weekly traffic"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Report id, e.g. rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids in the report"
},
"frequency": {
"type": "string",
"description": "daily, weekly or monthly"
},
"hour": {
"type": "integer",
"description": "Send hour (workspace timezone)"
},
"weekday": {
"type": "integer",
"description": "Weekly: 0 = Sunday … 6 = Saturday"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every address on the report, whatever its status"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient id, e.g. rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "The address"
},
"status": {
"type": "string",
"description": "active, pending, declined or unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the last invite was sent"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a pending invite expires"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the address became active"
},
{
"type": "null"
}
]
}
}
},
"description": "Each recipient with its opt-in status (only active recipients get reports)"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Content blocks"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/reports/:id/deliveries.json
Delivery log of an email report
email_reports_deliveries
Permission: analytics.read
Example
curl https://privatusanalytics.com/reports/:id/deliveries.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Only deliveries with this status",
"enum": [
"sent",
"test",
"failed",
"skipped"
]
},
"id": {
"type": "string",
"description": "Id of the resource"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "sent, test, failed or skipped"
},
"recipients_count": {
"type": "integer"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sent_at": {
"type": "string",
"format": "date-time"
}
}
}
}
DELETE
/reports/:id.json
Delete an email report
email_reports_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/reports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Report id, e.g. rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids in the report"
},
"frequency": {
"type": "string",
"description": "daily, weekly or monthly"
},
"hour": {
"type": "integer",
"description": "Send hour (workspace timezone)"
},
"weekday": {
"type": "integer",
"description": "Weekly: 0 = Sunday … 6 = Saturday"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every address on the report, whatever its status"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient id, e.g. rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "The address"
},
"status": {
"type": "string",
"description": "active, pending, declined or unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the last invite was sent"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a pending invite expires"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the address became active"
},
{
"type": "null"
}
]
}
}
},
"description": "Each recipient with its opt-in status (only active recipients get reports)"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Content blocks"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/reports.json
List email reports
email_reports_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/reports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"frequency": {
"type": "string",
"description": "Only reports with this frequency",
"enum": [
"daily",
"weekly",
"monthly"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Report id, e.g. rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids in the report"
},
"frequency": {
"type": "string",
"description": "daily, weekly or monthly"
},
"hour": {
"type": "integer",
"description": "Send hour (workspace timezone)"
},
"weekday": {
"type": "integer",
"description": "Weekly: 0 = Sunday … 6 = Saturday"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every address on the report, whatever its status"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient id, e.g. rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "The address"
},
"status": {
"type": "string",
"description": "active, pending, declined or unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the last invite was sent"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a pending invite expires"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the address became active"
},
{
"type": "null"
}
]
}
}
},
"description": "Each recipient with its opt-in status (only active recipients get reports)"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Content blocks"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/reports/:id/send_test.json
Send an email report now as a test
email_reports_send_test
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/reports/:id/send_test.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"recipient": {
"type": "string",
"description": "Send the test here (default: your email)"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "sent, test, failed or skipped"
},
"recipients_count": {
"type": "integer"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sent_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/reports/:id.json
Get an email report
email_reports_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/reports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Report id, e.g. rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids in the report"
},
"frequency": {
"type": "string",
"description": "daily, weekly or monthly"
},
"hour": {
"type": "integer",
"description": "Send hour (workspace timezone)"
},
"weekday": {
"type": "integer",
"description": "Weekly: 0 = Sunday … 6 = Saturday"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every address on the report, whatever its status"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient id, e.g. rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "The address"
},
"status": {
"type": "string",
"description": "active, pending, declined or unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the last invite was sent"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a pending invite expires"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the address became active"
},
{
"type": "null"
}
]
}
}
},
"description": "Each recipient with its opt-in status (only active recipients get reports)"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Content blocks"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/reports/:id.json
Update an email report
email_reports_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/reports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids (pa_…) included in the report"
},
"frequency": {
"type": "string",
"description": "daily, weekly (on weekday) or monthly (on the 1st)",
"enum": [
"daily",
"weekly",
"monthly"
]
},
"hour": {
"type": "integer",
"description": "Hour of day to send (0 to 23, workspace timezone)"
},
"weekday": {
"type": "integer",
"description": "Weekly reports: 0 = Sunday … 6 = Saturday"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "Email addresses (no account needed). Entries may be comma or newline separated. Members of the workspace are added at once. Anyone else gets an invite and only receives reports after accepting it. Addresses that opted out of reports are refused"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Content: kpis, chart, pages, sources, goals, campaigns, vitals, uptime"
},
"attach_pdf": {
"type": "boolean",
"description": "Attach a PDF version"
},
"intro": {
"type": "string",
"description": "Custom intro text (max 2000 chars)"
},
"enabled": {
"type": "boolean",
"description": "Send on schedule"
},
"name": {
"type": "string",
"description": "Report name"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Report id, e.g. rep_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids in the report"
},
"frequency": {
"type": "string",
"description": "daily, weekly or monthly"
},
"hour": {
"type": "integer",
"description": "Send hour (workspace timezone)"
},
"weekday": {
"type": "integer",
"description": "Weekly: 0 = Sunday … 6 = Saturday"
},
"recipients": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every address on the report, whatever its status"
},
"recipient_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient id, e.g. rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "The address"
},
"status": {
"type": "string",
"description": "active, pending, declined or unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the last invite was sent"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a pending invite expires"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the address became active"
},
{
"type": "null"
}
]
}
}
},
"description": "Each recipient with its opt-in status (only active recipients get reports)"
},
"blocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Content blocks"
},
"attach_pdf": {
"type": "boolean"
},
"intro": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"last_sent_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/reports/invites/:token/accept.json
Accept a report invite
report_invites_accept
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/reports/invites/:token/accept.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token of the resource"
}
},
"required": [
"token"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient id, e.g. rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "The address"
},
"status": {
"type": "string",
"description": "active, pending, declined or unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the last invite was sent"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a pending invite expires"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the address became active"
},
{
"type": "null"
}
]
}
}
}
POST
/reports/invites/:token/decline.json
Decline a report invite
report_invites_decline
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/reports/invites/:token/decline.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token of the resource"
}
},
"required": [
"token"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Recipient id, e.g. rcp_7Q2K9XH3AB"
},
"email": {
"type": "string",
"description": "The address"
},
"status": {
"type": "string",
"description": "active, pending, declined or unsubscribed"
},
"invited_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the last invite was sent"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When a pending invite expires"
},
{
"type": "null"
}
]
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the address became active"
},
{
"type": "null"
}
]
}
}
}
POST
/reports/resubscribe/:token.json
Receive reports again after opting out
report_resubscribes_confirm
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/reports/resubscribe/:token.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token of the resource"
}
},
"required": [
"token"
]
}
Response data
{
"type": "object"
}
POST
/reports/unsubscribe/:token/resubscribe.json
Email an address a link to receive reports again
report_resubscribes_create
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/reports/unsubscribe/:token/resubscribe.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token of the resource"
}
},
"required": [
"token"
]
}
Response data
{
"type": "object"
}
POST
/reports/unsubscribe/:token.json
Unsubscribe an address from an email report
report_unsubscribes_create
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/reports/unsubscribe/:token.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token of the resource"
}
},
"required": [
"token"
]
}
Response data
{
"type": "object"
}
Events
GET
/sites/:site_id/events/properties.json
List event property keys seen in the last 30 days
event_properties_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/events/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "Only keys seen on this raw event name"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
PATCH
/sites/:site_id/events/properties.json
Rename or hide an event property key
event_properties_update
Permission: sites.manage
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/events/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Property key as stored, e.g. plan"
},
"display_name": {
"type": "string",
"description": "Label to show instead (blank removes it)"
},
"hidden": {
"type": "boolean",
"description": "Hide this key from reports"
},
"export_safe": {
"type": "boolean",
"description": "The key contains no personal data, so it is included in raw exports and warehouse syncs"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"key",
"site_id"
]
}
Response data
{
"type": "object"
}
DELETE
/sites/:site_id/events.json
Delete an event and its history (runs in the background, confirm by typing the name)
events_delete
Permission: sites.manage
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/events.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Raw event name to delete"
},
"confirm": {
"type": "string",
"description": "Type the event name again to confirm"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"confirm",
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/events.json
List events with completions, visits, conversion rate and first/last seen
events_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/events.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"search": {
"type": "string",
"description": "Only events whose name contains this"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
POST
/sites/:site_id/events/merge.json
Merge several events into one display name
events_merge
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/events/merge.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"names": {
"type": "array",
"items": {
"type": "string"
},
"description": "Raw event names to merge"
},
"into": {
"type": "string",
"description": "Display name for the merged event",
"examples": [
"Signup"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"names",
"into",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Raw event name as sent by the tracker"
},
"display_name": {
"anyOf": [
{
"type": "string",
"description": "Name shown in reports"
},
{
"type": "null"
}
]
},
"hidden": {
"type": "boolean",
"description": "Hidden from reports"
},
"currency": {
"anyOf": [
{
"type": "string",
"description": "Revenue currency"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/events/detail.json
One event: chart, property pivot, number property aggregates, pages and sources
events_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/events/detail.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"name": {
"type": "string",
"description": "Event name as shown (after renames)",
"examples": [
"Signup"
]
},
"properties": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to 3 property keys to pivot by",
"default": []
},
"interval": {
"type": "string",
"description": "Chart bucket size",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"site_id"
]
}
Response data
{
"type": "object"
}
PATCH
/sites/:site_id/events/settings.json
Rename, hide or unhide an event, or set its currency
events_update
Permission: sites.manage
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/events/settings.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Raw event name as sent by the tracker",
"examples": [
"signup_click"
]
},
"display_name": {
"type": "string",
"description": "Name to show instead (blank removes rename)"
},
"hidden": {
"type": "boolean",
"description": "Hide from reports (data is kept)"
},
"currency": {
"type": "string",
"description": "Currency for revenue on this event (ISO 4217)"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Raw event name as sent by the tracker"
},
"display_name": {
"anyOf": [
{
"type": "string",
"description": "Name shown in reports"
},
{
"type": "null"
}
]
},
"hidden": {
"type": "boolean",
"description": "Hidden from reports"
},
"currency": {
"anyOf": [
{
"type": "string",
"description": "Revenue currency"
},
{
"type": "null"
}
]
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
Exports
POST
/workspaces/:workspace_id/exports.json
Queue an export (built in the background)
exports_create
Permission: analytics.export
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/exports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site to export (pa_…)",
"examples": [
"pa_7Q2K9XH3AB"
]
},
"kind": {
"type": "string",
"description": "aggregated: metrics by time bucket and dimensions. pageviews/events/raw: one row per hit (Pro and above). imported: imported daily stats. dashboard: ZIP of the overview panels",
"enum": [
"aggregated",
"pageviews",
"events",
"imported",
"raw",
"dashboard"
],
"default": "aggregated"
},
"file_format": {
"type": "string",
"description": "csv, json or xlsx (aggregated, pageviews, events, imported), csv or ndjson (raw), zip (dashboard)",
"enum": [
"csv",
"json",
"xlsx",
"ndjson",
"zip"
],
"default": "csv"
},
"from": {
"type": "string",
"format": "date",
"description": "First day, in the export timezone",
"examples": [
"2026-09-01"
]
},
"to": {
"type": "string",
"format": "date",
"description": "Last day, inclusive (max 400 days, raw 93 days)",
"examples": [
"2026-09-28"
]
},
"timezone": {
"type": "string",
"description": "Timezone for dates and grouping, e.g. America/New_York (default: the site timezone)"
},
"grouping": {
"type": "string",
"description": "Time bucket for aggregated exports",
"enum": [
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "day"
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Visit dimensions to group aggregated exports by (up to 6), e.g. country, channel, entry_page. For imported exports: the imported dimensions to include",
"default": []
},
"metrics": {
"type": "array",
"items": {
"type": "string"
},
"description": "Metrics for aggregated exports (default all): visitors, visits, pageviews, bounce_rate, visit_duration, views_per_visit, revenue",
"default": []
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Columns for pageviews/events/raw exports (default all but visit_id, vital_value, selector): occurred_at, kind, name, visit_id, hostname, path, referrer_host, referrer_path, channel, utm_source, utm_medium, utm_campaign, utm_content, utm_term, ref, paid_click, country, language, device, browser, browser_major, os, os_major, screen_bucket, engaged_ms, scroll_depth, revenue_minor, currency, vital_value, selector, props",
"default": []
},
"filters": {
"type": "array",
"items": {},
"description": "Filters, same format as the stats API: [[\"dimension\",\"operator\",\"value\"], …]",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"site_id",
"from",
"to",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Export id, e.g. exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site exported (pa_…)"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated, pageviews, events, imported, raw or dashboard"
},
"format": {
"type": "string",
"description": "csv, json, xlsx, ndjson or zip"
},
"status": {
"type": "string",
"description": "queued, running, complete, failed or expired"
},
"params": {
"type": "object",
"description": "The export definition (dates, timezone, grouping, dimensions, metrics, fields, filters)"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "Rows written"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Why the export failed"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the file is deleted"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "Path returning a short-lived signed file link (exports_download)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/exports/:id.json
Delete an export and its file
exports_delete
Permission: analytics.export
Example
curl -X DELETE https://privatusanalytics.com/exports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Export id, e.g. exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site exported (pa_…)"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated, pageviews, events, imported, raw or dashboard"
},
"format": {
"type": "string",
"description": "csv, json, xlsx, ndjson or zip"
},
"status": {
"type": "string",
"description": "queued, running, complete, failed or expired"
},
"params": {
"type": "object",
"description": "The export definition (dates, timezone, grouping, dimensions, metrics, fields, filters)"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "Rows written"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Why the export failed"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the file is deleted"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "Path returning a short-lived signed file link (exports_download)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/exports/:id/download.json
Get a signed link to the file (valid 10 minutes)
exports_download
Permission: analytics.export
Example
curl https://privatusanalytics.com/exports/:id/download.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object"
}
GET
/workspaces/:workspace_id/exports.json
List exports (the job queue)
exports_list
Permission: analytics.export
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/exports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Only exports of this site (pa_…)"
},
"status": {
"type": "string",
"description": "Only exports with this status",
"enum": [
"queued",
"running",
"complete",
"failed",
"expired"
]
},
"kind": {
"type": "string",
"description": "Only exports of this kind",
"enum": [
"aggregated",
"pageviews",
"events",
"imported",
"raw",
"dashboard"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Export id, e.g. exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site exported (pa_…)"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated, pageviews, events, imported, raw or dashboard"
},
"format": {
"type": "string",
"description": "csv, json, xlsx, ndjson or zip"
},
"status": {
"type": "string",
"description": "queued, running, complete, failed or expired"
},
"params": {
"type": "object",
"description": "The export definition (dates, timezone, grouping, dimensions, metrics, fields, filters)"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "Rows written"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Why the export failed"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the file is deleted"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "Path returning a short-lived signed file link (exports_download)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/workspaces/:workspace_id/exports/preview.json
Preview an export: first 20 rows and the estimated row count
exports_preview
Permission: analytics.export
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/exports/preview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site to export (pa_…)",
"examples": [
"pa_7Q2K9XH3AB"
]
},
"kind": {
"type": "string",
"description": "aggregated: metrics by time bucket and dimensions. pageviews/events/raw: one row per hit (Pro and above). imported: imported daily stats. dashboard: ZIP of the overview panels",
"enum": [
"aggregated",
"pageviews",
"events",
"imported",
"raw",
"dashboard"
],
"default": "aggregated"
},
"file_format": {
"type": "string",
"description": "csv, json or xlsx (aggregated, pageviews, events, imported), csv or ndjson (raw), zip (dashboard)",
"enum": [
"csv",
"json",
"xlsx",
"ndjson",
"zip"
],
"default": "csv"
},
"from": {
"type": "string",
"format": "date",
"description": "First day, in the export timezone",
"examples": [
"2026-09-01"
]
},
"to": {
"type": "string",
"format": "date",
"description": "Last day, inclusive (max 400 days, raw 93 days)",
"examples": [
"2026-09-28"
]
},
"timezone": {
"type": "string",
"description": "Timezone for dates and grouping, e.g. America/New_York (default: the site timezone)"
},
"grouping": {
"type": "string",
"description": "Time bucket for aggregated exports",
"enum": [
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "day"
},
"dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Visit dimensions to group aggregated exports by (up to 6), e.g. country, channel, entry_page. For imported exports: the imported dimensions to include",
"default": []
},
"metrics": {
"type": "array",
"items": {
"type": "string"
},
"description": "Metrics for aggregated exports (default all): visitors, visits, pageviews, bounce_rate, visit_duration, views_per_visit, revenue",
"default": []
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Columns for pageviews/events/raw exports (default all but visit_id, vital_value, selector): occurred_at, kind, name, visit_id, hostname, path, referrer_host, referrer_path, channel, utm_source, utm_medium, utm_campaign, utm_content, utm_term, ref, paid_click, country, language, device, browser, browser_major, os, os_major, screen_bucket, engaged_ms, scroll_depth, revenue_minor, currency, vital_value, selector, props",
"default": []
},
"filters": {
"type": "array",
"items": {},
"description": "Filters, same format as the stats API: [[\"dimension\",\"operator\",\"value\"], …]",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"site_id",
"from",
"to",
"workspace_id"
]
}
Response data
{
"type": "object"
}
GET
/exports/:id.json
Get an export and its status
exports_get
Permission: analytics.export
Example
curl https://privatusanalytics.com/exports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Export id, e.g. exp_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site exported (pa_…)"
},
{
"type": "null"
}
]
},
"kind": {
"type": "string",
"description": "aggregated, pageviews, events, imported, raw or dashboard"
},
"format": {
"type": "string",
"description": "csv, json, xlsx, ndjson or zip"
},
"status": {
"type": "string",
"description": "queued, running, complete, failed or expired"
},
"params": {
"type": "object",
"description": "The export definition (dates, timezone, grouping, dimensions, metrics, fields, filters)"
},
"row_count": {
"anyOf": [
{
"type": "integer",
"description": "Rows written"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Why the export failed"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "When the file is deleted"
},
{
"type": "null"
}
]
},
"download_url": {
"anyOf": [
{
"type": "string",
"description": "Path returning a short-lived signed file link (exports_download)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Funnels
POST
/sites/:site_id/funnels.json
Create a funnel
funnels_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/funnels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Funnel name",
"examples": [
"Signup flow"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Ordered steps (2 to your plan limit): [{\"type\": \"page|event|goal\", \"value\": \"/pricing | Signup | goal_…\", \"match\": \"exact|prefix|glob|regex\" (page steps), \"name\": \"optional label\"}]"
},
"order_mode": {
"type": "string",
"description": "strict: steps in this order, any: in any order",
"enum": [
"strict",
"any"
],
"default": "strict"
},
"window": {
"type": "string",
"description": "Conversion window: visit, or day (measured within a visit, which never spans a UTC day)",
"enum": [
"visit",
"day"
],
"default": "visit"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"steps",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Funnel id, e.g. fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "Steps: {type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict or any"
},
"window": {
"type": "string",
"description": "visit or day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "Visits that reached step 1"
},
"completed": {
"type": "integer",
"description": "Visits that reached the last step"
},
"conversion_rate": {
"type": "number",
"description": "Completed ÷ entered, %"
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/funnels/:id.json
Delete a funnel
funnels_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/funnels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Funnel id, e.g. fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "Steps: {type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict or any"
},
"window": {
"type": "string",
"description": "visit or day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "Visits that reached step 1"
},
"completed": {
"type": "integer",
"description": "Visits that reached the last step"
},
"conversion_rate": {
"type": "number",
"description": "Completed ÷ entered, %"
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/funnels.json
List funnels with entries, completions and rate
funnels_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/funnels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"page": {
"type": "integer",
"description": "Page number",
"default": 1
},
"per_page": {
"type": "integer",
"description": "Funnels per page (max 100)",
"default": 25
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Funnel id, e.g. fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "Steps: {type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict or any"
},
"window": {
"type": "string",
"description": "visit or day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "Visits that reached step 1"
},
"completed": {
"type": "integer",
"description": "Visits that reached the last step"
},
"conversion_rate": {
"type": "number",
"description": "Completed ÷ entered, %"
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/funnels/:id.json
Funnel report: step counts, conversion, drop-off, time between steps and where visits went instead
funnels_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/funnels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"breakdown": {
"type": "string",
"description": "Split step counts by a visit dimension",
"enum": [
"channel",
"device",
"country",
"utm_campaign",
"utm_source",
"browser",
"os"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "from/to of the period (UTC)"
},
"funnel": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Funnel id, e.g. fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "Steps: {type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict or any"
},
"window": {
"type": "string",
"description": "visit or day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "Visits that reached step 1"
},
"completed": {
"type": "integer",
"description": "Visits that reached the last step"
},
"conversion_rate": {
"type": "number",
"description": "Completed ÷ entered, %"
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"description": "The funnel definition"
},
"order_mode": {
"type": "string",
"description": "strict or any"
},
"window": {
"type": "string",
"description": "visit or day (day is measured within a visit)"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "Per step: index, name, type, value, count, step_conversion_rate, overall_conversion_rate, dropoff, dropoff_rate, median_seconds_from_previous, next_pages [{value, count}]"
},
"overall_conversion_rate": {
"type": "number",
"description": "Last step ÷ first step, %"
},
"breakdown": {
"anyOf": [
{
"type": "object",
"description": "dimension, label and rows [{value, counts, overall_conversion_rate}]"
},
{
"type": "null"
}
]
},
"comparison": {
"anyOf": [
{
"type": "object",
"description": "period, counts per step, overall_conversion_rate and change (%)"
},
{
"type": "null"
}
]
}
}
}
PATCH
/sites/:site_id/funnels/:id.json
Update a funnel
funnels_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/funnels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Funnel name",
"examples": [
"Signup flow"
]
},
"steps": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Ordered steps (2 to your plan limit): [{\"type\": \"page|event|goal\", \"value\": \"/pricing | Signup | goal_…\", \"match\": \"exact|prefix|glob|regex\" (page steps), \"name\": \"optional label\"}]"
},
"order_mode": {
"type": "string",
"description": "strict: steps in this order, any: in any order",
"enum": [
"strict",
"any"
]
},
"window": {
"type": "string",
"description": "Conversion window: visit, or day (measured within a visit, which never spans a UTC day)",
"enum": [
"visit",
"day"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Funnel id, e.g. fun_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object"
},
"description": "Steps: {type: page|event|goal, value, match, name}"
},
"order_mode": {
"type": "string",
"description": "strict or any"
},
"window": {
"type": "string",
"description": "visit or day"
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"entered": {
"type": "integer",
"description": "Visits that reached step 1"
},
"completed": {
"type": "integer",
"description": "Visits that reached the last step"
},
"conversion_rate": {
"type": "number",
"description": "Completed ÷ entered, %"
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
Goals
POST
/sites/:site_id/goals/:id/archive.json
Archive a goal (hidden from reports)
goals_archive
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/goals/:id/archive.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Goal id, e.g. goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page, event, engagement, outbound or download"
},
"match_type": {
"type": "string",
"description": "exact, prefix, glob or regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "Path, domain or file pattern"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "Hostname restriction (page goals)"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "Custom event name (event goals)"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "Event property conditions"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: scroll %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: seconds on page"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none, fixed or revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "Fixed value in minor units"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit or every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "Matching events, repeats included"
},
"conversions": {
"type": "integer",
"description": "Visits with at least one completion"
},
"conversion_rate": {
"type": "number",
"description": "Conversions ÷ visits (or ÷ visitors, per site setting), %"
},
"value": {
"type": "integer",
"description": "Goal value in site currency minor units"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "Conversions change vs the previous period, %"
},
{
"type": "null"
}
]
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/goals.json
Create a goal
goals_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/goals.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Goal name",
"examples": [
"Signed up"
]
},
"kind": {
"type": "string",
"description": "page (visit a page), event (custom event), engagement (scroll or time on page), outbound (outbound link click) or download (file download)",
"enum": [
"page",
"event",
"engagement",
"outbound",
"download"
]
},
"match_type": {
"type": "string",
"description": "How pattern matches the path (page, engagement), link domain (outbound) or file (download): exact, prefix, glob (*) or regex",
"enum": [
"exact",
"prefix",
"glob",
"regex"
],
"default": "exact"
},
"pattern": {
"type": "string",
"description": "Path, domain or file pattern, e.g. /pricing, /blog/*, stripe.com or *.pdf"
},
"hostname": {
"type": "string",
"description": "Only count pages on this hostname (page goals)"
},
"event_name": {
"type": "string",
"description": "Custom event name (event goals)"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Event property conditions: [{\"key\": \"plan\", \"operator\": \"is|is_not|contains|gt|lt\", \"value\": \"pro\"}]",
"default": []
},
"scroll_threshold": {
"type": "integer",
"description": "Engagement: scroll depth % to reach"
},
"time_threshold_seconds": {
"type": "integer",
"description": "Engagement: seconds on page"
},
"value_mode": {
"type": "string",
"description": "none, fixed (fixed_value per conversion) or revenue (the event revenue)",
"enum": [
"none",
"fixed",
"revenue"
],
"default": "none"
},
"fixed_value": {
"type": "number",
"description": "Fixed value per conversion in the site currency, e.g. 50.0"
},
"count_mode": {
"type": "string",
"description": "Value counts once_per_visit or every completion",
"enum": [
"once_per_visit",
"every"
],
"default": "once_per_visit"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"kind",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Goal id, e.g. goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page, event, engagement, outbound or download"
},
"match_type": {
"type": "string",
"description": "exact, prefix, glob or regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "Path, domain or file pattern"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "Hostname restriction (page goals)"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "Custom event name (event goals)"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "Event property conditions"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: scroll %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: seconds on page"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none, fixed or revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "Fixed value in minor units"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit or every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "Matching events, repeats included"
},
"conversions": {
"type": "integer",
"description": "Visits with at least one completion"
},
"conversion_rate": {
"type": "number",
"description": "Conversions ÷ visits (or ÷ visitors, per site setting), %"
},
"value": {
"type": "integer",
"description": "Goal value in site currency minor units"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "Conversions change vs the previous period, %"
},
{
"type": "null"
}
]
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/goals/:id.json
Delete a goal (data is kept)
goals_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/goals/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Goal id, e.g. goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page, event, engagement, outbound or download"
},
"match_type": {
"type": "string",
"description": "exact, prefix, glob or regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "Path, domain or file pattern"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "Hostname restriction (page goals)"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "Custom event name (event goals)"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "Event property conditions"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: scroll %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: seconds on page"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none, fixed or revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "Fixed value in minor units"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit or every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "Matching events, repeats included"
},
"conversions": {
"type": "integer",
"description": "Visits with at least one completion"
},
"conversion_rate": {
"type": "number",
"description": "Conversions ÷ visits (or ÷ visitors, per site setting), %"
},
"value": {
"type": "integer",
"description": "Goal value in site currency minor units"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "Conversions change vs the previous period, %"
},
{
"type": "null"
}
]
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/goals/:id/duplicate.json
Copy a goal
goals_duplicate
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/goals/:id/duplicate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name for the copy"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Goal id, e.g. goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page, event, engagement, outbound or download"
},
"match_type": {
"type": "string",
"description": "exact, prefix, glob or regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "Path, domain or file pattern"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "Hostname restriction (page goals)"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "Custom event name (event goals)"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "Event property conditions"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: scroll %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: seconds on page"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none, fixed or revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "Fixed value in minor units"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit or every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "Matching events, repeats included"
},
"conversions": {
"type": "integer",
"description": "Visits with at least one completion"
},
"conversion_rate": {
"type": "number",
"description": "Conversions ÷ visits (or ÷ visitors, per site setting), %"
},
"value": {
"type": "integer",
"description": "Goal value in site currency minor units"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "Conversions change vs the previous period, %"
},
{
"type": "null"
}
]
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/goals.json
List goals with completions, conversions, rate and value for a period
goals_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/goals.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"status": {
"type": "string",
"description": "active, archived or all goals",
"enum": [
"active",
"archived",
"all"
],
"default": "active"
},
"page": {
"type": "integer",
"description": "Page number",
"default": 1
},
"per_page": {
"type": "integer",
"description": "Goals per page (max 100)",
"default": 25
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Goal id, e.g. goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page, event, engagement, outbound or download"
},
"match_type": {
"type": "string",
"description": "exact, prefix, glob or regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "Path, domain or file pattern"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "Hostname restriction (page goals)"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "Custom event name (event goals)"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "Event property conditions"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: scroll %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: seconds on page"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none, fixed or revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "Fixed value in minor units"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit or every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "Matching events, repeats included"
},
"conversions": {
"type": "integer",
"description": "Visits with at least one completion"
},
"conversion_rate": {
"type": "number",
"description": "Conversions ÷ visits (or ÷ visitors, per site setting), %"
},
"value": {
"type": "integer",
"description": "Goal value in site currency minor units"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "Conversions change vs the previous period, %"
},
{
"type": "null"
}
]
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/goals/:id.json
Goal report: metrics, chart, breakdowns and the journey to converting
goals_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/goals/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"interval": {
"type": "string",
"description": "Chart bucket size",
"enum": [
"auto",
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"default": "auto"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"period": {
"type": "object",
"description": "from/to of the period (UTC)"
},
"goal": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Goal id, e.g. goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page, event, engagement, outbound or download"
},
"match_type": {
"type": "string",
"description": "exact, prefix, glob or regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "Path, domain or file pattern"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "Hostname restriction (page goals)"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "Custom event name (event goals)"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "Event property conditions"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: scroll %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: seconds on page"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none, fixed or revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "Fixed value in minor units"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit or every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "Matching events, repeats included"
},
"conversions": {
"type": "integer",
"description": "Visits with at least one completion"
},
"conversion_rate": {
"type": "number",
"description": "Conversions ÷ visits (or ÷ visitors, per site setting), %"
},
"value": {
"type": "integer",
"description": "Goal value in site currency minor units"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "Conversions change vs the previous period, %"
},
{
"type": "null"
}
]
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
},
"description": "The goal definition"
},
"metrics": {
"type": "object",
"description": "completions, conversions, conversion_rate (%), value (minor units)"
},
"comparison_period": {
"anyOf": [
{
"type": "object",
"description": "Comparison from/to"
},
{
"type": "null"
}
]
},
"comparison": {
"anyOf": [
{
"type": "object",
"description": "Metrics for the comparison period"
},
{
"type": "null"
}
]
},
"change": {
"anyOf": [
{
"type": "object",
"description": "Change vs comparison, % per metric"
},
{
"type": "null"
}
]
},
"interval": {
"type": "string",
"description": "Chart bucket size"
},
"series": {
"type": "array",
"items": {
"type": "object"
},
"description": "Per bucket: date, completions, conversions, conversion_rate"
},
"breakdowns": {
"type": "object",
"description": "Top values by conversions for channel, utm_campaign, entry_page, country and device: value, completions, conversions, conversion_rate"
},
"journey": {
"anyOf": [
{
"type": "object",
"description": "converting_visits, median_seconds_to_convert, median_pages_before and pages_before (pages viewed earlier in the visit, by converting visits)"
},
{
"type": "null"
}
]
}
}
}
POST
/sites/:site_id/goals/:id/unarchive.json
Restore an archived goal
goals_unarchive
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/goals/:id/unarchive.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Goal id, e.g. goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page, event, engagement, outbound or download"
},
"match_type": {
"type": "string",
"description": "exact, prefix, glob or regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "Path, domain or file pattern"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "Hostname restriction (page goals)"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "Custom event name (event goals)"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "Event property conditions"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: scroll %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: seconds on page"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none, fixed or revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "Fixed value in minor units"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit or every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "Matching events, repeats included"
},
"conversions": {
"type": "integer",
"description": "Visits with at least one completion"
},
"conversion_rate": {
"type": "number",
"description": "Conversions ÷ visits (or ÷ visitors, per site setting), %"
},
"value": {
"type": "integer",
"description": "Goal value in site currency minor units"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "Conversions change vs the previous period, %"
},
{
"type": "null"
}
]
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/goals/:id.json
Update a goal
goals_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/goals/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Goal name",
"examples": [
"Signed up"
]
},
"kind": {
"type": "string",
"description": "page (visit a page), event (custom event), engagement (scroll or time on page), outbound (outbound link click) or download (file download)",
"enum": [
"page",
"event",
"engagement",
"outbound",
"download"
]
},
"match_type": {
"type": "string",
"description": "How pattern matches the path (page, engagement), link domain (outbound) or file (download): exact, prefix, glob (*) or regex",
"enum": [
"exact",
"prefix",
"glob",
"regex"
]
},
"pattern": {
"type": "string",
"description": "Path, domain or file pattern, e.g. /pricing, /blog/*, stripe.com or *.pdf"
},
"hostname": {
"type": "string",
"description": "Only count pages on this hostname (page goals)"
},
"event_name": {
"type": "string",
"description": "Custom event name (event goals)"
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "Event property conditions: [{\"key\": \"plan\", \"operator\": \"is|is_not|contains|gt|lt\", \"value\": \"pro\"}]"
},
"scroll_threshold": {
"type": "integer",
"description": "Engagement: scroll depth % to reach"
},
"time_threshold_seconds": {
"type": "integer",
"description": "Engagement: seconds on page"
},
"value_mode": {
"type": "string",
"description": "none, fixed (fixed_value per conversion) or revenue (the event revenue)",
"enum": [
"none",
"fixed",
"revenue"
]
},
"fixed_value": {
"type": "number",
"description": "Fixed value per conversion in the site currency, e.g. 50.0"
},
"count_mode": {
"type": "string",
"description": "Value counts once_per_visit or every completion",
"enum": [
"once_per_visit",
"every"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Goal id, e.g. goal_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "page, event, engagement, outbound or download"
},
"match_type": {
"type": "string",
"description": "exact, prefix, glob or regex"
},
"pattern": {
"anyOf": [
{
"type": "string",
"description": "Path, domain or file pattern"
},
{
"type": "null"
}
]
},
"hostname": {
"anyOf": [
{
"type": "string",
"description": "Hostname restriction (page goals)"
},
{
"type": "null"
}
]
},
"event_name": {
"anyOf": [
{
"type": "string",
"description": "Custom event name (event goals)"
},
{
"type": "null"
}
]
},
"conditions": {
"type": "array",
"items": {
"type": "object"
},
"description": "Event property conditions"
},
"scroll_threshold": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: scroll %"
},
{
"type": "null"
}
]
},
"time_threshold_seconds": {
"anyOf": [
{
"type": "integer",
"description": "Engagement: seconds on page"
},
{
"type": "null"
}
]
},
"value_mode": {
"type": "string",
"description": "none, fixed or revenue"
},
"fixed_value_minor": {
"anyOf": [
{
"type": "integer",
"description": "Fixed value in minor units"
},
{
"type": "null"
}
]
},
"count_mode": {
"type": "string",
"description": "once_per_visit or every"
},
"archived": {
"type": "boolean"
},
"archived_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"stats": {
"anyOf": [
{
"type": "object",
"properties": {
"completions": {
"type": "integer",
"description": "Matching events, repeats included"
},
"conversions": {
"type": "integer",
"description": "Visits with at least one completion"
},
"conversion_rate": {
"type": "number",
"description": "Conversions ÷ visits (or ÷ visitors, per site setting), %"
},
"value": {
"type": "integer",
"description": "Goal value in site currency minor units"
},
"change": {
"anyOf": [
{
"type": "number",
"description": "Conversions change vs the previous period, %"
},
{
"type": "null"
}
]
}
},
"description": "Period stats (list only)"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
Imports
GET
/sites/:site_id/imports/google/properties.json
List Google Analytics 4 properties to import
imports_google_properties
Permission: sites.manage
Example
curl https://privatusanalytics.com/sites/:site_id/imports/google/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
POST
/sites/:site_id/imports.json
Start an import (GA4 property or CSV upload)
imports_create
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/imports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "ga4 (Google Analytics 4 API) or the tool whose CSV export you upload",
"enum": [
"ga4",
"universal_analytics",
"fathom",
"simple_analytics",
"plausible",
"matomo",
"umami",
"clicky"
]
},
"property_id": {
"type": "string",
"description": "GA4 property, e.g. properties/123 (see imports_google_properties). Required for ga4",
"examples": [
"properties/123456789"
]
},
"date_from": {
"type": "string",
"format": "date",
"description": "First day to import. Required for ga4. For CSV files without a date column every row is dated this day"
},
"date_to": {
"type": "string",
"format": "date",
"description": "Last day to import (ga4 defaults to the day before your first tracked event, or yesterday)"
},
"file": {
"type": "string",
"format": "binary",
"description": "CSV export (multipart upload, max 50 MB). Required for CSV sources"
},
"dimension": {
"type": "string",
"description": "What the CSV rows break down (overrides detection, needed for Matomo \"Label\" exports)",
"enum": [
"total",
"page",
"source",
"country",
"device",
"browser",
"os"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"source",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Import id"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4, universal_analytics, fathom, simple_analytics, plausible, matomo, umami or clicky"
},
"status": {
"type": "string",
"description": "queued, running, complete or failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "First imported day"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "Last imported day"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "Daily rows stored"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Why the import failed"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/imports/:id.json
Delete an import and all its imported data
imports_delete
Permission: sites.manage
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/imports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Import id"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4, universal_analytics, fathom, simple_analytics, plausible, matomo, umami or clicky"
},
"status": {
"type": "string",
"description": "queued, running, complete or failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "First imported day"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "Last imported day"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "Daily rows stored"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Why the import failed"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/imports.json
List imports for a site
imports_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/imports.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Only imports with this status",
"enum": [
"queued",
"running",
"complete",
"failed"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Import id"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4, universal_analytics, fathom, simple_analytics, plausible, matomo, umami or clicky"
},
"status": {
"type": "string",
"description": "queued, running, complete or failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "First imported day"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "Last imported day"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "Daily rows stored"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Why the import failed"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/imports/:id.json
Get an import and its status
imports_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/imports/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Import id"
},
"site_id": {
"type": "string"
},
"source": {
"type": "string",
"description": "ga4, universal_analytics, fathom, simple_analytics, plausible, matomo, umami or clicky"
},
"status": {
"type": "string",
"description": "queued, running, complete or failed"
},
"date_from": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "First imported day"
},
{
"type": "null"
}
]
},
"date_to": {
"anyOf": [
{
"type": "string",
"format": "date",
"description": "Last imported day"
},
{
"type": "null"
}
]
},
"rows_imported": {
"type": "integer",
"description": "Daily rows stored"
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Why the import failed"
},
{
"type": "null"
}
]
},
"completed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Live
GET
/sites/:site_id/live.json
Live visitors, activity stream and what is popular right now (last 30 minutes)
live_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/live.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"feed": {
"type": "string",
"description": "Activity stream: all hits, pageviews or custom events",
"enum": [
"all",
"pageviews",
"events"
],
"default": "all"
},
"limit": {
"type": "integer",
"description": "Activity stream entries (max 100)",
"default": 50
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/live/wallboard.json
Wallboard cards (live and today) for one or more sites
live_wallboard
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/live/wallboard.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids to rotate between (defaults to this site)",
"default": []
},
"rotate_seconds": {
"type": "integer",
"description": "Seconds each site stays on screen (5-300)",
"default": 20
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/wallboard/:token.json
Wallboard for a wallboard token (no login needed)
live_public_wallboard
Permission: public
· HTTP only (not an MCP tool)
Example
curl https://privatusanalytics.com/wallboard/:token.jsonInputs
{
"type": "object",
"properties": {
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids to rotate between (defaults to this site)",
"default": []
},
"rotate_seconds": {
"type": "integer",
"description": "Seconds each site stays on screen (5-300)",
"default": 20
},
"token": {
"type": "string",
"description": "Token of the resource"
}
},
"required": [
"token"
]
}
Response data
{
"type": "object"
}
POST
/sites/:site_id/live/wallboard/links.json
Create a wallboard link (read-only, revocable)
wallboard_links_create
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/live/wallboard/links.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Label, e.g. Office TV"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra sites to rotate through (this site is always included)",
"default": []
},
"rotate_seconds": {
"type": "integer",
"description": "Seconds per site when rotating (5-300)",
"default": 20
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "Stop working after this time"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Link id, e.g. shr_7Q2K9XH3AB"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "Open this on a TV. No login needed"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites shown, in rotation"
},
"rotate_seconds": {
"type": "integer"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/live/wallboard/links/:id.json
Revoke a wallboard link
wallboard_links_delete
Permission: sites.manage
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/live/wallboard/links/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Link id, e.g. shr_7Q2K9XH3AB"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "Open this on a TV. No login needed"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites shown, in rotation"
},
"rotate_seconds": {
"type": "integer"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/live/wallboard/links.json
List wallboard links for a site
wallboard_links_list
Permission: sites.manage
Example
curl https://privatusanalytics.com/sites/:site_id/live/wallboard/links.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Link id, e.g. shr_7Q2K9XH3AB"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string",
"description": "Open this on a TV. No login needed"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites shown, in rotation"
},
"rotate_seconds": {
"type": "integer"
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"revoked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
Members
POST
/workspaces/:workspace_id/invitations.json
Invite people by email
invitations_create
Permission: members.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/invitations.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "Email addresses to invite"
},
"role": {
"type": "string",
"description": "Role for the new members (custom needs custom_role_id)",
"enum": [
"admin",
"editor",
"analyst",
"viewer",
"billing",
"custom"
],
"default": "viewer"
},
"custom_role_id": {
"type": "string",
"description": "Custom role id (Business)"
},
"all_sites": {
"type": "boolean",
"description": "Access to all sites, including future ones",
"default": true
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids (pa_…) when all_sites is false",
"default": []
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"emails",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"role": {
"type": "string"
},
"custom_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/invitations/:id.json
Revoke a pending invitation
invitations_delete
Permission: members.manage
Example
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/invitations/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"role": {
"type": "string"
},
"custom_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/invitations.json
List pending invitations
invitations_list
Permission: members.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/invitations.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"role": {
"type": "string"
},
"custom_role": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"invited_by": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
DELETE
/workspaces/:workspace_id/members/:id.json
Remove a member (or leave the workspace)
members_delete
Permission: member
Example
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/members/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Member id (use it to update or remove the member)"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner, admin, editor, analyst, viewer, billing or custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "Custom role name"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "Access to all sites"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids when all_sites is false"
},
"two_factor": {
"type": "boolean",
"description": "Has 2FA or a passkey"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Joined at"
}
}
}
GET
/workspaces/:workspace_id/members.json
List workspace members
members_list
Permission: member
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/members.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Filter by name or email"
},
"role": {
"type": "string",
"description": "Only members with this role",
"enum": [
"owner",
"admin",
"editor",
"analyst",
"viewer",
"billing",
"custom"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Member id (use it to update or remove the member)"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner, admin, editor, analyst, viewer, billing or custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "Custom role name"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "Access to all sites"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids when all_sites is false"
},
"two_factor": {
"type": "boolean",
"description": "Has 2FA or a passkey"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Joined at"
}
}
}
}
PATCH
/workspaces/:workspace_id/members/:id.json
Change a member's role or site access
members_update
Permission: members.manage
Example
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/members/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"role": {
"type": "string",
"description": "New role (custom needs custom_role_id)",
"enum": [
"admin",
"editor",
"analyst",
"viewer",
"billing",
"custom"
]
},
"custom_role_id": {
"type": "string",
"description": "Custom role id (Business)"
},
"all_sites": {
"type": "boolean",
"description": "Access to all sites, including future ones"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids (pa_…) when all_sites is false"
},
"include_future_sites": {
"type": "boolean",
"description": "Also grant sites added later"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Member id (use it to update or remove the member)"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner, admin, editor, analyst, viewer, billing or custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "Custom role name"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "Access to all sites"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids when all_sites is false"
},
"two_factor": {
"type": "boolean",
"description": "Has 2FA or a passkey"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Joined at"
}
}
}
POST
/workspaces/:workspace_id/ownership_transfer.json
Transfer workspace ownership to another member (owner only, you become an admin)
ownership_transfers_create
Permission: member
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/ownership_transfer.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"description": "Member id of the new owner"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"membership_id",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Member id (use it to update or remove the member)"
},
"email": {
"type": "string"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"role": {
"type": "string",
"description": "owner, admin, editor, analyst, viewer, billing or custom"
},
"custom_role": {
"anyOf": [
{
"type": "string",
"description": "Custom role name"
},
{
"type": "null"
}
]
},
"custom_role_id": {
"anyOf": [
{
"type": "string",
"format": "uuid"
},
{
"type": "null"
}
]
},
"all_sites": {
"type": "boolean",
"description": "Access to all sites"
},
"include_future_sites": {
"type": "boolean"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Site ids when all_sites is false"
},
"two_factor": {
"type": "boolean",
"description": "Has 2FA or a passkey"
},
"last_active_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Joined at"
}
}
}
Notes
POST
/sites/:site_id/notes.json
Add a note to a site (use source "deploy" for release webhooks)
notes_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "Day of the note (site timezone). Defaults to today"
},
"end_date": {
"type": "string",
"format": "date",
"description": "Last day, for a date range"
},
"title": {
"type": "string",
"description": "Short title shown on charts",
"examples": [
"Launched new pricing"
]
},
"body": {
"type": "string",
"description": "Details (Markdown)"
},
"url": {
"type": "string",
"description": "Link, e.g. a PR or changelog"
},
"color": {
"type": "string",
"description": "Pin color",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"source": {
"type": "string",
"description": "manual, or deploy for release webhooks",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
],
"default": "manual"
},
"version": {
"type": "string",
"description": "Deploys: release version or commit, used for the default title"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Note id, e.g. note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site, or null for workspace-wide notes"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral, brand, blue, amber, red, violet"
},
"source": {
"type": "string",
"description": "manual, deploy, system, import, incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/notes/:id.json
Delete a note
notes_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Note id, e.g. note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site, or null for workspace-wide notes"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral, brand, blue, amber, red, violet"
},
"source": {
"type": "string",
"description": "manual, deploy, system, import, incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/notes.json
List notes for a site (including workspace-wide notes)
notes_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date",
"description": "Only notes on or after this date"
},
"to": {
"type": "string",
"format": "date",
"description": "Only notes on or before this date"
},
"source": {
"type": "string",
"description": "Only notes from this source",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
]
},
"query": {
"type": "string",
"description": "Search title, body and link"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Note id, e.g. note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site, or null for workspace-wide notes"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral, brand, blue, amber, red, violet"
},
"source": {
"type": "string",
"description": "manual, deploy, system, import, incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:site_id/notes/:id.json
Get a note
notes_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Note id, e.g. note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site, or null for workspace-wide notes"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral, brand, blue, amber, red, violet"
},
"source": {
"type": "string",
"description": "manual, deploy, system, import, incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/notes/:id.json
Edit a note
notes_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "Day of the note"
},
"end_date": {
"type": "string",
"format": "date",
"description": "Last day, for a date range"
},
"title": {
"type": "string",
"description": "Short title shown on charts"
},
"body": {
"type": "string",
"description": "Details (Markdown)"
},
"url": {
"type": "string",
"description": "Link"
},
"color": {
"type": "string",
"description": "Pin color",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Note id, e.g. note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site, or null for workspace-wide notes"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral, brand, blue, amber, red, violet"
},
"source": {
"type": "string",
"description": "manual, deploy, system, import, incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/notes.json
Add a workspace-wide note (shown on every site)
workspace_notes_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "Day of the note (site timezone). Defaults to today"
},
"end_date": {
"type": "string",
"format": "date",
"description": "Last day, for a date range"
},
"title": {
"type": "string",
"description": "Short title shown on charts",
"examples": [
"Launched new pricing"
]
},
"body": {
"type": "string",
"description": "Details (Markdown)"
},
"url": {
"type": "string",
"description": "Link, e.g. a PR or changelog"
},
"color": {
"type": "string",
"description": "Pin color",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"source": {
"type": "string",
"description": "manual, or deploy for release webhooks",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
],
"default": "manual"
},
"version": {
"type": "string",
"description": "Deploys: release version or commit, used for the default title"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Note id, e.g. note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site, or null for workspace-wide notes"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral, brand, blue, amber, red, violet"
},
"source": {
"type": "string",
"description": "manual, deploy, system, import, incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/notes/:id.json
Delete a workspace note
workspace_notes_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Note id, e.g. note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site, or null for workspace-wide notes"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral, brand, blue, amber, red, violet"
},
"source": {
"type": "string",
"description": "manual, deploy, system, import, incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/notes.json
List notes across a workspace
workspace_notes_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/notes.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date",
"description": "Only notes on or after this date"
},
"to": {
"type": "string",
"format": "date",
"description": "Only notes on or before this date"
},
"source": {
"type": "string",
"description": "Only notes from this source",
"enum": [
"manual",
"deploy",
"system",
"import",
"incident"
]
},
"query": {
"type": "string",
"description": "Search title, body and link"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Note id, e.g. note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site, or null for workspace-wide notes"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral, brand, blue, amber, red, violet"
},
"source": {
"type": "string",
"description": "manual, deploy, system, import, incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/workspaces/:workspace_id/notes/:id.json
Edit a workspace note
workspace_notes_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/notes/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "Day of the note"
},
"end_date": {
"type": "string",
"format": "date",
"description": "Last day, for a date range"
},
"title": {
"type": "string",
"description": "Short title shown on charts"
},
"body": {
"type": "string",
"description": "Details (Markdown)"
},
"url": {
"type": "string",
"description": "Link"
},
"color": {
"type": "string",
"description": "Pin color",
"enum": [
"neutral",
"brand",
"blue",
"amber",
"red",
"violet"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Note id, e.g. note_7Q2K9XH3AB"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site, or null for workspace-wide notes"
},
{
"type": "null"
}
]
},
"date": {
"type": "string",
"format": "date"
},
"end_date": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
]
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string",
"description": "Markdown"
},
{
"type": "null"
}
]
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"color": {
"type": "string",
"description": "neutral, brand, blue, amber, red, violet"
},
"source": {
"type": "string",
"description": "manual, deploy, system, import, incident"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Notification channels
POST
/workspaces/:workspace_id/channels.json
Add a notification channel
notification_channels_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/channels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Webhook URL (slack, teams, discord, webhook), HTTPS"
},
"secret": {
"type": "string",
"description": "webhook: HMAC secret for X-Privatus-Signature"
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "email: recipient addresses (max 20)"
},
"routing_key": {
"type": "string",
"description": "pagerduty: Events API v2 integration key"
},
"api_key": {
"type": "string",
"description": "opsgenie: API integration key"
},
"region": {
"type": "string",
"description": "opsgenie: account region",
"enum": [
"us",
"eu"
]
},
"kind": {
"type": "string",
"description": "email, slack, teams, discord, webhook, pagerduty, opsgenie or push",
"enum": [
"email",
"slack",
"teams",
"discord",
"webhook",
"pagerduty",
"opsgenie",
"push"
]
},
"name": {
"type": "string",
"description": "Display name",
"examples": [
"#alerts"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"kind",
"name",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Channel id, e.g. nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email, slack, teams, discord, webhook, pagerduty, opsgenie or push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Masked destination"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/channels/:id.json
Delete a notification channel
notification_channels_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/channels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Channel id, e.g. nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email, slack, teams, discord, webhook, pagerduty, opsgenie or push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Masked destination"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/channels.json
List notification channels
notification_channels_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/channels.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "Only channels of this kind",
"enum": [
"email",
"slack",
"teams",
"discord",
"webhook",
"pagerduty",
"opsgenie",
"push"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Channel id, e.g. nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email, slack, teams, discord, webhook, pagerduty, opsgenie or push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Masked destination"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/channels/:id/send_test.json
Send a test message through a channel
notification_channels_send_test
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/channels/:id/send_test.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Channel id, e.g. nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email, slack, teams, discord, webhook, pagerduty, opsgenie or push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Masked destination"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/channels/:id.json
Get a notification channel
notification_channels_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/channels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Channel id, e.g. nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email, slack, teams, discord, webhook, pagerduty, opsgenie or push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Masked destination"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/channels/:id.json
Update a notification channel
notification_channels_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/channels/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Webhook URL (slack, teams, discord, webhook), HTTPS"
},
"secret": {
"type": "string",
"description": "webhook: HMAC secret for X-Privatus-Signature"
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"description": "email: recipient addresses (max 20)"
},
"routing_key": {
"type": "string",
"description": "pagerduty: Events API v2 integration key"
},
"api_key": {
"type": "string",
"description": "opsgenie: API integration key"
},
"region": {
"type": "string",
"description": "opsgenie: account region",
"enum": [
"us",
"eu"
]
},
"name": {
"type": "string",
"description": "Display name"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Channel id, e.g. nch_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "email, slack, teams, discord, webhook, pagerduty, opsgenie or push"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Masked destination"
},
"last_used_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/push_subscription.json
Register a browser for push notifications
push_subscriptions_create
Permission: member
Example
curl -X POST https://privatusanalytics.com/push_subscription.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"endpoint": {
"type": "string",
"description": "PushSubscription.endpoint from the browser"
},
"p256dh": {
"type": "string",
"description": "PushSubscription keys.p256dh (base64url)"
},
"auth": {
"type": "string",
"description": "PushSubscription keys.auth (base64url)"
}
},
"required": [
"endpoint",
"p256dh",
"auth"
]
}
Response data
{
"type": "object",
"properties": {
"endpoint_host": {
"type": "string",
"description": "Push service host"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/push_subscription.json
Remove a browser push registration
push_subscriptions_delete
Permission: member
Example
curl -X DELETE https://privatusanalytics.com/push_subscription.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"endpoint": {
"type": "string",
"description": "PushSubscription.endpoint to remove"
}
},
"required": [
"endpoint"
]
}
Response data
{
"type": "object",
"properties": {
"endpoint_host": {
"type": "string",
"description": "Push service host"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Performance
GET
/sites/:site_id/performance.json
Web Vitals: p75 scorecard, daily trend and breakdowns by page, device, browser and country
performance_report
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/performance.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"metric": {
"type": "string",
"description": "Metric for the trend and breakdowns",
"enum": [
"LCP",
"INP",
"CLS",
"FCP",
"TTFB"
],
"default": "LCP"
},
"limit": {
"type": "integer",
"description": "Rows per breakdown (max 100)",
"default": 10
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
Plans
GET
/plans.json
List plans, prices and limits
plans_list
Permission: public
Example
curl https://privatusanalytics.com/plans.jsonInputs
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": []
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"events": {
"anyOf": [
{
"type": "integer",
"description": "Included events a month (free plan only)"
},
{
"type": "null"
}
]
},
"badge_bonus": {
"anyOf": [
{
"type": "integer",
"description": "Extra events a month for showing the badge (free plan)"
},
{
"type": "null"
}
]
},
"limits": {
"type": "object",
"description": "Plan limits. Null means unlimited"
},
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"events": {
"type": "integer",
"description": "Events a month included"
},
"monthly": {
"type": "integer",
"description": "USD a month, billed monthly"
},
"yearly": {
"type": "integer",
"description": "USD a year, billed yearly (2 months free)"
},
"monthly_price_id": {
"anyOf": [
{
"type": "string",
"description": "Paddle price id (monthly)"
},
{
"type": "null"
}
]
},
"yearly_price_id": {
"anyOf": [
{
"type": "string",
"description": "Paddle price id (yearly)"
},
{
"type": "null"
}
]
}
}
},
"description": "Price ladder by events a month"
},
"contact_sales": {
"type": "boolean",
"description": "Priced per contract"
}
}
}
}
Roles
POST
/workspaces/:workspace_id/roles.json
Create a custom role
roles_create
Permission: members.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/roles.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Role name",
"examples": [
"Client reviewer"
]
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"analytics.read",
"analytics.export",
"content.write",
"sites.manage",
"uptime.manage",
"members.manage",
"tokens.manage",
"billing.manage",
"workspace.manage"
]
},
"description": "Permissions granted by the role"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"permissions",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Custom role id (custom_role_id on members)"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Granted permissions"
},
"members": {
"type": "integer",
"description": "Members with this role"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/roles/:id.json
Delete a custom role (must be unused)
roles_delete
Permission: members.manage
Example
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/roles/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Custom role id (custom_role_id on members)"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Granted permissions"
},
"members": {
"type": "integer",
"description": "Members with this role"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/roles.json
List custom roles
roles_list
Permission: member
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/roles.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Custom role id (custom_role_id on members)"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Granted permissions"
},
"members": {
"type": "integer",
"description": "Members with this role"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/workspaces/:workspace_id/roles/:id.json
Update a custom role
roles_update
Permission: members.manage
Example
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/roles/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Role name"
},
"permissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"analytics.read",
"analytics.export",
"content.write",
"sites.manage",
"uptime.manage",
"members.manage",
"tokens.manage",
"billing.manage",
"workspace.manage"
]
},
"description": "Permissions granted by the role"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Custom role id (custom_role_id on members)"
},
"name": {
"type": "string"
},
"permissions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Granted permissions"
},
"members": {
"type": "integer",
"description": "Members with this role"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
SCIM
POST
/scim/v2/Users.json
Provision a user
scim_users_create
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/scim/v2/Users.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"userName": {
"type": "string",
"description": "Email address"
},
"name": {
"type": "object",
"additionalProperties": true,
"description": "givenName, familyName, formatted",
"default": {}
},
"active": {
"type": "boolean",
"description": "Member of the workspace",
"default": true
}
},
"required": [
"userName"
]
}
Response data
{
"type": "object"
}
DELETE
/scim/v2/Users/:id.json
Deprovision a user
scim_users_delete
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X DELETE https://privatusanalytics.com/scim/v2/Users/:id.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object"
}
GET
/scim/v2/Users.json
List provisioned users
scim_users_list
Permission: public
· HTTP only (not an MCP tool)
Example
curl https://privatusanalytics.com/scim/v2/Users.jsonInputs
{
"type": "object",
"properties": {
"scim_filter": {
"type": "string",
"description": "SCIM filter (query param `filter`), e.g. userName eq \"[email protected]\""
},
"startIndex": {
"type": "integer",
"description": "1-based index of the first result",
"default": 1
},
"count": {
"type": "integer",
"description": "Page size (max 200)",
"default": 100
}
},
"required": []
}
Response data
{
"type": "object"
}
GET
/scim/v2/Users/:id.json
Get a provisioned user
scim_users_get
Permission: public
· HTTP only (not an MCP tool)
Example
curl https://privatusanalytics.com/scim/v2/Users/:id.jsonInputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object"
}
PATCH
/scim/v2/Users/:id.json
Update a user (PATCH active, name)
scim_users_update
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X PATCH https://privatusanalytics.com/scim/v2/Users/:id.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"Operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"description": "SCIM PatchOp operations"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"Operations",
"id"
]
}
Response data
{
"type": "object"
}
SSO
POST
/workspaces/:workspace_id/sso/activate.json
Activate a tested SSO configuration
sso_activate
Permission: workspace.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/activate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml or oidc"
},
"status": {
"type": "string",
"description": "draft, testing, tested or active"
},
"enforced": {
"type": "boolean",
"description": "SSO is the only way in (owner excepted)"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Verified email domains"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
POST
/workspaces/:workspace_id/sso/deactivate.json
Turn SSO off (back to draft)
sso_deactivate
Permission: workspace.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/deactivate.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml or oidc"
},
"status": {
"type": "string",
"description": "draft, testing, tested or active"
},
"enforced": {
"type": "boolean",
"description": "SSO is the only way in (owner excepted)"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Verified email domains"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
POST
/workspaces/:workspace_id/sso/scim_token.json
Generate a new SCIM token (shown once)
sso_scim_token
Permission: workspace.manage
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sso/scim_token.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object"
}
GET
/workspaces/:workspace_id/sso.json
Get SSO settings
sso_get
Permission: workspace.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/sso.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml or oidc"
},
"status": {
"type": "string",
"description": "draft, testing, tested or active"
},
"enforced": {
"type": "boolean",
"description": "SSO is the only way in (owner excepted)"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Verified email domains"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
PATCH
/workspaces/:workspace_id/sso.json
Create or update SSO settings
sso_update
Permission: workspace.manage
Example
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/sso.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml or oidc",
"enum": [
"saml",
"oidc"
]
},
"idp_sso_url": {
"type": "string",
"description": "SAML: IdP single sign-on URL"
},
"idp_entity_id": {
"type": "string",
"description": "SAML: IdP entity id (issuer)"
},
"idp_cert": {
"type": "string",
"description": "SAML: IdP X.509 signing certificate (PEM)"
},
"oidc_issuer": {
"type": "string",
"description": "OIDC: issuer URL (discovery)"
},
"oidc_client_id": {
"type": "string",
"description": "OIDC: client id"
},
"oidc_client_secret": {
"type": "string",
"description": "OIDC: client secret (write-only)"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Verified email domains that use this SSO"
},
"default_role": {
"type": "string",
"description": "Role for members created by JIT or SCIM",
"enum": [
"admin",
"editor",
"analyst",
"viewer",
"billing"
]
},
"jit_provisioning": {
"type": "boolean",
"description": "Create members on first SSO login"
},
"enforced": {
"type": "boolean",
"description": "Only allow SSO logins (needs an active config)"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"protocol": {
"type": "string",
"description": "saml or oidc"
},
"status": {
"type": "string",
"description": "draft, testing, tested or active"
},
"enforced": {
"type": "boolean",
"description": "SSO is the only way in (owner excepted)"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Verified email domains"
},
"idp_sso_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_entity_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"idp_cert_present": {
"type": "boolean"
},
"oidc_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"oidc_client_secret_present": {
"type": "boolean"
},
"default_role": {
"type": "string"
},
"jit_provisioning": {
"type": "boolean"
},
"scim_enabled": {
"type": "boolean"
}
}
}
Search
GET
/sites/:site_id/search.json
Search report: clicks, impressions, CTR, position, top queries/pages, landing pages and opportunities
search_report
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/search.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"period": {
"type": "string",
"description": "Date range preset. Use custom with from/to",
"enum": [
"today",
"yesterday",
"24h",
"7d",
"14d",
"28d",
"30d",
"90d",
"mtd",
"last_month",
"qtd",
"last_quarter",
"ytd",
"12mo",
"last_year",
"all",
"custom"
],
"default": "30d"
},
"from": {
"type": "string",
"format": "date",
"description": "Custom range start (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Custom range end, inclusive"
},
"compare": {
"type": "string",
"description": "Comparison period",
"enum": [
"none",
"previous_period",
"previous_year",
"custom"
],
"default": "none"
},
"compare_from": {
"type": "string",
"format": "date",
"description": "Custom comparison start"
},
"compare_to": {
"type": "string",
"format": "date",
"description": "Custom comparison end"
},
"match_weekday": {
"type": "boolean",
"description": "Align comparison days of the week",
"default": false
},
"filters": {
"type": "array",
"items": {},
"description": "Filters: [[\"dimension\",\"operator\",\"value\"], …]. Operators: is, is_not, any_of, none_of, contains, not_contains, starts_with, regex, not_regex, gt, lt, between. Wrap conditions in {\"any\": [...]} for OR.",
"default": []
},
"segment_id": {
"type": "string",
"description": "Apply a saved segment (seg_…)"
},
"include_imported": {
"type": "boolean",
"description": "Add imported historical data (dates before the first native event, ignored when filters or a segment are applied)",
"default": false
},
"provider": {
"type": "string",
"description": "google (Search Console) or bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"limit": {
"type": "integer",
"description": "Rows per table (max 100)",
"default": 25
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
POST
/sites/:site_id/search/connections.json
Connect a Search Console property or Bing site
search_connect
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/search/connections.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google or bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"property": {
"type": "string",
"description": "Search Console property (e.g. sc-domain:example.com) or Bing site URL",
"examples": [
"sc-domain:example.com"
]
},
"bing_api_key": {
"type": "string",
"description": "Your own Bing Webmaster Tools API key (Settings > API access). Required when provider is bing. Stored encrypted and never returned."
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"property",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google or bing"
},
"property": {
"type": "string",
"description": "Search Console property or Bing site URL"
},
"status": {
"type": "string",
"description": "active or error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/search/connections/:provider.json
Disconnect Search Console or Bing and delete its data
search_disconnect
Permission: sites.manage
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/search/connections/:provider.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"provider": {
"type": "string",
"description": "Provider of the resource"
}
},
"required": [
"site_id",
"provider"
]
}
Response data
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google or bing"
},
"property": {
"type": "string",
"description": "Search Console property or Bing site URL"
},
"status": {
"type": "string",
"description": "active or error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/search/properties.json
List properties you can connect (Search Console needs a Google grant from the browser)
search_properties
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/search/properties.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google or bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"bing_api_key": {
"type": "string",
"description": "Your own Bing Webmaster Tools API key (Settings > API access). Required when provider is bing. Only used to list the sites it can see."
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
POST
/sites/:site_id/search/sync.json
Import search data now
search_sync
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/search/sync.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google or bing",
"enum": [
"google",
"bing"
],
"default": "google"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"description": "google or bing"
},
"property": {
"type": "string",
"description": "Search Console property or Bing site URL"
},
"status": {
"type": "string",
"description": "active or error"
},
"last_synced_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Segments
POST
/sites/:site_id/segments.json
Save filters as a segment
segments_create
Permission: content.write
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/segments.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Segment name, e.g. \"Mobile visitors from ads\"",
"examples": [
"Mobile visitors from ads"
]
},
"description": {
"type": "string",
"description": "Optional note on what the segment is for (300 characters at most)",
"examples": [
"People who might buy the Pro plan"
]
},
"filters": {
"type": "array",
"items": {},
"description": "Filters, all of which must match. Each item is a condition [\"dimension\", \"operator\", \"value\"], or {\"any\": [conditions]} when any one of several may match. Dimensions: page, entry_page, exit_page, hostname, channel, referrer, referrer_url, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, country (ISO code, e.g. US), language, device (desktop, mobile, tablet, tv, other), browser, browser_version, os, os_version, screen, goal (goal id), event (custom event name) and prop:<key> (custom event property). Operators: is, is_not, contains, not_contains, starts_with, regex, not_regex, any_of and none_of (value is a list), gt and lt (a number), between (a list of two numbers). Rows from the segment form are accepted too: {\"dimension\", \"operator\", \"value\", \"property\" (for dimension prop), \"join\": \"and\" or \"or\" (or combines the row with the one before it)}. Example: [[\"country\", \"is\", \"US\"], [\"device\", \"is\", \"mobile\"], {\"any\": [[\"page\", \"starts_with\", \"/pricing\"], [\"goal\", \"is\", \"goal_7Q2K9XH3AB\"]]}]",
"examples": [
[
[
"country",
"is",
"US"
],
[
"device",
"is",
"mobile"
],
{
"any": [
[
"page",
"starts_with",
"/pricing"
],
[
"goal",
"is",
"goal_7Q2K9XH3AB"
]
]
}
]
]
},
"shared": {
"type": "boolean",
"description": "Visible to everyone with access to the site (false: only you)",
"default": true
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"name",
"filters",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Segment id, e.g. seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "What the segment is for, or null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "Filters in the stats filter format: conditions [\"dimension\", \"operator\", \"value\"] that must all match, and {\"any\": [conditions]} groups"
},
"summary": {
"type": "string",
"description": "The filters in plain English, e.g. \"Visitors from the United States on mobile who viewed /pricing\""
},
"shared": {
"type": "boolean",
"description": "Visible to everyone with access to the site"
},
"mine": {
"type": "boolean",
"description": "Created by you"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/segments/:id.json
Delete a segment
segments_delete
Permission: content.write
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/segments/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Segment id, e.g. seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "What the segment is for, or null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "Filters in the stats filter format: conditions [\"dimension\", \"operator\", \"value\"] that must all match, and {\"any\": [conditions]} groups"
},
"summary": {
"type": "string",
"description": "The filters in plain English, e.g. \"Visitors from the United States on mobile who viewed /pricing\""
},
"shared": {
"type": "boolean",
"description": "Visible to everyone with access to the site"
},
"mine": {
"type": "boolean",
"description": "Created by you"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/segments.json
List segments you can use on a site
segments_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/segments.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Segment id, e.g. seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "What the segment is for, or null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "Filters in the stats filter format: conditions [\"dimension\", \"operator\", \"value\"] that must all match, and {\"any\": [conditions]} groups"
},
"summary": {
"type": "string",
"description": "The filters in plain English, e.g. \"Visitors from the United States on mobile who viewed /pricing\""
},
"shared": {
"type": "boolean",
"description": "Visible to everyone with access to the site"
},
"mine": {
"type": "boolean",
"description": "Created by you"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/sites/:site_id/segments/preview.json
Describe filters in plain English and count the visitors they matched in the last 30 days
segments_preview
Permission: analytics.read
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/segments/preview.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"filters": {
"type": "array",
"items": {},
"description": "Filters, all of which must match. Each item is a condition [\"dimension\", \"operator\", \"value\"], or {\"any\": [conditions]} when any one of several may match. Dimensions: page, entry_page, exit_page, hostname, channel, referrer, referrer_url, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, country (ISO code, e.g. US), language, device (desktop, mobile, tablet, tv, other), browser, browser_version, os, os_version, screen, goal (goal id), event (custom event name) and prop:<key> (custom event property). Operators: is, is_not, contains, not_contains, starts_with, regex, not_regex, any_of and none_of (value is a list), gt and lt (a number), between (a list of two numbers). Rows from the segment form are accepted too: {\"dimension\", \"operator\", \"value\", \"property\" (for dimension prop), \"join\": \"and\" or \"or\" (or combines the row with the one before it)}. Example: [[\"country\", \"is\", \"US\"], [\"device\", \"is\", \"mobile\"], {\"any\": [[\"page\", \"starts_with\", \"/pricing\"], [\"goal\", \"is\", \"goal_7Q2K9XH3AB\"]]}]",
"examples": [
[
[
"country",
"is",
"US"
],
[
"device",
"is",
"mobile"
],
{
"any": [
[
"page",
"starts_with",
"/pricing"
],
[
"goal",
"is",
"goal_7Q2K9XH3AB"
]
]
}
]
],
"default": []
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/segments/:id.json
Get a segment
segments_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/segments/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Segment id, e.g. seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "What the segment is for, or null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "Filters in the stats filter format: conditions [\"dimension\", \"operator\", \"value\"] that must all match, and {\"any\": [conditions]} groups"
},
"summary": {
"type": "string",
"description": "The filters in plain English, e.g. \"Visitors from the United States on mobile who viewed /pricing\""
},
"shared": {
"type": "boolean",
"description": "Visible to everyone with access to the site"
},
"mine": {
"type": "boolean",
"description": "Created by you"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:site_id/segments/:id.json
Rename a segment or change its filters or sharing
segments_update
Permission: content.write
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/segments/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Segment name"
},
"description": {
"type": "string",
"description": "Optional note on what the segment is for (300 characters at most, empty to clear)"
},
"filters": {
"type": "array",
"items": {},
"description": "Replacement filters, in the same format as when creating. Filters, all of which must match. Each item is a condition [\"dimension\", \"operator\", \"value\"], or {\"any\": [conditions]} when any one of several may match. Dimensions: page, entry_page, exit_page, hostname, channel, referrer, referrer_url, ref, utm_source, utm_medium, utm_campaign, utm_content, utm_term, country (ISO code, e.g. US), language, device (desktop, mobile, tablet, tv, other), browser, browser_version, os, os_version, screen, goal (goal id), event (custom event name) and prop:<key> (custom event property). Operators: is, is_not, contains, not_contains, starts_with, regex, not_regex, any_of and none_of (value is a list), gt and lt (a number), between (a list of two numbers). Rows from the segment form are accepted too: {\"dimension\", \"operator\", \"value\", \"property\" (for dimension prop), \"join\": \"and\" or \"or\" (or combines the row with the one before it)}. Example: [[\"country\", \"is\", \"US\"], [\"device\", \"is\", \"mobile\"], {\"any\": [[\"page\", \"starts_with\", \"/pricing\"], [\"goal\", \"is\", \"goal_7Q2K9XH3AB\"]]}]",
"examples": [
[
[
"country",
"is",
"US"
],
[
"device",
"is",
"mobile"
],
{
"any": [
[
"page",
"starts_with",
"/pricing"
],
[
"goal",
"is",
"goal_7Q2K9XH3AB"
]
]
}
]
]
},
"shared": {
"type": "boolean",
"description": "Visible to everyone on the site"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Segment id, e.g. seg_7Q2K9XH3AB"
},
"site_id": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string",
"description": "What the segment is for, or null"
},
{
"type": "null"
}
]
},
"filters": {
"type": "array",
"description": "Filters in the stats filter format: conditions [\"dimension\", \"operator\", \"value\"] that must all match, and {\"any\": [conditions]} groups"
},
"summary": {
"type": "string",
"description": "The filters in plain English, e.g. \"Visitors from the United States on mobile who viewed /pricing\""
},
"shared": {
"type": "boolean",
"description": "Visible to everyone with access to the site"
},
"mine": {
"type": "boolean",
"description": "Created by you"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
Sharing
GET
/badge/:site_id.json
Visitor counter badge (SVG) for a public site
badges_get
Permission: public
· HTTP only (not an MCP tool)
Example
curl https://privatusanalytics.com/badge/:site_id.jsonInputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
Sites
POST
/sites/:site_id/data_reset.json
Delete all events and visits in a date range (runs in the background, cannot be undone)
sites_reset_data
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/data_reset.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"from": {
"type": "string",
"format": "date",
"description": "First day to delete (site timezone)"
},
"to": {
"type": "string",
"format": "date",
"description": "Last day to delete, inclusive"
},
"confirm": {
"type": "string",
"description": "Type the domain to confirm"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"from",
"to",
"confirm",
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/filter_stats.json
Filtered traffic summary: bots, traffic rules or PII redactions by reason and country (counts only)
sites_filter_stats
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/filter_stats.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "bot (bots filtered), rule (traffic rules) or redaction (PII scrubber)",
"enum": [
"bot",
"rule",
"redaction"
],
"default": "bot"
},
"days": {
"type": "integer",
"description": "Days to look back (1-395)",
"default": 30
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/access.json
List members and whether they can see this site
sites_access_list
Permission: members.manage
Example
curl https://privatusanalytics.com/sites/:site_id/access.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"format": "uuid",
"description": "Membership id"
},
"email": {
"type": "string"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"access": {
"type": "boolean",
"description": "Can see this site"
},
"locked": {
"type": "boolean",
"description": "Owners and admins always have access"
}
}
}
PATCH
/sites/:site_id/access.json
Grant or remove one member's access to this site
sites_access_update
Permission: members.manage
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/access.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"description": "Membership id from sites_access_list"
},
"access": {
"type": "boolean",
"description": "true to grant access, false to remove it"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"membership_id",
"access",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"membership_id": {
"type": "string",
"format": "uuid",
"description": "Membership id"
},
"email": {
"type": "string"
},
"name": {
"type": "string"
},
"role": {
"type": "string"
},
"access": {
"type": "boolean",
"description": "Can see this site"
},
"locked": {
"type": "boolean",
"description": "Owners and admins always have access"
}
}
}
POST
/sites/:site_id/favorite.json
Star a site (pinned first on All sites)
sites_favorite
Permission: analytics.read
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/favorite.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Site id used in the tracking snippet"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "Start of the server ingest key"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML tracking snippet"
},
"favorite": {
"type": "boolean",
"description": "Starred by you"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/favorite.json
Unstar a site
sites_unfavorite
Permission: analytics.read
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/favorite.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Site id used in the tracking snippet"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "Start of the server ingest key"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML tracking snippet"
},
"favorite": {
"type": "boolean",
"description": "Starred by you"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/setup.json
Installation status and snippet for a site
sites_setup_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/setup.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
POST
/transfers/:token/accept.json
Accept a site transfer into one of your workspaces
site_transfers_accept
Permission: public
Example
curl -X POST https://privatusanalytics.com/transfers/:token/accept.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace to move the site into (ws_…)"
},
"token": {
"type": "string",
"description": "Token of the resource"
}
},
"required": [
"workspace_id",
"token"
]
}
Response data
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site being transferred"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "Current workspace name"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "Receiving workspace"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "Recipient email"
},
"status": {
"type": "string",
"description": "pending, accepted or canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/transfer.json
Start transferring a site to another workspace (emails the recipient)
sites_transfer_start
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/transfer.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email of the person who will receive the site (they choose one of their workspaces)"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"email",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site being transferred"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "Current workspace name"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "Receiving workspace"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "Recipient email"
},
"status": {
"type": "string",
"description": "pending, accepted or canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/transfer.json
Cancel a pending site transfer
sites_transfer_cancel
Permission: sites.manage
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/transfer.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site being transferred"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "Current workspace name"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "Receiving workspace"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "Recipient email"
},
"status": {
"type": "string",
"description": "pending, accepted or canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/transfers/:token.json
Get a pending transfer from its emailed token
site_transfers_get
Permission: public
Example
curl https://privatusanalytics.com/transfers/:token.jsonInputs
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token of the resource"
}
},
"required": [
"token"
]
}
Response data
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site being transferred"
},
"site_domain": {
"type": "string"
},
"from_workspace": {
"type": "string",
"description": "Current workspace name"
},
"to_workspace_id": {
"anyOf": [
{
"type": "string",
"description": "Receiving workspace"
},
{
"type": "null"
}
]
},
"to_email": {
"type": "string",
"description": "Recipient email"
},
"status": {
"type": "string",
"description": "pending, accepted or canceled"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/sites.json
Add a site
sites_create
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/sites.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"domain": {
"type": "string",
"description": "Primary domain, e.g. example.com",
"examples": [
"example.com"
]
},
"name": {
"type": "string",
"description": "Display name (defaults to the domain)"
},
"timezone": {
"type": "string",
"description": "Reporting timezone"
},
"currency": {
"type": "string",
"description": "Currency for revenue (ISO 4217)"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"domain",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Site id used in the tracking snippet"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "Start of the server ingest key"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML tracking snippet"
},
"favorite": {
"type": "boolean",
"description": "Starred by you"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:id.json
Delete a site (purged after 7 days)
sites_delete
Permission: sites.manage
Example
curl -X DELETE https://privatusanalytics.com/sites/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"confirm": {
"type": "string",
"description": "Type the domain to confirm"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"confirm",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Site id used in the tracking snippet"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "Start of the server ingest key"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML tracking snippet"
},
"favorite": {
"type": "boolean",
"description": "Starred by you"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/sites.json
List sites in a workspace
sites_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/sites.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Filter by domain or name"
},
"label": {
"type": "string",
"description": "Only sites with this label"
},
"sort": {
"type": "string",
"description": "position (your order), name, or visitors in the last 30 days (most first)",
"enum": [
"position",
"name",
"visitors"
],
"default": "position"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Site id used in the tracking snippet"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "Start of the server ingest key"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML tracking snippet"
},
"favorite": {
"type": "boolean",
"description": "Starred by you"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/sites/:id.json
Get a site and all its settings
sites_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Site id used in the tracking snippet"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "Start of the server ingest key"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML tracking snippet"
},
"favorite": {
"type": "boolean",
"description": "Starred by you"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/sites/:id.json
Update site settings
sites_update
Permission: sites.manage
Example
curl -X PATCH https://privatusanalytics.com/sites/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name"
},
"domain": {
"type": "string",
"description": "Primary domain"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Additional hostnames"
},
"multi_domain_mode": {
"type": "string",
"description": "combined: one visitor across domains",
"enum": [
"combined",
"separate"
]
},
"timezone": {
"type": "string",
"description": "Reporting timezone"
},
"currency": {
"type": "string",
"description": "Revenue currency (ISO 4217)"
},
"week_start": {
"type": "integer",
"description": "0 = Sunday, 1 = Monday"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "Labels for grouping sites"
},
"honor_dnt": {
"type": "boolean",
"description": "Skip visitors sending DNT"
},
"honor_gpc": {
"type": "boolean",
"description": "Skip visitors sending GPC"
},
"pii_scrubber": {
"type": "boolean",
"description": "Redact emails, tokens, ids"
},
"redaction_rules": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"pattern": {
"type": "string"
}
}
},
"description": "Custom redaction regexes"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
},
"description": "Query parameters to keep on paths"
},
"path_masks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"replacement": {
"type": "string"
}
}
},
"description": "Path masking rules, e.g. /u/* -> /u/:id"
},
"retention_months": {
"type": "integer",
"description": "Delete data older than this"
},
"bot_filtering": {
"type": "boolean",
"description": "Filter bot traffic"
},
"traffic_rule_modes": {
"type": "object",
"additionalProperties": true,
"description": "block or allow per traffic rule list"
},
"vitals_sample_rate": {
"type": "integer",
"description": "Web Vitals sample %"
},
"conversion_denominator": {
"type": "string",
"description": "Conversion rate over visits or visitors",
"enum": [
"visits",
"visitors"
]
},
"public_dashboard": {
"type": "boolean",
"description": "Anyone with the link can view stats"
},
"public_indexable": {
"type": "boolean",
"description": "Let search engines index the public page"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Site id used in the tracking snippet"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "Start of the server ingest key"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML tracking snippet"
},
"favorite": {
"type": "boolean",
"description": "Starred by you"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Status pages
GET
/status/:slug/confirm/:token.json
Confirm a subscription from the emailed link
public_status_pages_confirm
Permission: public
· HTTP only (not an MCP tool)
Example
curl https://privatusanalytics.com/status/:slug/confirm/:token.jsonInputs
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token of the resource"
},
"slug": {
"type": "string",
"description": "Slug of the resource"
}
},
"required": [
"token",
"slug"
]
}
Response data
{
"type": "object"
}
GET
/status/:slug.json
Public status page: current status, 90-day uptime bars, incidents and posts
public_status_pages_get
Permission: public
· HTTP only (not an MCP tool)
Example
curl https://privatusanalytics.com/status/:slug.jsonInputs
{
"type": "object",
"properties": {
"slug": {
"type": "string",
"description": "Slug of the resource"
}
},
"required": [
"slug"
]
}
Response data
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "operational, degraded or outage"
},
"checks": {
"type": "array",
"description": "Each: {name, status, uptime_90d, days: [{date, uptime, downtime_seconds}]}"
},
"posts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Post id (spp_…)"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating, identified, monitoring or resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
},
"incidents": {
"type": "array",
"description": "Recent incidents: {check, started_at, resolved_at, duration_seconds}"
}
}
}
POST
/status/:slug/subscribers.json
Subscribe an email address (double opt-in)
public_status_pages_subscribe
Browser clients send a Cloudflare Turnstile token as `cf-turnstile-response`. Requests with an API token need none.
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/status/:slug/subscribers.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address to notify",
"examples": [
"[email protected]"
]
},
"slug": {
"type": "string",
"description": "Slug of the resource"
}
},
"required": [
"email",
"slug"
]
}
Response data
{
"type": "object"
}
POST
/status/:slug/unsubscribe/:token.json
Unsubscribe with the emailed token
public_status_pages_unsubscribe
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/status/:slug/unsubscribe/:token.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Token of the resource"
},
"slug": {
"type": "string",
"description": "Slug of the resource"
}
},
"required": [
"token",
"slug"
]
}
Response data
{
"type": "object"
}
POST
/status_pages/:status_page_id/posts.json
Post an incident update (emails subscribers)
status_page_posts_create
Permission: uptime.manage
Example
curl -X POST https://privatusanalytics.com/status_pages/:status_page_id/posts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Headline, e.g. \"Elevated error rates\""
},
"body": {
"type": "string",
"description": "Update text (plain text)"
},
"status": {
"type": "string",
"description": "investigating, identified, monitoring or resolved",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"default": "investigating"
},
"posted_at": {
"type": "string",
"format": "date-time",
"description": "When it happened (defaults to now)"
},
"notify": {
"type": "boolean",
"description": "Email confirmed subscribers",
"default": true
},
"status_page_id": {
"type": "string",
"description": "Status page of the resource"
}
},
"required": [
"title",
"status_page_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Post id (spp_…)"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating, identified, monitoring or resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/status_pages/:status_page_id/posts/:id.json
Delete a status page post
status_page_posts_delete
Permission: uptime.manage
Example
curl -X DELETE https://privatusanalytics.com/status_pages/:status_page_id/posts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"status_page_id": {
"type": "string",
"description": "Status page of the resource"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"status_page_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Post id (spp_…)"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating, identified, monitoring or resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/status_pages/:status_page_id/posts.json
List posts on a status page
status_page_posts_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/status_pages/:status_page_id/posts.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Only posts with this status",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"status_page_id": {
"type": "string",
"description": "Status page of the resource"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"status_page_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Post id (spp_…)"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating, identified, monitoring or resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
}
PATCH
/status_pages/:status_page_id/posts/:id.json
Edit a status page post
status_page_posts_update
Permission: uptime.manage
Example
curl -X PATCH https://privatusanalytics.com/status_pages/:status_page_id/posts/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Headline"
},
"body": {
"type": "string",
"description": "Update text (plain text)"
},
"status": {
"type": "string",
"description": "investigating, identified, monitoring or resolved",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"notify": {
"type": "boolean",
"description": "Email confirmed subscribers if the status changes",
"default": true
},
"status_page_id": {
"type": "string",
"description": "Status page of the resource"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"status_page_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Post id (spp_…)"
},
"title": {
"type": "string"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"description": "investigating, identified, monitoring or resolved"
},
"posted_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/status_pages/:status_page_id/subscribers/:id.json
Remove a subscriber
status_page_subscribers_delete
Permission: uptime.manage
Example
curl -X DELETE https://privatusanalytics.com/status_pages/:status_page_id/subscribers/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"status_page_id": {
"type": "string",
"description": "Status page of the resource"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"status_page_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/status_pages/:status_page_id/subscribers.json
List subscribers of a status page
status_page_subscribers_list
Permission: uptime.manage
Example
curl https://privatusanalytics.com/status_pages/:status_page_id/subscribers.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"confirmed": {
"type": "boolean",
"description": "true: confirmed only, false: pending only"
},
"status_page_id": {
"type": "string",
"description": "Status page of the resource"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"status_page_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string"
},
"confirmed_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/workspaces/:workspace_id/status_pages.json
Create a status page
status_pages_create
Permission: uptime.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/status_pages.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Page title, e.g. \"Acme status\""
},
"slug": {
"type": "string",
"description": "Public URL slug: /status/<slug> (defaults from name)"
},
"description": {
"type": "string",
"description": "Intro text under the title"
},
"logo_url": {
"type": "string",
"description": "HTTPS URL of a logo image"
},
"brand_color": {
"type": "string",
"description": "Accent color, e.g. #06755b"
},
"custom_domain": {
"type": "string",
"description": "Custom domain (CNAME to our host), e.g. status.example.com. Empty to remove"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Uptime check ids (upc_…) to show"
},
"published": {
"type": "boolean",
"description": "Visible to the public",
"default": true
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"name",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Status page id (sp_…)"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "Public URL: /status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Uptime check ids shown"
},
"subscribers": {
"type": "integer",
"description": "Confirmed subscribers"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/status_pages/:id.json
Delete a status page
status_pages_delete
Permission: uptime.manage
Example
curl -X DELETE https://privatusanalytics.com/status_pages/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Status page id (sp_…)"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "Public URL: /status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Uptime check ids shown"
},
"subscribers": {
"type": "integer",
"description": "Confirmed subscribers"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/status_pages.json
List status pages
status_pages_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/status_pages.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Filter by name or slug"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Status page id (sp_…)"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "Public URL: /status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Uptime check ids shown"
},
"subscribers": {
"type": "integer",
"description": "Confirmed subscribers"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/status_pages/:id.json
Get a status page
status_pages_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/status_pages/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Status page id (sp_…)"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "Public URL: /status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Uptime check ids shown"
},
"subscribers": {
"type": "integer",
"description": "Confirmed subscribers"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/status_pages/:id.json
Change a status page
status_pages_update
Permission: uptime.manage
Example
curl -X PATCH https://privatusanalytics.com/status_pages/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Page title, e.g. \"Acme status\""
},
"slug": {
"type": "string",
"description": "Public URL slug: /status/<slug> (defaults from name)"
},
"description": {
"type": "string",
"description": "Intro text under the title"
},
"logo_url": {
"type": "string",
"description": "HTTPS URL of a logo image"
},
"brand_color": {
"type": "string",
"description": "Accent color, e.g. #06755b"
},
"custom_domain": {
"type": "string",
"description": "Custom domain (CNAME to our host), e.g. status.example.com. Empty to remove"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Uptime check ids (upc_…) to show"
},
"published": {
"type": "boolean",
"description": "Visible to the public"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Status page id (sp_…)"
},
"workspace_id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string",
"description": "Public URL: /status/<slug>"
},
"custom_domain": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"logo_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"published": {
"type": "boolean"
},
"check_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Uptime check ids shown"
},
"subscribers": {
"type": "integer",
"description": "Confirmed subscribers"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Tracking
POST
/sites/:site_id/tracking/ingest_key.json
Create or rotate the server ingest key (shown once)
tracking_ingest_key_rotate
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/tracking/ingest_key.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id"
},
"key": {
"type": "string",
"description": "The ingest key. Shown once: store it now. Send it as a Bearer token to POST /api/events"
},
"prefix": {
"type": "string",
"description": "Key prefix shown in settings"
}
}
}
DELETE
/sites/:site_id/tracking/ingest_key.json
Revoke the server ingest key
tracking_ingest_key_revoke
Permission: sites.manage
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/tracking/ingest_key.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Site id used in the tracking snippet"
},
"workspace_id": {
"type": "string"
},
"domain": {
"type": "string"
},
"name": {
"type": "string"
},
"extra_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"multi_domain_mode": {
"type": "string"
},
"timezone": {
"type": "string"
},
"currency": {
"type": "string"
},
"week_start": {
"type": "integer"
},
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"honor_dnt": {
"type": "boolean"
},
"honor_gpc": {
"type": "boolean"
},
"pii_scrubber": {
"type": "boolean"
},
"redaction_rules": {
"type": "array"
},
"allowed_params": {
"type": "array",
"items": {
"type": "string"
}
},
"path_masks": {
"type": "array"
},
"retention_months": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"bot_filtering": {
"type": "boolean"
},
"traffic_rule_modes": {
"type": "object"
},
"vitals_sample_rate": {
"type": "integer"
},
"conversion_denominator": {
"type": "string"
},
"public_dashboard": {
"type": "boolean"
},
"public_indexable": {
"type": "boolean"
},
"ingest_key_prefix": {
"anyOf": [
{
"type": "string",
"description": "Start of the server ingest key"
},
{
"type": "null"
}
]
},
"verified_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"first_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_event_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"snippet": {
"type": "string",
"description": "HTML tracking snippet"
},
"favorite": {
"type": "boolean",
"description": "Starred by you"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/tracking/verify.json
Check the tracker is installed on the site (script tag, site id, CSP and referrer policy)
tracking_verify
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/tracking/verify.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Page to check (defaults to https://<domain>/)"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
GET
/sites/:site_id/tracking/snippet.json
Build the tracking snippet for chosen options
tracking_snippet
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/tracking/snippet.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"modules": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional modules: auto (outbound links, downloads, forms, 404s), engage (time and scroll), vitals (Web Vitals), clicks",
"default": [
"engage"
]
},
"manual": {
"type": "boolean",
"description": "Turn off the automatic pageview",
"default": false
},
"spa": {
"type": "string",
"description": "Single-page app navigation tracking",
"enum": [
"auto",
"history",
"hash",
"off"
],
"default": "auto"
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only track on these hostnames",
"default": []
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "Path globs not to track, e.g. /admin/*",
"default": []
},
"query_params": {
"type": "array",
"items": {
"type": "string"
},
"description": "Extra query parameters to keep, e.g. page",
"default": []
},
"mask": {
"type": "array",
"items": {
"type": "string"
},
"description": "Client-side path masks, e.g. /u/*->/u/:id",
"default": []
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
Traffic rules
POST
/sites/:site_id/traffic_rules.json
Add a traffic rule
traffic_rules_create
Permission: sites.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/traffic_rules.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"list": {
"type": "string",
"description": "hostnames, paths, referrers, countries, ip_ranges, user_agents or events",
"enum": [
"hostnames",
"paths",
"referrers",
"countries",
"ip_ranges",
"user_agents",
"events"
]
},
"pattern": {
"type": "string",
"description": "Value to match. * is a wildcard. ip_ranges take an IP or CIDR (v4/v6), countries an ISO code",
"examples": [
"/admin/*"
]
},
"label": {
"type": "string",
"description": "Optional note, e.g. \"Office\""
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"list",
"pattern",
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Rule id"
},
"list": {
"type": "string",
"description": "hostnames, paths, referrers, countries, ip_ranges, user_agents or events"
},
"pattern": {
"type": "string",
"description": "Pattern (* wildcards, CIDR for ip_ranges)"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block or allow (the mode of its list)"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/sites/:site_id/traffic_rules/:id.json
Delete a traffic rule
traffic_rules_delete
Permission: sites.manage
Example
curl -X DELETE https://privatusanalytics.com/sites/:site_id/traffic_rules/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Rule id"
},
"list": {
"type": "string",
"description": "hostnames, paths, referrers, countries, ip_ranges, user_agents or events"
},
"pattern": {
"type": "string",
"description": "Pattern (* wildcards, CIDR for ip_ranges)"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block or allow (the mode of its list)"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/traffic_rules.json
List traffic rules
traffic_rules_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/traffic_rules.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"list": {
"type": "string",
"description": "Only rules in this list",
"enum": [
"hostnames",
"paths",
"referrers",
"countries",
"ip_ranges",
"user_agents",
"events"
]
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Rule id"
},
"list": {
"type": "string",
"description": "hostnames, paths, referrers, countries, ip_ranges, user_agents or events"
},
"pattern": {
"type": "string",
"description": "Pattern (* wildcards, CIDR for ip_ranges)"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block or allow (the mode of its list)"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/sites/:site_id/traffic_rules/test.json
Test whether a hit would be counted with the site's current rules
traffic_rules_test
Permission: analytics.read
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/traffic_rules/test.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Page URL, e.g. https://example.com/a"
},
"referrer": {
"type": "string",
"description": "Referrer URL or hostname"
},
"country": {
"type": "string",
"description": "ISO country code, e.g. US"
},
"ip": {
"type": "string",
"description": "IP address to test against ip_ranges (not stored)"
},
"user_agent": {
"type": "string",
"description": "User-Agent string (reduced to browser and major version, like at ingest)"
},
"event": {
"type": "string",
"description": "Custom event name"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object"
}
PATCH
/sites/:site_id/traffic_rules/:id.json
Change a traffic rule
traffic_rules_update
Permission: sites.manage
Example
curl -X PATCH https://privatusanalytics.com/sites/:site_id/traffic_rules/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"pattern": {
"type": "string",
"description": "New pattern"
},
"label": {
"type": "string",
"description": "New label"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"site_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Rule id"
},
"list": {
"type": "string",
"description": "hostnames, paths, referrers, countries, ip_ranges, user_agents or events"
},
"pattern": {
"type": "string",
"description": "Pattern (* wildcards, CIDR for ip_ranges)"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"mode": {
"type": "string",
"description": "block or allow (the mode of its list)"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Uptime
POST
/sites/:site_id/uptime.json
Add an uptime check for a site
uptime_checks_create
Permission: uptime.manage
Example
curl -X POST https://privatusanalytics.com/sites/:site_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name (defaults to the target)"
},
"kind": {
"type": "string",
"description": "http (status code), keyword (body contains), tcp (host:port) or dns (name resolves)",
"enum": [
"http",
"keyword",
"tcp",
"dns"
],
"default": "http"
},
"url": {
"type": "string",
"description": "URL for http/keyword checks",
"examples": [
"https://example.com/health"
]
},
"host": {
"type": "string",
"description": "Hostname for tcp/dns checks"
},
"port": {
"type": "integer",
"description": "TCP port for tcp checks"
},
"keyword": {
"type": "string",
"description": "Text the response body must contain (keyword)"
},
"expected_status": {
"type": "integer",
"description": "Expected HTTP status code",
"default": 200
},
"http_method": {
"type": "string",
"description": "HTTP method",
"enum": [
"GET",
"HEAD"
],
"default": "GET"
},
"interval_seconds": {
"type": "integer",
"description": "Seconds between checks (plan minimum applies, default 300 or the minimum)"
},
"timeout_seconds": {
"type": "integer",
"description": "Seconds before a probe times out (1-30)",
"default": 20
},
"public": {
"type": "boolean",
"description": "May appear on public status pages",
"default": false
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Check id (upc_…)"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site the check belongs to"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http, keyword, tcp or dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up, down, pending or paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "May appear on status pages"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/uptime/checks/:id.json
Delete an uptime check and its history
uptime_checks_delete
Permission: uptime.manage
Example
curl -X DELETE https://privatusanalytics.com/uptime/checks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Check id (upc_…)"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site the check belongs to"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http, keyword, tcp or dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up, down, pending or paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "May appear on status pages"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/sites/:site_id/uptime.json
List a site's uptime checks
uptime_checks_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/sites/:site_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Only checks in this state",
"enum": [
"up",
"down",
"pending",
"paused"
]
},
"query": {
"type": "string",
"description": "Filter by name or target"
},
"site_id": {
"type": "string",
"description": "Site id, e.g. pa_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"site_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Check id (upc_…)"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site the check belongs to"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http, keyword, tcp or dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up, down, pending or paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "May appear on status pages"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/uptime/checks/:id/pause.json
Pause an uptime check
uptime_checks_pause
Permission: uptime.manage
Example
curl -X POST https://privatusanalytics.com/uptime/checks/:id/pause.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Check id (upc_…)"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site the check belongs to"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http, keyword, tcp or dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up, down, pending or paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "May appear on status pages"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/uptime/checks/:id/resume.json
Resume a paused uptime check
uptime_checks_resume
Permission: uptime.manage
Example
curl -X POST https://privatusanalytics.com/uptime/checks/:id/resume.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Check id (upc_…)"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site the check belongs to"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http, keyword, tcp or dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up, down, pending or paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "May appear on status pages"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/uptime/checks/:id.json
Get an uptime check: uptime 24h/7d/30d, response times and incidents
uptime_checks_get
Permission: analytics.read
Example
curl https://privatusanalytics.com/uptime/checks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"range": {
"type": "string",
"description": "Window for the response-time chart",
"enum": [
"24h",
"7d",
"30d"
],
"default": "24h"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"check": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Check id (upc_…)"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site the check belongs to"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http, keyword, tcp or dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up, down, pending or paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "May appear on status pages"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
},
"uptime": {
"type": "object",
"description": "Uptime % for 24h, 7d and 30d"
},
"range": {
"type": "string",
"description": "Window of response_times"
},
"response_times": {
"type": "object",
"description": "Average response ms per bucket: {unit, labels, series: {location: [ms…]}}"
},
"incidents": {
"type": "array",
"items": {
"type": "object",
"properties": {
"started_at": {
"type": "string",
"format": "date-time"
},
"resolved_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"duration_seconds": {
"type": "integer",
"description": "So far, if still open"
},
"cause": {
"anyOf": [
{
"type": "string",
"description": "Most common error, e.g. timeout or status_503"
},
{
"type": "null"
}
]
},
"failed_locations": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}
}
PATCH
/uptime/checks/:id.json
Change an uptime check
uptime_checks_update
Permission: uptime.manage
Example
curl -X PATCH https://privatusanalytics.com/uptime/checks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name (defaults to the target)"
},
"kind": {
"type": "string",
"description": "http (status code), keyword (body contains), tcp (host:port) or dns (name resolves)",
"enum": [
"http",
"keyword",
"tcp",
"dns"
]
},
"url": {
"type": "string",
"description": "URL for http/keyword checks",
"examples": [
"https://example.com/health"
]
},
"host": {
"type": "string",
"description": "Hostname for tcp/dns checks"
},
"port": {
"type": "integer",
"description": "TCP port for tcp checks"
},
"keyword": {
"type": "string",
"description": "Text the response body must contain (keyword)"
},
"expected_status": {
"type": "integer",
"description": "Expected HTTP status code"
},
"http_method": {
"type": "string",
"description": "HTTP method",
"enum": [
"GET",
"HEAD"
]
},
"interval_seconds": {
"type": "integer",
"description": "Seconds between checks (plan minimum applies, default 300 or the minimum)"
},
"timeout_seconds": {
"type": "integer",
"description": "Seconds before a probe times out (1-30)"
},
"public": {
"type": "boolean",
"description": "May appear on public status pages"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Check id (upc_…)"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site the check belongs to"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http, keyword, tcp or dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up, down, pending or paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "May appear on status pages"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/uptime/probes.json
Probe datacenter, User-Agent and egress IP ranges (for allowlisting our uptime probes)
uptime_probes_list
Permission: public
· HTTP only (not an MCP tool)
Example
curl https://privatusanalytics.com/uptime/probes.jsonInputs
{
"type": "object",
"properties": {},
"required": []
}
Response data
{
"type": "object"
}
POST
/uptime/probes/results.json
Submit results from an external probe agent (Bearer uptime probe token)
uptime_probes_results
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/uptime/probes/results.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"check_id": {
"type": "string"
},
"location": {
"type": "string"
},
"ok": {
"type": "boolean"
},
"status_code": {
"type": "integer"
},
"response_ms": {
"type": "integer"
},
"error": {
"type": "string"
},
"checked_at": {
"type": "string",
"format": "date-time"
}
}
},
"description": "Probe results: [{check_id, location, ok, status_code, response_ms, error, checked_at}]"
}
},
"required": [
"results"
]
}
Response data
{
"type": "object"
}
POST
/workspaces/:workspace_id/uptime.json
Add a workspace uptime check (not tied to a site)
workspace_uptime_checks_create
Permission: uptime.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name (defaults to the target)"
},
"kind": {
"type": "string",
"description": "http (status code), keyword (body contains), tcp (host:port) or dns (name resolves)",
"enum": [
"http",
"keyword",
"tcp",
"dns"
],
"default": "http"
},
"url": {
"type": "string",
"description": "URL for http/keyword checks",
"examples": [
"https://example.com/health"
]
},
"host": {
"type": "string",
"description": "Hostname for tcp/dns checks"
},
"port": {
"type": "integer",
"description": "TCP port for tcp checks"
},
"keyword": {
"type": "string",
"description": "Text the response body must contain (keyword)"
},
"expected_status": {
"type": "integer",
"description": "Expected HTTP status code",
"default": 200
},
"http_method": {
"type": "string",
"description": "HTTP method",
"enum": [
"GET",
"HEAD"
],
"default": "GET"
},
"interval_seconds": {
"type": "integer",
"description": "Seconds between checks (plan minimum applies, default 300 or the minimum)"
},
"timeout_seconds": {
"type": "integer",
"description": "Seconds before a probe times out (1-30)",
"default": 20
},
"public": {
"type": "boolean",
"description": "May appear on public status pages",
"default": false
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Check id (upc_…)"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site the check belongs to"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http, keyword, tcp or dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up, down, pending or paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "May appear on status pages"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/uptime.json
List all uptime checks in a workspace
workspace_uptime_checks_list
Permission: analytics.read
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/uptime.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Only checks in this state",
"enum": [
"up",
"down",
"pending",
"paused"
]
},
"query": {
"type": "string",
"description": "Filter by name or target"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Check id (upc_…)"
},
"workspace_id": {
"type": "string"
},
"site_id": {
"anyOf": [
{
"type": "string",
"description": "Site the check belongs to"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"kind": {
"type": "string",
"description": "http, keyword, tcp or dns"
},
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"host": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"port": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"keyword": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"expected_status": {
"type": "integer"
},
"http_method": {
"type": "string"
},
"interval_seconds": {
"type": "integer"
},
"timeout_seconds": {
"type": "integer"
},
"status": {
"type": "string",
"description": "up, down, pending or paused"
},
"enabled": {
"type": "boolean"
},
"public": {
"type": "boolean",
"description": "May appear on status pages"
},
"last_checked_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_check_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_response_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"ssl_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"ssl_issuer": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"domain_expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
Warehouse sync
POST
/workspaces/:workspace_id/warehouses.json
Add a warehouse destination
warehouse_destinations_create
Permission: workspace.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/warehouses.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name, e.g. Data lake"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites to send (pa_…). Empty sends all sites"
},
"bucket": {
"type": "string",
"description": "s3: bucket name"
},
"region": {
"type": "string",
"description": "s3: region, e.g. us-east-1 (auto for R2)"
},
"prefix": {
"type": "string",
"description": "s3/azure: path prefix, e.g. privatus/events"
},
"endpoint": {
"type": "string",
"description": "s3: https endpoint for S3-compatible storage (GCS interoperability, R2, MinIO)"
},
"access_key_id": {
"type": "string",
"description": "s3: access key id"
},
"secret_access_key": {
"type": "string",
"description": "s3: secret access key (write-only)"
},
"service_account_json": {
"type": "string",
"description": "bigquery: service account JSON key with BigQuery Data Editor (write-only)"
},
"project_id": {
"type": "string",
"description": "bigquery: project id (default: from the key)"
},
"dataset": {
"type": "string",
"description": "bigquery: dataset id"
},
"table": {
"type": "string",
"description": "bigquery/snowflake: table name (columns: schema v1)"
},
"account": {
"type": "string",
"description": "snowflake: account identifier, e.g. xy12345.us-east-1 or myorg-myaccount"
},
"user": {
"type": "string",
"description": "snowflake: user with key-pair authentication"
},
"private_key": {
"type": "string",
"description": "snowflake: PEM RSA private key (write-only)"
},
"database": {
"type": "string",
"description": "snowflake: database"
},
"schema": {
"type": "string",
"description": "snowflake: schema"
},
"warehouse": {
"type": "string",
"description": "snowflake: virtual warehouse"
},
"role": {
"type": "string",
"description": "snowflake: role (optional)"
},
"sas_url": {
"type": "string",
"description": "azure: container SAS URL with create/write permission (write-only)"
},
"kind": {
"type": "string",
"description": "s3 (also GCS/R2/MinIO), bigquery, snowflake or azure",
"enum": [
"s3",
"bigquery",
"snowflake",
"azure"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"kind",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Destination id, e.g. whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3, bigquery, snowflake or azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Where data goes: s3://bucket/prefix, project.dataset.table, account/database.schema.table or the Azure container"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "Setting names that are filled in (values are never returned)"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites sent (pa_…). Empty means all sites"
},
"schedule": {
"type": "string",
"description": "daily: 02:00 UTC, sends the previous UTC day"
},
"schema_version": {
"type": "string",
"description": "Row schema sent"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/warehouses/:id.json
Delete a warehouse destination
warehouse_destinations_delete
Permission: workspace.manage
Example
curl -X DELETE https://privatusanalytics.com/warehouses/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Destination id, e.g. whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3, bigquery, snowflake or azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Where data goes: s3://bucket/prefix, project.dataset.table, account/database.schema.table or the Azure container"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "Setting names that are filled in (values are never returned)"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites sent (pa_…). Empty means all sites"
},
"schedule": {
"type": "string",
"description": "daily: 02:00 UTC, sends the previous UTC day"
},
"schema_version": {
"type": "string",
"description": "Row schema sent"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/warehouses.json
List warehouse destinations
warehouse_destinations_list
Permission: workspace.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/warehouses.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "Only destinations of this kind",
"enum": [
"s3",
"bigquery",
"snowflake",
"azure"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Destination id, e.g. whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3, bigquery, snowflake or azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Where data goes: s3://bucket/prefix, project.dataset.table, account/database.schema.table or the Azure container"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "Setting names that are filled in (values are never returned)"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites sent (pa_…). Empty means all sites"
},
"schedule": {
"type": "string",
"description": "daily: 02:00 UTC, sends the previous UTC day"
},
"schema_version": {
"type": "string",
"description": "Row schema sent"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/warehouses/:id.json
Get a warehouse destination (no secrets)
warehouse_destinations_get
Permission: workspace.manage
Example
curl https://privatusanalytics.com/warehouses/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Destination id, e.g. whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3, bigquery, snowflake or azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Where data goes: s3://bucket/prefix, project.dataset.table, account/database.schema.table or the Azure container"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "Setting names that are filled in (values are never returned)"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites sent (pa_…). Empty means all sites"
},
"schedule": {
"type": "string",
"description": "daily: 02:00 UTC, sends the previous UTC day"
},
"schema_version": {
"type": "string",
"description": "Row schema sent"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/warehouses/:id/sync.json
Queue a sync of one day now
warehouse_destinations_sync
Permission: workspace.manage
Example
curl -X POST https://privatusanalytics.com/warehouses/:id/sync.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"date": {
"type": "string",
"format": "date",
"description": "UTC day to send, e.g. 2026-09-28 (default: yesterday)"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Destination id, e.g. whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3, bigquery, snowflake or azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Where data goes: s3://bucket/prefix, project.dataset.table, account/database.schema.table or the Azure container"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "Setting names that are filled in (values are never returned)"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites sent (pa_…). Empty means all sites"
},
"schedule": {
"type": "string",
"description": "daily: 02:00 UTC, sends the previous UTC day"
},
"schema_version": {
"type": "string",
"description": "Row schema sent"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/warehouses/:id.json
Update a warehouse destination (blank secrets are kept)
warehouse_destinations_update
Permission: workspace.manage
Example
curl -X PATCH https://privatusanalytics.com/warehouses/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name, e.g. Data lake"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites to send (pa_…). Empty sends all sites"
},
"bucket": {
"type": "string",
"description": "s3: bucket name"
},
"region": {
"type": "string",
"description": "s3: region, e.g. us-east-1 (auto for R2)"
},
"prefix": {
"type": "string",
"description": "s3/azure: path prefix, e.g. privatus/events"
},
"endpoint": {
"type": "string",
"description": "s3: https endpoint for S3-compatible storage (GCS interoperability, R2, MinIO)"
},
"access_key_id": {
"type": "string",
"description": "s3: access key id"
},
"secret_access_key": {
"type": "string",
"description": "s3: secret access key (write-only)"
},
"service_account_json": {
"type": "string",
"description": "bigquery: service account JSON key with BigQuery Data Editor (write-only)"
},
"project_id": {
"type": "string",
"description": "bigquery: project id (default: from the key)"
},
"dataset": {
"type": "string",
"description": "bigquery: dataset id"
},
"table": {
"type": "string",
"description": "bigquery/snowflake: table name (columns: schema v1)"
},
"account": {
"type": "string",
"description": "snowflake: account identifier, e.g. xy12345.us-east-1 or myorg-myaccount"
},
"user": {
"type": "string",
"description": "snowflake: user with key-pair authentication"
},
"private_key": {
"type": "string",
"description": "snowflake: PEM RSA private key (write-only)"
},
"database": {
"type": "string",
"description": "snowflake: database"
},
"schema": {
"type": "string",
"description": "snowflake: schema"
},
"warehouse": {
"type": "string",
"description": "snowflake: virtual warehouse"
},
"role": {
"type": "string",
"description": "snowflake: role (optional)"
},
"sas_url": {
"type": "string",
"description": "azure: container SAS URL with create/write permission (write-only)"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Destination id, e.g. whd_7Q2K9XH3AB"
},
"kind": {
"type": "string",
"description": "s3, bigquery, snowflake or azure"
},
"name": {
"type": "string"
},
"target": {
"type": "string",
"description": "Where data goes: s3://bucket/prefix, project.dataset.table, account/database.schema.table or the Azure container"
},
"configured": {
"type": "array",
"items": {
"type": "string"
},
"description": "Setting names that are filled in (values are never returned)"
},
"site_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Sites sent (pa_…). Empty means all sites"
},
"schedule": {
"type": "string",
"description": "daily: 02:00 UTC, sends the previous UTC day"
},
"schema_version": {
"type": "string",
"description": "Row schema sent"
},
"last_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"next_run_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Webhooks
GET
/workspaces/:workspace_id/webhooks/:webhook_id/deliveries.json
List deliveries for a webhook
webhook_deliveries_list
Permission: workspace.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:webhook_id/deliveries.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Only successful or failed deliveries",
"enum": [
"succeeded",
"failed"
]
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"webhook_id": {
"type": "string",
"description": "Webhook of the resource"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id",
"webhook_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Delivery id, e.g. whd_123"
},
"event": {
"type": "string"
},
"status": {
"type": "string",
"description": "pending, succeeded or failed"
},
"status_code": {
"anyOf": [
{
"type": "integer",
"description": "HTTP status of the last attempt"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Connection error of the last attempt"
},
{
"type": "null"
}
]
},
"attempt": {
"type": "integer"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"payload": {
"type": "object"
},
"response_body": {
"anyOf": [
{
"type": "string",
"description": "First 2,000 characters"
},
{
"type": "null"
}
]
},
"delivered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
POST
/workspaces/:workspace_id/webhooks/:webhook_id/deliveries/:id/redeliver.json
Send a delivery again
webhook_deliveries_redeliver
Permission: workspace.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:webhook_id/deliveries/:id/redeliver.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"webhook_id": {
"type": "string",
"description": "Webhook of the resource"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"webhook_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Delivery id, e.g. whd_123"
},
"event": {
"type": "string"
},
"status": {
"type": "string",
"description": "pending, succeeded or failed"
},
"status_code": {
"anyOf": [
{
"type": "integer",
"description": "HTTP status of the last attempt"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Connection error of the last attempt"
},
{
"type": "null"
}
]
},
"attempt": {
"type": "integer"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"payload": {
"type": "object"
},
"response_body": {
"anyOf": [
{
"type": "string",
"description": "First 2,000 characters"
},
{
"type": "null"
}
]
},
"delivered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/webhooks.json
Add a webhook endpoint
webhooks_create
Permission: workspace.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/webhooks.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "HTTPS endpoint that receives POSTed JSON",
"examples": [
"https://example.com/hooks/privatus"
]
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"alert.triggered",
"alert.resolved",
"goal.completed_threshold",
"uptime.down",
"uptime.up",
"export.ready",
"import.completed",
"import.failed",
"site.created",
"site.deleted",
"member.added",
"usage.threshold"
]
},
"description": "Events to send"
},
"enabled": {
"type": "boolean",
"description": "Send deliveries",
"default": true
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"url",
"events",
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook id, e.g. wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active, failing or disabled"
},
"secret": {
"type": "string",
"description": "Signing secret for Privatus-Signature"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:workspace_id/webhooks/:id.json
Delete a webhook
webhooks_delete
Permission: workspace.manage
Example
curl -X DELETE https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook id, e.g. wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active, failing or disabled"
},
"secret": {
"type": "string",
"description": "Signing secret for Privatus-Signature"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces/:workspace_id/webhooks.json
List webhooks
webhooks_list
Permission: workspace.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook id, e.g. wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active, failing or disabled"
},
"secret": {
"type": "string",
"description": "Signing secret for Privatus-Signature"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/workspaces/:workspace_id/webhooks/:id.json
Get a webhook
webhooks_get
Permission: workspace.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook id, e.g. wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active, failing or disabled"
},
"secret": {
"type": "string",
"description": "Signing secret for Privatus-Signature"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
POST
/workspaces/:workspace_id/webhooks/:id/test.json
Send a test delivery
webhooks_test
Permission: workspace.manage
Example
curl -X POST https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id/test.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Delivery id, e.g. whd_123"
},
"event": {
"type": "string"
},
"status": {
"type": "string",
"description": "pending, succeeded or failed"
},
"status_code": {
"anyOf": [
{
"type": "integer",
"description": "HTTP status of the last attempt"
},
{
"type": "null"
}
]
},
"error": {
"anyOf": [
{
"type": "string",
"description": "Connection error of the last attempt"
},
{
"type": "null"
}
]
},
"attempt": {
"type": "integer"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"payload": {
"type": "object"
},
"response_body": {
"anyOf": [
{
"type": "string",
"description": "First 2,000 characters"
},
{
"type": "null"
}
]
},
"delivered_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/workspaces/:workspace_id/webhooks/:id.json
Update a webhook (events, URL, enabled, rotate secret)
webhooks_update
Permission: workspace.manage
Example
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/webhooks/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "HTTPS endpoint"
},
"events": {
"type": "array",
"items": {
"type": "string",
"enum": [
"alert.triggered",
"alert.resolved",
"goal.completed_threshold",
"uptime.down",
"uptime.up",
"export.ready",
"import.completed",
"import.failed",
"site.created",
"site.deleted",
"member.added",
"usage.threshold"
]
},
"description": "Events to send"
},
"enabled": {
"type": "boolean",
"description": "Send deliveries"
},
"rotate_secret": {
"type": "boolean",
"description": "Replace the signing secret",
"default": false
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"workspace_id",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Webhook id, e.g. wh_7Q2K9XH3AB"
},
"url": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"enabled": {
"type": "boolean"
},
"status": {
"type": "string",
"description": "active, failing or disabled"
},
"secret": {
"type": "string",
"description": "Signing secret for Privatus-Signature"
},
"consecutive_failures": {
"type": "integer"
},
"last_success_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"last_failure_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
Website
GET
/changelog.json
List changelog entries
changelog_list
Published product updates, newest first. Also available as RSS at /changelog.rss.
Permission: public
Example
curl https://privatusanalytics.com/changelog.jsonInputs
{
"type": "object",
"properties": {
"area": {
"type": "string",
"description": "Only entries for this product area",
"enum": [
"product",
"dashboard",
"tracker",
"privacy",
"api",
"integrations",
"billing",
"docs"
]
},
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": []
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Entry id, e.g. chg_7Q2K9XH3AB"
},
"title": {
"type": "string",
"description": "Headline"
},
"area": {
"type": "string",
"description": "Product area, e.g. dashboard, tracker, api"
},
"body": {
"type": "string",
"description": "Markdown body"
},
"published_at": {
"type": "string",
"format": "date-time",
"description": "Publication time"
},
"url": {
"type": "string",
"description": "Permanent link"
}
}
}
}
GET
/changelog/:id.json
Get a changelog entry
changelog_get
Permission: public
Example
curl https://privatusanalytics.com/changelog/:id.jsonInputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Entry id, e.g. chg_7Q2K9XH3AB"
},
"title": {
"type": "string",
"description": "Headline"
},
"area": {
"type": "string",
"description": "Product area, e.g. dashboard, tracker, api"
},
"body": {
"type": "string",
"description": "Markdown body"
},
"published_at": {
"type": "string",
"format": "date-time",
"description": "Publication time"
},
"url": {
"type": "string",
"description": "Permanent link"
}
}
}
POST
/contact.json
Send a message to the Privatus team
contact_create
Browser clients send a Cloudflare Turnstile token as `cf-turnstile-response`. Requests with an API token need none.
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/contact.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Your name",
"examples": [
"Ada Lovelace"
]
},
"email": {
"type": "string",
"description": "Where we should reply",
"examples": [
"[email protected]"
]
},
"company": {
"type": "string",
"description": "Company or organization (optional)"
},
"topic": {
"type": "string",
"description": "What the message is about",
"enum": [
"general",
"sales",
"support",
"privacy",
"security",
"partnerships",
"press"
],
"default": "general"
},
"message": {
"type": "string",
"description": "Your message (10 to 5,000 characters)"
},
"website": {
"type": "string",
"description": "Leave empty. Spam trap for bots. Filled-in submissions are discarded"
}
},
"required": [
"name",
"email",
"message"
]
}
Response data
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "Always true when the submission was accepted"
},
"message": {
"type": "string",
"description": "What happens next"
}
}
}
POST
/newsletter/confirm.json
Confirm a newsletter subscription (signed token)
newsletter_confirm
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/newsletter/confirm.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Signed token from the confirmation email"
}
},
"required": [
"token"
]
}
Response data
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "Always true when the submission was accepted"
},
"message": {
"type": "string",
"description": "What happens next"
}
}
}
POST
/newsletter.json
Subscribe an email to the newsletter
newsletter_subscribe
Browser clients send a Cloudflare Turnstile token as `cf-turnstile-response`. Requests with an API token need none.
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/newsletter.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email address to subscribe. A confirmation link is emailed to it",
"examples": [
"[email protected]"
]
},
"website": {
"type": "string",
"description": "Leave empty. Spam trap for bots. Filled-in submissions are discarded"
}
},
"required": [
"email"
]
}
Response data
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "Always true when the submission was accepted"
},
"message": {
"type": "string",
"description": "What happens next"
}
}
}
POST
/newsletter/unsubscribe.json
Unsubscribe with a signed link token
newsletter_unsubscribe
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/newsletter/unsubscribe.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "Signed token from the unsubscribe link"
},
"list": {
"type": "string",
"description": "newsletter (default: the list the link was for) or marketing (all marketing email)",
"enum": [
"newsletter",
"marketing"
]
}
},
"required": [
"token"
]
}
Response data
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "Always true when the submission was accepted"
},
"message": {
"type": "string",
"description": "What happens next"
}
}
}
GET
/pricing.json
Get plans, prices and plan limits
pricing_get
The same data as the pricing page: the events ladder, every plan limit and what counts as an event. Pass events to get the matching tier.
Permission: public
Example
curl https://privatusanalytics.com/pricing.jsonInputs
{
"type": "object",
"properties": {
"events": {
"type": "integer",
"description": "Expected pageviews plus custom events a month. Returns the matching tier as `recommendation`",
"examples": [
750000
]
},
"interval": {
"type": "string",
"description": "Billing interval for the prices shown: month, or year (10x the monthly price)",
"enum": [
"month",
"year"
],
"default": "month"
}
},
"required": []
}
Response data
{
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "Currency of every price (USD)"
},
"tax_included": {
"type": "boolean",
"description": "Always true. Prices include VAT or sales tax, so the price shown is the price paid"
},
"interval": {
"type": "string",
"description": "month or year. Prices are for this interval"
},
"annual_multiplier": {
"type": "integer",
"description": "Yearly price = monthly price x this (two months free)"
},
"free_events": {
"type": "integer",
"description": "Events a month included in the Free plan"
},
"badge_bonus": {
"type": "integer",
"description": "Extra free events a month when the optional badge is shown"
},
"tiers": {
"type": "array",
"items": {
"type": "object"
},
"description": "Events ladder: { events, pro, business } prices for the interval (pro is null where only Business is offered), plus the monthly prices"
},
"plans": {
"type": "array",
"items": {
"type": "object"
},
"description": "Plans with { id, name, from_price, limits }. Limits of null mean unlimited"
},
"counted": {
"type": "array",
"items": {
"type": "string"
},
"description": "What counts as a billable event"
},
"not_counted": {
"type": "array",
"items": {
"type": "string"
},
"description": "What never counts toward usage"
},
"recommendation": {
"anyOf": [
{
"type": "object",
"description": "{ events, plan, tier_events, price } for the `events` input, or null when no volume was given"
},
{
"type": "null"
}
]
}
}
}
GET
/status.json
Get the current system status
status_get
Database, Redis and background-job health, checked at most every 15 seconds.
Permission: public
Example
curl https://privatusanalytics.com/status.jsonInputs
{
"type": "object",
"properties": {
"fresh": {
"type": "boolean",
"description": "Skip the 15-second cache and check again now",
"default": false
}
},
"required": []
}
Response data
{
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Overall: operational, degraded or outage"
},
"checked_at": {
"type": "string",
"format": "date-time",
"description": "When the checks ran (cached up to 15 s)"
},
"components": {
"type": "array",
"items": {
"type": "object"
},
"description": "Per component: { id, name, status, detail, latency_ms }, plus queue_latency_s and queue_depth for queues"
}
}
}
GET
/tools/consent-gap.json
Estimate traffic missed by consent-based analytics
tools_consent_gap
Permission: public
Example
curl https://privatusanalytics.com/tools/consent-gap.jsonInputs
{
"type": "object",
"properties": {
"monthly_visitors": {
"type": "integer",
"description": "Visitors a month (from your server logs or current analytics)",
"examples": [
50000
]
},
"consent_rate": {
"type": "number",
"description": "Percent of visitors who accept analytics cookies in your banner (0-100)",
"examples": [
55
]
},
"adblock_share": {
"type": "number",
"description": "Percent of visitors whose blockers stop analytics scripts (0-100)",
"default": 25.0
}
},
"required": [
"monthly_visitors",
"consent_rate"
]
}
Response data
{
"type": "object",
"properties": {
"monthly_visitors": {
"type": "integer",
"description": "Input: visitors a month"
},
"consent_rate": {
"type": "number",
"description": "Input: percent who accept analytics cookies"
},
"adblock_share": {
"type": "number",
"description": "Input: percent whose blockers stop scripts"
},
"measured_with_consent": {
"type": "integer",
"description": "Visitors a consent-based tool can measure"
},
"missed": {
"type": "integer",
"description": "Visitors it misses"
},
"missed_percent": {
"type": "number",
"description": "Share of visitors missed, in percent"
},
"measured_cookieless": {
"type": "integer",
"description": "Visitors a cookieless tool without a banner can measure, if it is blocked at the same rate"
},
"recovered_by_cookieless": {
"type": "integer",
"description": "Difference between the cookieless and consent-based estimates"
}
}
}
GET
/tools/header-checker.json
Check a page’s Referrer-Policy and CSP for analytics
tools_header_check
Permission: public
Example
curl https://privatusanalytics.com/tools/header-checker.jsonInputs
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Public page to check (http or https)",
"examples": [
"https://example.com"
]
}
},
"required": [
"url"
]
}
Response data
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Final URL after redirects"
},
"status": {
"type": "integer",
"description": "HTTP status of the final response"
},
"findings": {
"type": "array",
"items": {
"type": "object"
},
"description": "Checks: { check, value, level (ok, warn, info), note }"
}
}
}
GET
/tools/privacy-policy-generator.json
Draft a privacy-policy paragraph for Privatus Analytics
tools_privacy_policy
Permission: public
Example
curl https://privatusanalytics.com/tools/privacy-policy-generator.jsonInputs
{
"type": "object",
"properties": {
"site_name": {
"type": "string",
"description": "Your website or company name",
"examples": [
"Example Books"
]
},
"contact_email": {
"type": "string",
"description": "Privacy contact to mention (optional)"
},
"honors_gpc": {
"type": "boolean",
"description": "Whether Do Not Track and Global Privacy Control are honored (the default)",
"default": true
}
},
"required": [
"site_name"
]
}
Response data
{
"type": "object",
"properties": {
"site_name": {
"type": "string",
"description": "Input: site or company name"
},
"paragraphs": {
"type": "array",
"items": {
"type": "string"
},
"description": "The policy text, one paragraph per item"
},
"text": {
"type": "string",
"description": "The paragraphs joined with blank lines"
}
}
}
GET
/tools/qr-code.json
Generate a QR code as SVG
tools_qr_code
Permission: public
Example
curl https://privatusanalytics.com/tools/qr-code.jsonInputs
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "URL or text to encode (up to 1,000 characters)",
"examples": [
"https://example.com/?utm_source=poster"
]
},
"level": {
"type": "string",
"description": "Error correction: l (7%), m (15%), q (25%), h (30%)",
"enum": [
"l",
"m",
"q",
"h"
],
"default": "m"
}
},
"required": [
"text"
]
}
Response data
{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "The encoded text"
},
"level": {
"type": "string",
"description": "Error correction level"
},
"size": {
"type": "integer",
"description": "Modules per side"
},
"svg": {
"type": "string",
"description": "Standalone SVG document"
}
}
}
GET
/tools/tracker-scanner.json
List cookies and known trackers on a page
tools_tracker_scan
Permission: public
Example
curl https://privatusanalytics.com/tools/tracker-scanner.jsonInputs
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Public page to scan (http or https)",
"examples": [
"https://example.com"
]
}
},
"required": [
"url"
]
}
Response data
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Final URL after redirects"
},
"status": {
"type": "integer",
"description": "HTTP status of the final response"
},
"truncated": {
"type": "boolean",
"description": "True when the page was over 1 MB and only the first 1 MB was scanned"
},
"cookies": {
"type": "array",
"items": {
"type": "object"
},
"description": "Cookies set by the HTTP response: { name, domain, path, expires, secure, http_only, same_site }. Values are never returned"
},
"trackers": {
"type": "array",
"items": {
"type": "object"
},
"description": "Known tools referenced by the page: { name, category, match, evidence }"
},
"third_party_hosts": {
"type": "array",
"items": {
"type": "string"
},
"description": "Other domains the page loads resources from"
}
}
}
GET
/tools/utm-builder.json
Build a campaign URL with UTM parameters
tools_utm_builder
Permission: public
Example
curl https://privatusanalytics.com/tools/utm-builder.jsonInputs
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Landing page URL",
"examples": [
"https://example.com/pricing"
]
},
"source": {
"type": "string",
"description": "utm_source: where the traffic comes from",
"examples": [
"newsletter"
]
},
"medium": {
"type": "string",
"description": "utm_medium: the channel, e.g. email, cpc, social",
"examples": [
"email"
]
},
"campaign": {
"type": "string",
"description": "utm_campaign: the campaign name",
"examples": [
"fall_launch"
]
},
"term": {
"type": "string",
"description": "utm_term: paid search keyword (optional)"
},
"content": {
"type": "string",
"description": "utm_content: which link or creative (optional)"
}
},
"required": [
"url",
"source",
"medium",
"campaign"
]
}
Response data
{
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The landing page URL with UTM parameters"
},
"params": {
"type": "object",
"description": "The UTM parameters that were added"
},
"warnings": {
"type": "array",
"items": {
"type": "string"
},
"description": "Problems worth fixing (case, spaces, personal data)"
}
}
}
POST
/waitlist.json
Join a waitlist (EU hosting)
waitlist_join
Browser clients send a Cloudflare Turnstile token as `cf-turnstile-response`. Requests with an API token need none.
Permission: public
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/waitlist.json \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email to notify",
"examples": [
"[email protected]"
]
},
"list": {
"type": "string",
"description": "Which waitlist to join",
"enum": [
"eu_hosting"
],
"default": "eu_hosting"
},
"website": {
"type": "string",
"description": "Leave empty. Spam trap for bots. Filled-in submissions are discarded"
}
},
"required": [
"email"
]
}
Response data
{
"type": "object",
"properties": {
"received": {
"type": "boolean",
"description": "Always true when the submission was accepted"
},
"message": {
"type": "string",
"description": "What happens next"
}
}
}
Workspaces
GET
/workspaces/:workspace_id/white_label.json
Get the white label brand
white_label_get
Permission: workspace.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/white_label.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"brand_name": {
"anyOf": [
{
"type": "string",
"description": "Name shown instead of Privatus Analytics"
},
{
"type": "null"
}
]
},
"brand_logo_url": {
"anyOf": [
{
"type": "string",
"description": "Logo image URL"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string",
"description": "Accent color"
},
{
"type": "null"
}
]
},
"hide_branding": {
"type": "boolean",
"description": "Privatus branding is hidden"
},
"available": {
"type": "boolean",
"description": "The plan includes white label"
},
"active": {
"type": "boolean",
"description": "The brand is currently applied"
}
}
}
PATCH
/workspaces/:workspace_id/white_label.json
Set the white label brand for shared dashboards and email reports (Business)
white_label_update
Permission: workspace.manage
Example
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/white_label.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"brand_name": {
"type": "string",
"description": "Name shown instead of Privatus Analytics (blank removes it)"
},
"brand_logo_url": {
"type": "string",
"description": "https URL of a logo image (blank removes it)"
},
"brand_color": {
"type": "string",
"description": "Accent color, e.g. #06755b"
},
"hide_branding": {
"type": "boolean",
"description": "Hide \"Privatus\" on shared dashboards and email reports"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"brand_name": {
"anyOf": [
{
"type": "string",
"description": "Name shown instead of Privatus Analytics"
},
{
"type": "null"
}
]
},
"brand_logo_url": {
"anyOf": [
{
"type": "string",
"description": "Logo image URL"
},
{
"type": "null"
}
]
},
"brand_color": {
"anyOf": [
{
"type": "string",
"description": "Accent color"
},
{
"type": "null"
}
]
},
"hide_branding": {
"type": "boolean",
"description": "Privatus branding is hidden"
},
"available": {
"type": "boolean",
"description": "The plan includes white label"
},
"active": {
"type": "boolean",
"description": "The brand is currently applied"
}
}
}
GET
/workspaces/:workspace_id/security.json
Get workspace security settings
workspace_security_get
Permission: workspace.manage
Example
curl https://privatusanalytics.com/workspaces/:workspace_id/security.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"enforce_2fa": {
"type": "boolean",
"description": "Members must set up 2FA"
},
"login_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed login methods"
},
"session_ttl_hours": {
"anyOf": [
{
"type": "integer",
"description": "Session lifetime (null = none)"
},
{
"type": "null"
}
]
},
"app_ip_allowlist": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed IPs/CIDRs (empty = anywhere)"
},
"support_access_until": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Privatus support may view the workspace until"
},
{
"type": "null"
}
]
}
}
}
PATCH
/workspaces/:workspace_id/security.json
Update workspace security settings (2FA, login methods, session lifetime, IP allowlist, support access)
workspace_security_update
Permission: workspace.manage
Example
curl -X PATCH https://privatusanalytics.com/workspaces/:workspace_id/security.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"enforce_2fa": {
"type": "boolean",
"description": "Require members to set up 2FA"
},
"login_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"password",
"magic_link",
"passkey",
"google",
"github",
"sso"
]
},
"description": "Allowed login methods"
},
"session_ttl_hours": {
"type": "integer",
"description": "Sign members out after this many hours (0 = no limit)"
},
"app_ip_allowlist": {
"type": "array",
"items": {
"type": "string"
},
"description": "Only allow app and API access from these IPs/CIDRs (Business). Empty = anywhere"
},
"support_access": {
"type": "boolean",
"description": "Let Privatus support view the workspace for 7 days"
},
"workspace_id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
}
},
"required": [
"workspace_id"
]
}
Response data
{
"type": "object",
"properties": {
"workspace_id": {
"type": "string"
},
"enforce_2fa": {
"type": "boolean",
"description": "Members must set up 2FA"
},
"login_methods": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed login methods"
},
"session_ttl_hours": {
"anyOf": [
{
"type": "integer",
"description": "Session lifetime (null = none)"
},
{
"type": "null"
}
]
},
"app_ip_allowlist": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allowed IPs/CIDRs (empty = anywhere)"
},
"support_access_until": {
"anyOf": [
{
"type": "string",
"format": "date-time",
"description": "Privatus support may view the workspace until"
},
{
"type": "null"
}
]
}
}
}
POST
/workspaces.json
Create a workspace (you become the owner)
workspaces_create
Permission: member
· HTTP only (not an MCP tool)
Example
curl -X POST https://privatusanalytics.com/workspaces.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Workspace name",
"examples": [
"Acme Inc"
]
},
"timezone": {
"type": "string",
"description": "Default reporting timezone (defaults to the user's)"
},
"currency": {
"type": "string",
"description": "Default currency (ISO 4217)",
"default": "USD"
},
"how_heard": {
"type": "string",
"description": "How you heard about us"
}
},
"required": [
"name"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "Default reporting timezone"
},
"currency": {
"type": "string",
"description": "Default currency"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events per month included in the plan"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "Your role in this workspace"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
DELETE
/workspaces/:id.json
Delete a workspace and all its sites (owner only, cancels any subscription)
workspaces_delete
Permission: workspace.manage
Example
curl -X DELETE https://privatusanalytics.com/workspaces/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"confirm": {
"type": "string",
"description": "Type the workspace name to confirm"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"confirm",
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "Default reporting timezone"
},
"currency": {
"type": "string",
"description": "Default currency"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events per month included in the plan"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "Your role in this workspace"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
GET
/workspaces.json
List your workspaces
workspaces_list
Permission: member
Example
curl https://privatusanalytics.com/workspaces.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"page": {
"type": "integer",
"description": "Page (from 1)"
},
"per_page": {
"type": "integer",
"description": "Results per page (max 100)"
}
},
"required": []
}
Response data
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "Default reporting timezone"
},
"currency": {
"type": "string",
"description": "Default currency"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events per month included in the plan"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "Your role in this workspace"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
}
GET
/workspaces/:id.json
Get a workspace
workspaces_get
Permission: member
Example
curl https://privatusanalytics.com/workspaces/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN"Inputs
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "Default reporting timezone"
},
"currency": {
"type": "string",
"description": "Default currency"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events per month included in the plan"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "Your role in this workspace"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}
PATCH
/workspaces/:id.json
Update workspace settings
workspaces_update
Permission: workspace.manage
Example
curl -X PATCH https://privatusanalytics.com/workspaces/:id.json \
-H "Authorization: Bearer $PRIVATUS_TOKEN" \
-H "Content-Type: application/json" -d '{…}'Inputs
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Workspace name"
},
"timezone": {
"type": "string",
"description": "Default reporting timezone"
},
"currency": {
"type": "string",
"description": "Default currency (ISO 4217)"
},
"id": {
"type": "string",
"description": "Id of the resource"
}
},
"required": [
"id"
]
}
Response data
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Workspace id, e.g. ws_7Q2K9XH3AB"
},
"name": {
"type": "string"
},
"timezone": {
"type": "string",
"description": "Default reporting timezone"
},
"currency": {
"type": "string",
"description": "Default currency"
},
"plan": {
"type": "string",
"description": "free, pro, business or enterprise"
},
"plan_events": {
"type": "integer",
"description": "Events per month included in the plan"
},
"subscription_status": {
"type": "string"
},
"role": {
"type": "string",
"description": "Your role in this workspace"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}