Web analytics

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
GET
POST
GET
POST
GET
GET
POST
GET
GET
POST
GET
GET
POST
GET
GET
POST

Retrieve aeo prompts

Gets citation and brand-mention totals per answer engine for one prompt, plus, for the last 30 days in the project's timezone, per-day counts, which engines cite which domains, brand sentiment per engine, and the words of the web searches the engines ran.

Required API key scopes

web_analytics:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/aeo_prompts/:id/stats
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/:id/stats/

Example response

Status 200
RESPONSE
{
"engines": [
{
"citation_rate": 0,
"mention_rate": 0,
"engine": "string",
"checks": 0,
"cited": 0,
"mentioned": 0,
"failed": 0,
"avg_position": 0,
"first_checked_at": "2019-08-24T14:15:22Z",
"last_checked_at": "2019-08-24T14:15:22Z"
}
],
"daily": [
{
"date": "2019-08-24",
"engine": "string",
"checks": 0,
"cited": 0,
"mentioned": 0,
"failed": 0,
"avg_position": 0
}
],
"consensus": [
{
"engine": "string",
"domain": "string",
"checks_citing": 0,
"checks": 0
}
],
"sentiment": [
{
"engine": "string",
"positive": 0,
"neutral": 0,
"negative": 0,
"unscored": 0
}
],
"top_words": [
{
"word": "string",
"count": 0
}
],
"total_checks": 0,
"brand_names": [
"string"
],
"daily_from": "2019-08-24",
"daily_to": "2019-08-24"
}

Retrieve aeo prompts

Lists every version of a prompt's text, newest first. A text edit adds a version, and one of them is current.

Required API key scopes

web_analytics:read

Path parameters

  • id
    string

Example request

GET /api/projects/:project_id/aeo_prompts/:id/versions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/:id/versions/

Example response

Status 200
RESPONSE
{
"created_by": {
"email": "string",
"name": "string"
},
"version": 0,
"text": "string",
"version_description": "string",
"created_at": "2019-08-24T14:15:22Z",
"is_current": true
}

Create aeo prompts bulk

Adds prompts to the project's AEO prompt set, or updates the topic and visibility of prompts that already exist. Existing prompts keep their active state. Prompts whose text matches an archived prompt are skipped.

Required API key scopes

web_analytics:write

Request parameters

  • prompts
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/aeo_prompts/bulk_import
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl
-H 'Content-Type: application/json'\
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/bulk_import/\
-d prompts="array"

Example response

Status 200
RESPONSE
{
"created": 0,
"updated": 0,
"skipped": 0
}

Retrieve aeo prompts

Lists the answered web-search checks across the whole prompt set that cited one URL, cited a page on one domain, or ran one web search, over the last 'days' days (default 30) in the project's timezone, newest first, one page at a time. Pass exactly one of url, domain or search. Each row has the prompt as it ran, whether the answer cited or mentioned the project, the URLs it cited and the searches it ran. Use it to see which prompts and answers sit behind a domain, page or search from the overview or the rankings, with the same 'days' and 'branded' values.

Required API key scopes

web_analytics:read

Query parameters

  • branded
    string
    Default: all
    One of: "all""branded""non_branded"
  • days
    integer
    Default: 30
  • domain
    string
  • engine
    string
  • include_answer_text
    boolean
    Default: false
  • limit
    integer
  • offset
    integer
  • search
    string
  • url
    string

Response


Example request

GET /api/projects/:project_id/aeo_prompts/citations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/citations/

Example response

Status 200
RESPONSE
{
"count": 123,
"next": "http://api.example.org/accounts/?offset=400&limit=100",
"previous": "http://api.example.org/accounts/?offset=200&limit=100",
"results": [
{
"brand_sentiment_sentences": [
{
"start": 0,
"end": 0,
"label": "string",
"score": 0.1
}
],
"id": "string",
"run_id": "string",
"engine": "string",
"mode": "web_search",
"model": "string",
"created_at": "2019-08-24T14:15:22Z",
"cited": true,
"check_failed": true,
"error": "string",
"cited_urls": [
"string"
],
"target_urls": [
"string"
],
"target_best_position": 0,
"top_cited_domains": [
"string"
],
"search_queries": [
"string"
],
"answer_text": "string",
"prompt_version": 0,
"brand_sentiment": "string",
"brand_sentiment_score": 0,
"prompt_id": "string",
"prompt_text": "string",
"prompt_topic": "string",
"mentioned": true
}
]
}
Status 400 None, or more than one, of url, domain and search was given.

Create aeo prompts create

Creates a dashboard named 'AI visibility weekly' with SQL insights over the citation checks of non-branded prompts: visibility and citation rate for the last 7 complete days against the 7 before, visibility per topic, the pages to watch per topic, and an 8-week trend. The queries read the brand catalog when they run, so they follow catalog edits. Each call creates a new dashboard. Subscribe to it with the subscriptions API to get it weekly in Slack or email.

Required API key scopes

web_analytics:readdashboard:writeinsight:write

Response


Example request

POST /api/projects/:project_id/aeo_prompts/create_dashboard
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl
-H 'Content-Type: application/json'\
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/create_dashboard/

Example response

Status 201
RESPONSE
{
"id": 0,
"name": "string"
}

Retrieve aeo prompts

Gets an overview of the project's whole AEO prompt set for the last 'days' days (default 30) in the project's timezone: how many prompts are tracked, how many checks ran, the citation rate and the brand-mention rate, the same counts for the window before it, the current window split per answer engine (Claude, ChatGPT/OpenAI, Exa) and per topic, and the domains the engines cited most. Those counts cover web-search checks; a prompt's own stats split every engine, no-search ones included. Pass 'branded' to count only the checks whose prompt names the brand, or only the ones whose prompt does not, 'engine' to count one answer engine, and 'topic' to count one topic.

Required API key scopes

web_analytics:read

Query parameters

  • branded
    string
    Default: all
    One of: "all""branded""non_branded"
  • days
    integer
    Default: 30
  • engine
    string | null
  • topic
    string | null

Response


Example request

GET /api/projects/:project_id/aeo_prompts/overview
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/overview/

Example response

Status 200
RESPONSE
{
"current": {
"citation_rate": 0,
"mention_rate": 0,
"checks": 0,
"failed": 0,
"cited": 0,
"mentioned": 0,
"prompts": 0,
"prompts_cited": 0,
"avg_position": 0
},
"previous": {
"citation_rate": 0,
"mention_rate": 0,
"checks": 0,
"failed": 0,
"cited": 0,
"mentioned": 0,
"prompts": 0,
"prompts_cited": 0,
"avg_position": 0
},
"engines": [
{
"citation_rate": 0,
"mention_rate": 0,
"checks": 0,
"failed": 0,
"cited": 0,
"mentioned": 0,
"prompts": 0,
"prompts_cited": 0,
"avg_position": 0,
"engine": "string"
}
],
"daily": [
{
"date": "2019-08-24",
"engine": "string",
"checks": 0,
"cited": 0,
"mentioned": 0,
"failed": 0,
"avg_position": 0
}
],
"topics": [
{
"citation_rate": 0,
"mention_rate": 0,
"checks": 0,
"failed": 0,
"cited": 0,
"mentioned": 0,
"prompts": 0,
"prompts_cited": 0,
"avg_position": 0,
"topic": "string",
"active_prompts": 0
}
],
"top_domains": [
{
"domain": "string",
"answers": 0,
"share_of_answers": 0.1,
"is_target": true
}
],
"top_searches": [
{
"top_prompts": [
{
"id": "string",
"text": "string"
}
],
"query": "string",
"prompts": 0,
"answers": 0,
"cited": 0,
"engines": [
"string"
]
}
],
"days": 0,
"window_from": "2019-08-24",
"window_to": "2019-08-24",
"prompts_tracked": 0,
"target_domains": [
"string"
],
"brand_names": [
"string"
],
"branded": "all",
"engine": "string",
"topic": "string",
"branded_answers": 0,
"non_branded_answers": 0
}

Retrieve aeo prompts

Gets how often AI answers named the project against its competitors over the last 'days' days (default 30) in the project's timezone, with the same share for the window before, a daily series, and the domains and pages the engines cited most. Competitors are derived from the cited domains. Pass 'branded' to count only the checks whose prompt names the brand, or only the ones whose prompt does not, 'engine' to count one answer engine, and 'topic' to count one topic.

Required API key scopes

web_analytics:read

Query parameters

  • branded
    string
    Default: all
    One of: "all""branded""non_branded"
  • days
    integer
    Default: 30
  • engine
    string | null
  • topic
    string | null

Response


Example request

GET /api/projects/:project_id/aeo_prompts/rankings
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/rankings/

Example response

Status 200
RESPONSE
{
"brands": [
{
"domain": "string",
"name": "string",
"is_target": true,
"answers_mentioning": 0,
"visibility": 0,
"previous_visibility": 0,
"positive_share": 0
}
],
"daily": [
{
"date": "2019-08-24",
"domain": "string",
"answers": 0,
"visibility": 0
}
],
"top_domains": [
{
"domain": "string",
"answers": 0,
"share_of_answers": 0.1,
"urls": 0,
"is_target": true,
"is_competitor": true
}
],
"top_pages": [
{
"url": "string",
"answers": 0,
"share_of_answers": 0.1,
"is_target": true
}
],
"days": 0,
"window_from": "2019-08-24",
"window_to": "2019-08-24",
"branded": "all",
"engine": "string",
"topic": "string",
"answers": 0,
"competitors_confirmed": true
}

Create aeo prompts

Suggests prompts to track for a site. Requires AI data processing approved for the organization. PostHog reads the site with web search and writes questions a buyer would ask an AI assistant, each labeled with a topic, a circle, a funnel stage and whether it names the brand. Nothing is saved: import the prompts you keep with bulk_import. Prompts the project already tracks are left out. Returns a pending job right away; poll GET aeo_prompts/suggest/<id>/ until it completes, which takes up to a few minutes.

Required API key scopes

web_analytics:write

Request parameters

  • domain
    string
  • brand
    string
  • description
    string
  • competitors
    array
  • topics
    array
  • count
    integer
    Default: 20

Response


Example request

POST /api/projects/:project_id/aeo_prompts/suggest
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl
-H 'Content-Type: application/json'\
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/suggest/\
-d domain="string"

Example response

Status 202
RESPONSE
{
"suggestions": [
{
"prompt": "string",
"topic": "string",
"circle": "differentiation",
"funnel_stage": "top",
"branded": true,
"reason": "string"
}
],
"id": "string",
"status": "pending",
"error": "string"
}

Retrieve aeo prompts suggestion

Gets a prompt suggestion job started with POST aeo_prompts/suggest/. status is pending while PostHog works, then completed with the suggestions or failed with an error. Jobs expire an hour after their last update.

Required API key scopes

web_analytics:read

Path parameters

  • job_id
    string

Response


Example request

GET /api/projects/:project_id/aeo_prompts/suggest/:job_id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/suggest/:job_id/

Example response

Status 200
RESPONSE
{
"suggestions": [
{
"prompt": "string",
"topic": "string",
"circle": "differentiation",
"funnel_stage": "top",
"branded": true,
"reason": "string"
}
],
"id": "string",
"status": "pending",
"error": "string"
}

Retrieve aeo prompts

Lists the topics in the project's AEO prompt set, with the number of prompts in each.

Required API key scopes

web_analytics:read

Example request

GET /api/projects/:project_id/aeo_prompts/topics
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/topics/

Example response

Status 200
RESPONSE
{
"topic": "string",
"prompts": 0
}

Create aeo setup

Sets up AI visibility tracking for the project in one job. Requires AI data processing approved for the organization. In order, it adds the site as the project's own brand, has PostHog suggest 20 prompts and saves them, and has PostHog suggest 20 keywords and saves them. With run_first_check the prompts are saved active and a first citation check run is queued with the enabled engines; each check is a paid call to every enabled engine, and each engine keeps checking active prompts on its schedule. Without it, new prompts are saved paused, so nothing is checked or spent until they are turned on. A step the project already covers is skipped: an own brand exists, 10 or more unarchived prompts, 10 or more keywords, or any check already recorded. With engines, the chosen engines are turned on and every other one off before the job starts. Returns a pending job right away; poll GET aeo_setup/<id>/ until it completes, which takes a few minutes. Running it again only fills the gaps.

Required API key scopes

web_analytics:write

Request parameters

  • domain
    string
  • brand
    string
  • description
    string
  • engines
    array
  • run_first_check
    boolean
    Default: false
  • only_first_run
    boolean
    Default: false
  • activate_paused_prompts
    boolean
    Default: false

Response


Example request

POST /api/projects/:project_id/aeo_setup
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl
-H 'Content-Type: application/json'\
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_setup/\
-d domain="string"

Example response

Status 202
RESPONSE
{
"steps": [
{
"step": "brand",
"status": "pending",
"added": 0,
"detail": "string"
}
],
"id": "string",
"status": "pending",
"error": "string"
}
Status 400 The domain is not valid, or no chosen engine can run.
Status 409 A setup job is already running for the project.
RESPONSE
{
"detail": "string",
"job_id": "string"
}

Retrieve aeo setup

Gets a setup job started with POST aeo_setup/, with the state of each step. Jobs expire an hour after their last update.

Required API key scopes

web_analytics:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/aeo_setup/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_setup/:id/

Example response

Status 200
RESPONSE
{
"steps": [
{
"step": "brand",
"status": "pending",
"added": 0,
"detail": "string"
}
],
"id": "string",
"status": "pending",
"error": "string"
}

Retrieve aeo setup

Gets what PostHog already knows about the project for AI visibility setup: the domains it may be about, from its own brands, authorized URLs, recording domains and pageview hosts, and how many prompts, keywords and checks it has. Use the first website as the default domain for POST aeo_setup/.

Required API key scopes

web_analytics:read

Response


Example request

GET /api/projects/:project_id/aeo_setup/context
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_setup/context/

Example response

Status 200
RESPONSE
{
"websites": [
{
"domain": "string",
"source": "own_brand",
"pageviews": 0
}
],
"engines": [
{
"engine": "string",
"mode": "web_search",
"available": true,
"enabled": true,
"frequency": "daily"
}
],
"own_domains": [
"string"
],
"active_prompts": 0,
"paused_prompts": 0,
"keywords": 0,
"has_checks": true,
"ai_data_processing_approved": true,
"first_run_available": true,
"prompt_target": 0,
"website_days": 0
}

Create web analytics fetch llms

Loads an llms.txt file from a public URL for coverage analysis without saving it.

Required API key scopes

web_analytics:read

Request parameters

  • url
    string

Response


Example request

POST /api/projects/:project_id/web_analytics/llms_txt
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl
-H 'Content-Type: application/json'\
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/web_analytics/llms_txt/\
-d url="string"

Example response

Status 200
RESPONSE
{
"content": "string",
"url": "http://example.com"
}
Status 400 The URL is invalid, inaccessible, or does not return an llms.txt file.

Create web analytics fetch llms

Loads an llms.txt file from a public URL for coverage analysis without saving it.

Required API key scopes

web_analytics:read

Request parameters

  • url
    string

Response


Example request

POST /api/projects/:project_id/web_analytics/llms_txt
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl
-H 'Content-Type: application/json'\
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/web_analytics/llms_txt/\
-d url="string"

Example response

Status 200
RESPONSE
{
"content": "string",
"url": "http://example.com"
}
Status 400 The URL is invalid, inaccessible, or does not return an llms.txt file.

Retrieve web analytics

The 'Wrapped'-style weekly recap: everything in the weekly digest (visitors, pageviews, sessions, bounce rate, average session duration with period-over-period comparisons, top pages, top sources, and goals) plus a single derived weekly persona and a short list of screenshot-worthy highlights for the period.

Required API key scopes

web_analytics:read

Query parameters

  • compare
    boolean
    Default: true
  • days
    integer
    Default: 7

Response


Example request

GET /api/projects/:project_id/web_analytics/recap
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/web_analytics/recap/

Example response

Status 200
RESPONSE
{
"visitors": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"pageviews": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"sessions": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"bounce_rate": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"avg_session_duration": {
"current": "string",
"previous": "string",
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"top_pages": [
{
"host": "string",
"path": "string",
"visitors": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"top_sources": [
{
"name": "string",
"visitors": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"goals": [
{
"name": "string",
"conversions": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"metadata": {
"data_status": "ok",
"date_from": "2019-08-24T14:15:22Z",
"date_to": "2019-08-24T14:15:22Z",
"timezone": "string",
"filter_test_accounts": true,
"notes": [
"string"
]
},
"dashboard_url": "http://example.com",
"persona": {
"id": "string",
"name": "string",
"emoji": "string",
"blurb": "string",
"color": "string"
},
"highlights": [
{
"id": "string",
"emoji": "string",
"title": "string",
"value": "string",
"detail": "string"
}
],
"period_label": "string",
"period_start": "2019-08-24",
"period_end": "2019-08-24",
"project_name": "string",
"recap_url": "http://example.com"
}

Retrieve web analytics

The 'Wrapped'-style weekly recap: everything in the weekly digest (visitors, pageviews, sessions, bounce rate, average session duration with period-over-period comparisons, top pages, top sources, and goals) plus a single derived weekly persona and a short list of screenshot-worthy highlights for the period.

Required API key scopes

web_analytics:read

Query parameters

  • compare
    boolean
    Default: true
  • days
    integer
    Default: 7

Response


Example request

GET /api/projects/:project_id/web_analytics/recap
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/web_analytics/recap/

Example response

Status 200
RESPONSE
{
"visitors": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"pageviews": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"sessions": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"bounce_rate": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"avg_session_duration": {
"current": "string",
"previous": "string",
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"top_pages": [
{
"host": "string",
"path": "string",
"visitors": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"top_sources": [
{
"name": "string",
"visitors": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"goals": [
{
"name": "string",
"conversions": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"metadata": {
"data_status": "ok",
"date_from": "2019-08-24T14:15:22Z",
"date_to": "2019-08-24T14:15:22Z",
"timezone": "string",
"filter_test_accounts": true,
"notes": [
"string"
]
},
"dashboard_url": "http://example.com",
"persona": {
"id": "string",
"name": "string",
"emoji": "string",
"blurb": "string",
"color": "string"
},
"highlights": [
{
"id": "string",
"emoji": "string",
"title": "string",
"value": "string",
"detail": "string"
}
],
"period_label": "string",
"period_start": "2019-08-24",
"period_end": "2019-08-24",
"project_name": "string",
"recap_url": "http://example.com"
}

Retrieve web analytics weekly

Also available via the PostHog MCP server:

  • web-analytics-weekly-digest — Summarize web analytics

Summarizes a project's web analytics over a lookback window (default 7 days): unique visitors, pageviews, sessions, bounce rate, and average session duration with period-over-period comparisons, plus the top 5 pages, top 5 traffic sources, and goal conversions.

Required API key scopes

web_analytics:read

Query parameters

  • compare
    boolean
    Default: true
  • days
    integer
    Default: 7

Response


Example request

GET /api/projects/:project_id/web_analytics/weekly_digest
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/web_analytics/weekly_digest/

Example response

Status 200
RESPONSE
{
"visitors": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"pageviews": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"sessions": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"bounce_rate": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"avg_session_duration": {
"current": "string",
"previous": "string",
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"top_pages": [
{
"host": "string",
"path": "string",
"visitors": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"top_sources": [
{
"name": "string",
"visitors": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"goals": [
{
"name": "string",
"conversions": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"metadata": {
"data_status": "ok",
"date_from": "2019-08-24T14:15:22Z",
"date_to": "2019-08-24T14:15:22Z",
"timezone": "string",
"filter_test_accounts": true,
"notes": [
"string"
]
},
"dashboard_url": "http://example.com"
}

Retrieve web analytics weekly

Also available via the PostHog MCP server:

  • web-analytics-weekly-digest — Summarize web analytics

Summarizes a project's web analytics over a lookback window (default 7 days): unique visitors, pageviews, sessions, bounce rate, and average session duration with period-over-period comparisons, plus the top 5 pages, top 5 traffic sources, and goal conversions.

Required API key scopes

web_analytics:read

Query parameters

  • compare
    boolean
    Default: true
  • days
    integer
    Default: 7

Response


Example request

GET /api/projects/:project_id/web_analytics/weekly_digest
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/web_analytics/weekly_digest/

Example response

Status 200
RESPONSE
{
"visitors": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"pageviews": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"sessions": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"bounce_rate": {
"current": 0.1,
"previous": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"avg_session_duration": {
"current": "string",
"previous": "string",
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
},
"top_pages": [
{
"host": "string",
"path": "string",
"visitors": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"top_sources": [
{
"name": "string",
"visitors": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"goals": [
{
"name": "string",
"conversions": 0,
"change": {
"percent": 0,
"direction": "Up",
"color": "string",
"text": "string",
"long_text": "string"
}
}
],
"metadata": {
"data_status": "ok",
"date_from": "2019-08-24T14:15:22Z",
"date_to": "2019-08-24T14:15:22Z",
"timezone": "string",
"filter_test_accounts": true,
"notes": [
"string"
]
},
"dashboard_url": "http://example.com"
}

Create web analytics content autopilot opportunities

Marks an opportunity as dismissed. It stays dismissed across refreshes, and list responses still include it with status dismissed.

Required API key scopes

web_analytics:write

Path parameters

  • id
    string

Response


Example request

POST /api/projects/:project_id/web_analytics_content_autopilot_opportunities/:id/dismiss
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl
-H 'Content-Type: application/json'\
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/web_analytics_content_autopilot_opportunities/:id/dismiss/

Example response

Status 200
RESPONSE
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"profile_id": "bfcb6779-b1f9-41fc-92d7-88f8bc1d12e8",
"run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
"proposal_id": "10dc578f-36d9-436c-bba3-e0bf53d58e9e",
"aeo_prompt_id": "adad77ff-a22f-4bc3-a87b-7040edd168b8",
"kind": "ai_visibility_gap",
"title": "string",
"score": 0.1,
"recommended_type": "new_content",
"target_url": "http://example.com",
"evidence": [
{
"opportunity_kind": "poor_ctr",
"explanation": "string",
"page_url": "http://example.com",
"query": "string"
}
],
"gap": {
"checks": 0,
"cited_checks": 0,
"mentioned_checks": 0,
"citation_rate": 0.1,
"engines": [
"string"
],
"engines_not_citing": [
"string"
],
"competitor_urls": [
"string"
],
"competitor_domains": [
"string"
],
"engine_search_queries": [
"string"
],
"our_cited_urls": [
"string"
],
"latest_answers": [
{
"engine": "string",
"answer_text": "string",
"checked_at": "string"
}
],
"last_checked_at": "string"
},
"status": "new",
"last_refreshed_at": "2019-08-24T14:15:22Z",
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}