Web analytics

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

Endpoints

`POST`
`GET`
`GET`

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/web_analytics/llms_txt/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"url": "string"
	}
).json()

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"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/web_analytics/llms_txt/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"url": "string"
	}
).json()

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/web_analytics/recap/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
      }
    }
  ],
  "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

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/web_analytics/recap/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
      }
    }
  ],
  "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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/web_analytics/weekly_digest/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
      }
    }
  ],
  "dashboard_url": "http://example.com"
}

Retrieve web analytics weekly

Also available via the PostHog MCP server:
web-analytics-weekly-digest — Summarize web analytics

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/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/web_analytics/weekly_digest/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

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"
      }
    }
  ],
  "dashboard_url": "http://example.com"
}