Web analytics
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
GET | |
POST | |
GET | |
PATCH | |
GET | |
PATCH | |
GET | |
POST | |
GET | |
DELETE | |
GET | |
GET | |
POST | |
GET | |
GET | |
GET | |
PATCH | |
DELETE | |
GET | |
GET |
List all aeo brands
Lists the project's brand catalog by domain: the project itself, competitors, publishers and domains nobody has labeled yet. Each daily run adds the domains its answers cited for the first time.
Required API key scopes
web_analytics:readQuery parameters
- kindstringOne of:
"own""competitor""publisher""unknown" - limitinteger
- offsetinteger
- searchstring
- statusstringOne of:
"suggested""confirmed""ignored"
Response
Example request
GET /api /projects /:project_id /aeo_brandsExample response
Status 200
Create aeo brands
Adds a brand to the project's brand catalog by domain, confirmed. Add the project's own site with kind 'own' before the first daily run: only own brands count as the project in citations and mentions, and the run skips a project without one. Returns 400 when the catalog already has the domain; update that brand instead.
Required API key scopes
web_analytics:writeRequest parameters
- domainstring
- namestring
- kind
- aliasesarray
Response
Example request
POST /api /projects /:project_id /aeo_brandsExample response
Status 201
Retrieve aeo brands
Gets one brand from the project's brand catalog.
Required API key scopes
web_analytics:readPath parameters
- idstring
Response
Example request
GET /api /projects /:project_id /aeo_brands /:idExample response
Status 200
Update aeo brands
Renames, relabels, confirms or ignores a brand, or replaces its other names. The daily run keeps these edits; it only adds newly cited domains.
Required API key scopes
web_analytics:writePath parameters
- idstring
Request parameters
- namestring
- kind
- status
- aliasesarray
Response
Example request
PATCH /api /projects /:project_id /aeo_brands /:idExample response
Status 200
List all aeo engines
Lists every answer engine the product can run, in display order, with whether the project runs it and how often. The no-search engines answer from training data alone and start off.
Required API key scopes
web_analytics:readExample request
GET /api /projects /:project_id /aeo_enginesExample response
Status 200
Update aeo engines
Turns an answer engine on or off for the project, or sets how often it checks each prompt. The next daily run uses the change. Each check on an engine is a paid model call.
Required API key scopes
web_analytics:writePath parameters
- idstring
Request parameters
- enabledboolean
- frequency
Response
Example request
PATCH /api /projects /:project_id /aeo_engines /:idExample response
Status 200
List all aeo keywords
Lists the project's keyword list, by keyword. The list holds at most 200 keywords, so it is never paged.
Required API key scopes
web_analytics:readExample request
GET /api /projects /:project_id /aeo_keywordsExample response
Status 200
Create aeo keywords
Adds keywords to the project's keyword list. Send many at once. Blank entries and keywords already in the list are skipped and counted. Fails with 400 when the new keywords would take the list past 200.
Required API key scopes
web_analytics:writeRequest parameters
- keywordsarray
Response
Example request
POST /api /projects /:project_id /aeo_keywordsExample response
Status 201
Status 400 The request is invalid, or the list would pass the keyword cap.
Retrieve aeo keywords
Gets one keyword from the project's keyword list.
Required API key scopes
web_analytics:readPath parameters
- idstring
Response
Example request
GET /api /projects /:project_id /aeo_keywords /:idExample response
Status 200
Delete aeo keywords
Removes a keyword from the project's keyword list. Checks are not changed, so adding it back restores its report.
Required API key scopes
web_analytics:writePath parameters
- idstring
Example request
DELETE /api /projects /:project_id /aeo_keywords /:idExample response
Status 204 The keyword is removed.
Retrieve aeo keywords
Gets the words and two-word phrases the engines added to their web searches beyond the prompt over the last 'days' days (default 7), such as years, 'pricing', 'vs' or 'site:'. They show the content the engines look for. Each modifier has a kind, how many answers used it, the citation rate in those answers against the baseline, the engines that used it and example searches. Pass 'keyword' to only count answers whose searches contain it, and 'branded', 'engine' or 'topic' to count only the answers to branded or non-branded prompts, of one answer engine, or of one topic.
Required API key scopes
web_analytics:readQuery parameters
- brandedstringDefault:
allOne of:"all""branded""non_branded" - daysintegerDefault:
7 - enginestring | null
- keywordstring
- topicstring | null
Response
Example request
GET /api /projects /:project_id /aeo_keywords /modifiersExample response
Status 200
Retrieve aeo keywords
Gets one row per keyword for the last 'days' days (default 7) in the project's timezone: how many prompts contain it and how those answers mention and cite the project, how often the engines searched for it and the citation rate in those answers, and how often answers use it, with the brand-mention rate, citation position and how early the brand is named in those answers. All rates are over answered checks. A keyword matches as a phrase, case ignored. Pass 'branded', 'engine' or 'topic' to count only the answers to branded or non-branded prompts, of one answer engine, or of one topic.
Required API key scopes
web_analytics:readQuery parameters
- brandedstringDefault:
allOne of:"all""branded""non_branded" - daysintegerDefault:
7 - enginestring | null
- topicstring | null
Response
Example request
GET /api /projects /:project_id /aeo_keywords /reportExample response
Status 200
Create aeo keywords
Suggests keywords to add to the project's keyword list. Requires AI data processing approved for the organization. PostHog ranks keywords from the site, the project's tracked prompts and topics, and the web searches the engines ran while answering them, and gives a reason for each. PostHog has no search-volume data: each suggestion only carries how many recent answers searched for it. Nothing is saved: add the keywords you keep with aeo_keywords create. Keywords already in the list and keywords that name the brand are left out. Fails with 400 when the list already holds 200 keywords. Returns a pending job right away; poll GET aeo_keywords/suggest/<id>/ until it completes, which takes up to a few minutes.
Required API key scopes
web_analytics:writeRequest parameters
- domainstring
- brandstring
- descriptionstring
- countintegerDefault:
20
Response
Example request
POST /api /projects /:project_id /aeo_keywords /suggestExample response
Status 202
Status 400 The request is invalid, or the keyword list is full.
Retrieve aeo keywords suggestion
Gets a keyword suggestion job started with POST aeo_keywords/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_keywords /suggest /:job_idExample response
Status 200
List all aeo prompts
Lists the project's AEO prompt set, ordered by topic and then rank, one page at a time. Filter by topic, by on/off state, by whether the prompt names the brand, or to the prompts that need improvement, optionally over 'days' days and one 'engine'. Archived prompts are left out unless include_archived is true. Each prompt carries its latest check per answer engine.
Required API key scopes
web_analytics:readQuery parameters
- activeboolean | null
- brandedboolean | null
- daysintegerDefault:
30 - enginestring | null
- include_archivedbooleanDefault:
false - limitinteger
- needs_improvementbooleanDefault:
false - offsetinteger
- topicstring
Response
Example request
GET /api /projects /:project_id /aeo_promptsExample response
Status 200
Retrieve aeo prompts
Gets one prompt from the project's AEO prompt set, archived ones included, with its latest check per answer engine.
Required API key scopes
web_analytics:readPath parameters
- idstring
Response
Example request
GET /api /projects /:project_id /aeo_prompts /:idExample response
Status 200
Update aeo prompts
Turns a prompt on or off, changes its topic, archives or restores it, or changes its text. A text change adds the next version and makes it current, and current_version moves back to an earlier one. The prompt keeps its id, and past checks are always kept.
Required API key scopes
web_analytics:writePath parameters
- idstring
Request parameters
- activeboolean | null
- topicstring
- promptstring
- version_descriptionstring
- current_versioninteger | null
- archivedboolean | null
Response
Example request
PATCH /api /projects /:project_id /aeo_prompts /:idExample response
Status 200 The updated prompt.
Status 400 The edit is invalid, the version does not exist, or the prompt is archived and must be restored first.
Status 409 Another prompt in the set already has the new text.
Delete aeo prompts
Archives a prompt: it is turned off and never runs again. Nothing is deleted, and its versions and checks are kept. Restore it with a PATCH of archived=false.
Required API key scopes
web_analytics:writePath parameters
- idstring
Example request
DELETE /api /projects /:project_id /aeo_prompts /:idExample response
Status 204 The prompt is archived.
Retrieve aeo prompts
Lists every check of one prompt, newest first, one page at a time. Filter by engine, by prompt version, or with since to see only checks from a point in time on. Each check has the engine's answer, the URLs it cited, the searches it ran and the prompt version it ran. Set include_answer_text=false to leave the answers out and page through history with smaller responses.
Required API key scopes
web_analytics:readPath parameters
- idstring
Query parameters
- enginestring
- include_answer_textbooleanDefault:
true - limitinteger
- offsetinteger
- sincestring
- versioninteger
Response
Example request
GET /api /projects /:project_id /aeo_prompts /:id /checksExample response
Status 200
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 /stats




