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:readPath parameters
- idstring
Response
Example request
GET /api /projects /:project_id /aeo_prompts /:id /statsExample response
Status 200
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:readPath parameters
- idstring
Example request
GET /api /projects /:project_id /aeo_prompts /:id /versionsExample response
Status 200
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:writeRequest parameters
- promptsarray
Response
Example request
POST /api /projects /:project_id /aeo_prompts /bulk_importExample response
Status 200
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:readQuery parameters
- brandedstringDefault:
allOne of:"all""branded""non_branded" - daysintegerDefault:
30 - domainstring
- enginestring
- include_answer_textbooleanDefault:
false - limitinteger
- offsetinteger
- searchstring
- urlstring
Response
Example request
GET /api /projects /:project_id /aeo_prompts /citationsExample response
Status 200
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:writeResponse
Example request
POST /api /projects /:project_id /aeo_prompts /create_dashboardExample response
Status 201
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:readQuery parameters
- brandedstringDefault:
allOne of:"all""branded""non_branded" - daysintegerDefault:
30 - enginestring | null
- topicstring | null
Response
Example request
GET /api /projects /:project_id /aeo_prompts /overviewExample response
Status 200
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:readQuery parameters
- brandedstringDefault:
allOne of:"all""branded""non_branded" - daysintegerDefault:
30 - enginestring | null
- topicstring | null
Response
Example request
GET /api /projects /:project_id /aeo_prompts /rankingsExample response
Status 200
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:writeRequest parameters
- domainstring
- brandstring
- descriptionstring
- competitorsarray
- topicsarray
- countintegerDefault:
20
Response
Example request
POST /api /projects /:project_id /aeo_prompts /suggestExample response
Status 202
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:readPath parameters
- job_idstring
Response
Example request
GET /api /projects /:project_id /aeo_prompts /suggest /:job_idExample response
Status 200
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:readExample request
GET /api /projects /:project_id /aeo_prompts /topicsExample response
Status 200
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:writeRequest parameters
- domainstring
- brandstring
- descriptionstring
- enginesarray
- run_first_checkbooleanDefault:
false - only_first_runbooleanDefault:
false - activate_paused_promptsbooleanDefault:
false
Response
Example request
POST /api /projects /:project_id /aeo_setupExample response
Status 202
Status 400 The domain is not valid, or no chosen engine can run.
Status 409 A setup job is already running for the project.
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:readPath parameters
- idstring
Response
Example request
GET /api /projects /:project_id /aeo_setup /:idExample response
Status 200
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:readResponse
Example request
GET /api /projects /:project_id /aeo_setup /contextExample response
Status 200
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:readRequest parameters
- urlstring
Response
Example request
POST /api /projects /:project_id /web_analytics /llms_txtExample response
Status 200
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:readRequest parameters
- urlstring
Response
Example request
POST /api /projects /:project_id /web_analytics /llms_txtExample response
Status 200
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:readQuery parameters
- comparebooleanDefault:
true - daysintegerDefault:
7
Response
Example request
GET /api /projects /:project_id /web_analytics /recapExample response
Status 200
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:readQuery parameters
- comparebooleanDefault:
true - daysintegerDefault:
7
Response
Example request
GET /api /projects /:project_id /web_analytics /recapExample response
Status 200
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:readQuery parameters
- comparebooleanDefault:
true - daysintegerDefault:
7
Response
Example request
GET /api /projects /:project_id /web_analytics /weekly_digestExample response
Status 200
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:readQuery parameters
- comparebooleanDefault:
true - daysintegerDefault:
7
Response
Example request
GET /api /projects /:project_id /web_analytics /weekly_digestExample response
Status 200
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:writePath parameters
- idstring
Response
Example request
POST /api /projects /:project_id /web_analytics_content_autopilot_opportunities /:id /dismiss




