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:read

Query parameters

  • kind
    string
    One of: "own""competitor""publisher""unknown"
  • limit
    integer
  • offset
    integer
  • search
    string
  • status
    string
    One of: "suggested""confirmed""ignored"

Response


Example request

GET /api/projects/:project_id/aeo_brands
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_brands/

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": [
{
"id": "string",
"name": "string",
"domain": "string",
"kind": "own",
"status": "suggested",
"source": "citations",
"aliases": [
"string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}
]
}

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:write

Request parameters

  • domain
    string
  • name
    string
  • kind
  • aliases
    array

Response


Example request

POST /api/projects/:project_id/aeo_brands
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_brands/\
-d domain="string",\
-d kind=undefined

Example response

Status 201
RESPONSE
{
"id": "string",
"name": "string",
"domain": "string",
"kind": "own",
"status": "suggested",
"source": "citations",
"aliases": [
"string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

Retrieve aeo brands

Gets one brand from the project's brand catalog.

Required API key scopes

web_analytics:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/aeo_brands/: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_brands/:id/

Example response

Status 200
RESPONSE
{
"id": "string",
"name": "string",
"domain": "string",
"kind": "own",
"status": "suggested",
"source": "citations",
"aliases": [
"string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

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:write

Path parameters

  • id
    string

Request parameters

  • name
    string
  • kind
  • status
  • aliases
    array

Response


Example request

PATCH /api/projects/:project_id/aeo_brands/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_brands/:id/\
-d name="string"

Example response

Status 200
RESPONSE
{
"id": "string",
"name": "string",
"domain": "string",
"kind": "own",
"status": "suggested",
"source": "citations",
"aliases": [
"string"
],
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
}

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:read

Example request

GET /api/projects/:project_id/aeo_engines
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_engines/

Example response

Status 200
RESPONSE
{
"engine": "string",
"mode": "web_search",
"available": true,
"enabled": true,
"frequency": "daily"
}

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:write

Path parameters

  • id
    string

Request parameters

  • enabled
    boolean
  • frequency

Response


Example request

PATCH /api/projects/:project_id/aeo_engines/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_engines/:id/\
-d enabled="boolean"

Example response

Status 200
RESPONSE
{
"engine": "string",
"mode": "web_search",
"available": true,
"enabled": true,
"frequency": "daily"
}

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:read

Example request

GET /api/projects/:project_id/aeo_keywords
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_keywords/

Example response

Status 200
RESPONSE
{
"id": "string",
"keyword": "string",
"created_at": "2019-08-24T14:15:22Z"
}

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:write

Request parameters

  • keywords
    array

Response


Example request

POST /api/projects/:project_id/aeo_keywords
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_keywords/\
-d keywords="array"

Example response

Status 201
RESPONSE
{
"created": 0,
"skipped": 0
}
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:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/aeo_keywords/: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_keywords/:id/

Example response

Status 200
RESPONSE
{
"id": "string",
"keyword": "string",
"created_at": "2019-08-24T14:15:22Z"
}

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:write

Path parameters

  • id
    string

Example request

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

Example 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:read

Query parameters

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

Response


Example request

GET /api/projects/:project_id/aeo_keywords/modifiers
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_keywords/modifiers/

Example response

Status 200
RESPONSE
{
"modifiers": [
{
"engines": [
{
"engine": "string",
"answers": 0
}
],
"term": "string",
"kind": "freshness",
"answers": 0,
"share": 0.1,
"cited_rate": 0,
"example_searches": [
"string"
]
}
],
"days": 0,
"window_from": "2019-08-24",
"window_to": "2019-08-24",
"keyword": "string",
"answers": 0,
"baseline_cited_rate": 0
}

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:read

Query parameters

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

Response


Example request

GET /api/projects/:project_id/aeo_keywords/report
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_keywords/report/

Example response

Status 200
RESPONSE
{
"keywords": [
{
"keyword": "string",
"prompts": 0,
"prompt_checks": 0,
"prompt_mention_rate": 0,
"prompt_cited_rate": 0,
"searched_checks": 0,
"searched_rate": 0,
"searched_cited_rate": 0,
"answer_checks": 0,
"answer_rate": 0,
"uses_per_answer": 0,
"answer_mention_rate": 0,
"avg_citation_position": 0,
"median_first_mention_depth": 0
}
],
"days": 0,
"window_from": "2019-08-24",
"window_to": "2019-08-24",
"answers": 0,
"brand_names": [
"string"
]
}

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:write

Request parameters

  • domain
    string
  • brand
    string
  • description
    string
  • count
    integer
    Default: 20

Response


Example request

POST /api/projects/:project_id/aeo_keywords/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_keywords/suggest/\
-d domain="string"

Example response

Status 202
RESPONSE
{
"suggestions": [
{
"keyword": "string",
"reason": "string",
"searched_checks": 0
}
],
"id": "string",
"status": "pending",
"error": "string"
}
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:read

Path parameters

  • job_id
    string

Response


Example request

GET /api/projects/:project_id/aeo_keywords/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_keywords/suggest/:job_id/

Example response

Status 200
RESPONSE
{
"suggestions": [
{
"keyword": "string",
"reason": "string",
"searched_checks": 0
}
],
"id": "string",
"status": "pending",
"error": "string"
}

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:read

Query parameters

  • active
    boolean | null
  • branded
    boolean | null
  • days
    integer
    Default: 30
  • engine
    string | null
  • include_archived
    boolean
    Default: false
  • limit
    integer
  • needs_improvement
    boolean
    Default: false
  • offset
    integer
  • topic
    string

Response


Example request

GET /api/projects/:project_id/aeo_prompts
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/

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": [
{
"latest_checks": [
{
"engine": "string",
"mode": "web_search",
"cited": true,
"mentioned": true,
"check_failed": true,
"target_best_position": 0,
"search_queries": [
"string"
],
"checked_at": "2019-08-24T14:15:22Z"
}
],
"id": "string",
"prompt": "string",
"topic": "string",
"prompt_source": "string",
"rank": 0.1,
"active": true,
"last_checked_at": "2019-08-24T14:15:22Z",
"external_visibility": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"archived_at": "2019-08-24T14:15:22Z",
"current_version": 0,
"version_count": 0,
"branded": true
}
]
}

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:read

Path parameters

  • id
    string

Response


Example request

GET /api/projects/:project_id/aeo_prompts/: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/:id/

Example response

Status 200
RESPONSE
{
"latest_checks": [
{
"engine": "string",
"mode": "web_search",
"cited": true,
"mentioned": true,
"check_failed": true,
"target_best_position": 0,
"search_queries": [
"string"
],
"checked_at": "2019-08-24T14:15:22Z"
}
],
"id": "string",
"prompt": "string",
"topic": "string",
"prompt_source": "string",
"rank": 0.1,
"active": true,
"last_checked_at": "2019-08-24T14:15:22Z",
"external_visibility": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"archived_at": "2019-08-24T14:15:22Z",
"current_version": 0,
"version_count": 0,
"branded": true
}

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:write

Path parameters

  • id
    string

Request parameters

  • active
    boolean | null
  • topic
    string
  • prompt
    string
  • version_description
    string
  • current_version
    integer | null
  • archived
    boolean | null

Response


Example request

PATCH /api/projects/:project_id/aeo_prompts/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
-H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
<ph_app_host>/api/projects/:project_id/aeo_prompts/:id/\
-d active="boolean"

Example response

Status 200 The updated prompt.
RESPONSE
{
"latest_checks": [
{
"engine": "string",
"mode": "web_search",
"cited": true,
"mentioned": true,
"check_failed": true,
"target_best_position": 0,
"search_queries": [
"string"
],
"checked_at": "2019-08-24T14:15:22Z"
}
],
"id": "string",
"prompt": "string",
"topic": "string",
"prompt_source": "string",
"rank": 0.1,
"active": true,
"last_checked_at": "2019-08-24T14:15:22Z",
"external_visibility": 0,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"archived_at": "2019-08-24T14:15:22Z",
"current_version": 0,
"version_count": 0,
"branded": true
}
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:write

Path parameters

  • id
    string

Example request

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

Example 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:read

Path parameters

  • id
    string

Query parameters

  • engine
    string
  • include_answer_text
    boolean
    Default: true
  • limit
    integer
  • offset
    integer
  • since
    string
  • version
    integer

Response


Example request

GET /api/projects/:project_id/aeo_prompts/:id/checks
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/checks/

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": [
{
"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
}
]
}

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