Web analytics

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

Endpoints

GET
GET
PATCH
DELETE
GET
GET
GET
POST
GET
POST
GET
GET
POST
POST
POST
POST
POST
Next page →

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 or by on/off state. 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
  • include_archived
    boolean
    Default: false
  • limit
    integer
  • 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",
          "cited": true,
          "check_failed": true,
          "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
    }
  ]
}

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",
      "cited": true,
      "check_failed": true,
      "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
}

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",
      "cited": true,
      "check_failed": true,
      "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
}
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 or by prompt version. Each check has the engine's answer, the URLs it cited, the searches it ran and the prompt version it ran.

Required API key scopes

web_analytics:read

Path parameters

  • id
    string

Query parameters

  • engine
    string
  • limit
    integer
  • offset
    integer
  • 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",
      "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,
      "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
    }
  ],
  "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 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 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",
  "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"
}

Create web analytics content autopilot opportunities

Starts a run that researches and drafts content for the selected opportunities.

Required API key scopes

web_analytics:write

Request parameters

  • profile_id
    string
  • opportunity_ids
    array

Response


Example request

POST /api/projects/:project_id/web_analytics_content_autopilot_opportunities/draft
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/draft/\
	-d profile_id="string",\
	-d opportunity_ids="array"

Example response

Status 202
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "profile_id": "bfcb6779-b1f9-41fc-92d7-88f8bc1d12e8",
  "run_status": "pending",
  "input_snapshot": {
    "domain": "http://example.com",
    "confidence": "standard",
    "source_urls": [
      "http://example.com"
    ],
    "content_boundaries": [
      "string"
    ],
    "brand_rules": [
      "string"
    ]
  },
  "errors": [
    {
      "error_code": "string",
      "message": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}

Create web analytics content autopilot opportunities

Re-reads AI citation checks and updates the site's content opportunities. Makes no model calls.

Required API key scopes

web_analytics:write

Request parameters

  • profile_id
    string

Example request

POST /api/projects/:project_id/web_analytics_content_autopilot_opportunities/refresh
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/refresh/\
	-d profile_id="string"

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

Create web analytics content autopilot profiles

Inspects a public site for its canonical origin, name, and sitemap URLs.

Required API key scopes

web_analytics:write

Request parameters

  • domain
    string

Response


Example request

POST /api/projects/:project_id/web_analytics_content_autopilot_profiles/discover
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_profiles/discover/\
	-d domain="string"

Example response

Status 200
RESPONSE
{
  "name": "string",
  "domain": "http://example.com",
  "source_urls": [
    "http://example.com"
  ],
  "content_boundaries": [
    "string"
  ],
  "sitemap_detected": true,
  "warnings": [
    "string"
  ]
}

Create web analytics content autopilot proposals

Saves reviewed Markdown and its structured package without publishing it.

Required API key scopes

web_analytics:write

Path parameters

  • id
    string

Request parameters

  • proposed_markdown
    string
  • content_package

Response


Example request

POST /api/projects/:project_id/web_analytics_content_autopilot_proposals/:id/edit
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_proposals/:id/edit/\
	-d proposed_markdown="string",\
	-d content_package=undefined

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  "proposal_type": "new_content",
  "lifecycle_status": "generating",
  "title": "string",
  "target_query": "string",
  "target_url": "http://example.com",
  "evidence": [
    {
      "opportunity_kind": "poor_ctr",
      "explanation": "string",
      "page_url": "http://example.com",
      "query": "string"
    }
  ],
  "validation_report": {
    "passed": true,
    "checks": [
      {
        "check_key": "string",
        "label": "string",
        "passed": true,
        "message": "string",
        "blocking": true
      }
    ]
  },
  "content_package": {
    "file_path": "string",
    "title": "string",
    "description": "string",
    "slug": "string",
    "frontmatter": [
      {
        "key": "string",
        "value": "string"
      }
    ],
    "internal_links": [
      "http://example.com"
    ],
    "source_notes": [
      "string"
    ],
    "json_ld": "string",
    "llms_txt_line": "string"
  },
  "original_markdown": "string",
  "proposed_markdown": "string",
  "brief": {
    "intent": "string",
    "audience": "string",
    "recommended_type": "string",
    "target_page": "string",
    "site_pages_to_read": [
      "string"
    ],
    "competitors_to_research": [
      {
        "name": "string",
        "url": "string"
      }
    ],
    "working_title": "string",
    "outline": [
      "string"
    ],
    "questions_to_answer": [
      "string"
    ],
    "competitor_coverage": [
      "string"
    ],
    "engine_answer_summary": "string",
    "disambiguation": "string"
  },
  "source_ledger": [
    {
      "claim": "string",
      "source_url": "string",
      "quote": "string",
      "kind": "site"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
Next page →