Marketing

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

Endpoints

`POST`
`GET`
`DELETE`
`PATCH`
`POST`
`GET`
`POST`
`POST`
`GET`
`GET`
`GET`
`GET`
`GET`
`GET`
`GET`
`POST`
`GET`

Create marketing analytics apply setup ops

Apply one or more setup operations from the setup plan, atomically. Either every operation lands or none does — a partially-applied batch has no well-defined undo. Returns undo_ops, computed from the pre-change state, which can be POSTed back to reverse the batch. Only send apply payloads returned by setup_plan.

Required API key scopes

marketing_analytics:write

Request parameters

ops
array
source
Default: setup_tab

Response

Example request

POST /api/projects/:project_id/marketing_analytics/apply_setup_ops
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/marketing_analytics/apply_setup_ops/\
	-d ops="array"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/apply_setup_ops/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"ops": "array"
	}
).json()

Example response

Status 200 The applied operations and the ops that reverse them

RESPONSE
{
  "applied": [
    null
  ],
  "undo_ops": [
    null
  ],
  "marketing_analytics_config": null
}

Status 400 An operation was malformed, unsupported, or not applicable

Status 404 Marketing Setup and new dashboard feature flags are both off

Retrieve marketing analytics conversion goals

Read the configured conversion goals for the current project — each with its kind, target, last-30d count, integrated vs non-integrated split, and a misconfiguration flag. Read-only.

Required API key scopes

marketing_analytics:read

Response

Example request

GET /api/projects/:project_id/marketing_analytics/conversion_goals
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/conversion_goals/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/conversion_goals/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Configured conversion goals with last-30d performance

RESPONSE
{
  "goals": [
    {
      "conversion_goal_id": "string",
      "name": "string",
      "kind": "EventsNode",
      "target_label": "string",
      "last_30d_count": 0,
      "integrated_count": 0,
      "events_without_utm_source": 0,
      "events_with_unmatched_utm_source": 0,
      "non_integrated_count": 0,
      "integrated_pct": 0,
      "is_misconfigured": true,
      "misconfig_reason": "string",
      "is_approximate": true,
      "approximation_reason": "string"
    }
  ],
  "attribution_window_days": 0,
  "attribution_mode": "string",
  "has_misconfigured": true
}

Delete marketing analytics conversion goals delete

Remove one conversion goal from the project, leaving the others in place.

Required API key scopes

marketing_analytics:write

Path parameters

conversion_goal_id
string

Response

Example request

DELETE /api/projects/:project_id/marketing_analytics/conversion_goals/:conversion_goal_id/delete
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/marketing_analytics/conversion_goals/:conversion_goal_id/delete/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.delete(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/conversion_goals/{conversion_goal_id}/delete/".format(
        project_id=project_id,
		conversion_goal_id="<the conversion goal id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
)

Example response

Status 200 The goals left after the delete

RESPONSE
{
  "goal": {
    "conversion_goal_id": "string",
    "conversion_goal_name": "string",
    "counts_as_customer": null,
    "counts_as_revenue": null,
    "custom_name": null,
    "event": null,
    "fixedProperties": null,
    "kind": "EventsNode",
    "limit": null,
    "math": null,
    "math_group_type_index": null,
    "math_hogql": null,
    "math_multiplier": null,
    "math_property": null,
    "math_property_revenue_currency": null,
    "math_property_type": null,
    "name": null,
    "optionalInFunnel": null,
    "orderBy": null,
    "properties": null,
    "response": null,
    "schema_map": {
      "property1": "string",
      "property2": "string"
    },
    "version": null
  },
  "conversion_goals": [
    {
      "conversion_goal_id": "string",
      "conversion_goal_name": "string",
      "counts_as_customer": null,
      "counts_as_revenue": null,
      "custom_name": null,
      "event": null,
      "fixedProperties": null,
      "kind": "EventsNode",
      "limit": null,
      "math": null,
      "math_group_type_index": null,
      "math_hogql": null,
      "math_multiplier": null,
      "math_property": null,
      "math_property_revenue_currency": null,
      "math_property_type": null,
      "name": null,
      "optionalInFunnel": null,
      "orderBy": null,
      "properties": null,
      "response": null,
      "schema_map": {
        "property1": "string",
        "property2": "string"
      },
      "version": null
    }
  ]
}

Status 403 Requires project admin access

Status 404 No goal with that conversion_goal_id

Update marketing analytics conversion goals update

Change one conversion goal in place. Fields you send are merged into the stored goal, the rest are kept, and the goal keeps its position in the list. Sending a different kind replaces the goal instead, since the shapes don't share their fields.

Required API key scopes

marketing_analytics:write

Path parameters

conversion_goal_id
string

Request parameters

goal

Response

Example request

PATCH /api/projects/:project_id/marketing_analytics/conversion_goals/:conversion_goal_id/update
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/marketing_analytics/conversion_goals/:conversion_goal_id/update/\
	-d goal=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.patch(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/conversion_goals/{conversion_goal_id}/update/".format(
        project_id=project_id,
		conversion_goal_id="<the conversion goal id>"
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 200 The goal as updated

RESPONSE
{
  "goal": {
    "conversion_goal_id": "string",
    "conversion_goal_name": "string",
    "counts_as_customer": null,
    "counts_as_revenue": null,
    "custom_name": null,
    "event": null,
    "fixedProperties": null,
    "kind": "EventsNode",
    "limit": null,
    "math": null,
    "math_group_type_index": null,
    "math_hogql": null,
    "math_multiplier": null,
    "math_property": null,
    "math_property_revenue_currency": null,
    "math_property_type": null,
    "name": null,
    "optionalInFunnel": null,
    "orderBy": null,
    "properties": null,
    "response": null,
    "schema_map": {
      "property1": "string",
      "property2": "string"
    },
    "version": null
  },
  "conversion_goals": [
    {
      "conversion_goal_id": "string",
      "conversion_goal_name": "string",
      "counts_as_customer": null,
      "counts_as_revenue": null,
      "custom_name": null,
      "event": null,
      "fixedProperties": null,
      "kind": "EventsNode",
      "limit": null,
      "math": null,
      "math_group_type_index": null,
      "math_hogql": null,
      "math_multiplier": null,
      "math_property": null,
      "math_property_revenue_currency": null,
      "math_property_type": null,
      "name": null,
      "optionalInFunnel": null,
      "orderBy": null,
      "properties": null,
      "response": null,
      "schema_map": {
        "property1": "string",
        "property2": "string"
      },
      "version": null
    }
  ]
}

Status 400 The resulting goal does not match any conversion goal shape

Status 403 Requires project admin access

Status 404 No goal with that conversion_goal_id

Create marketing analytics conversion goals create

Add one conversion goal to the project. The server assigns conversion_goal_id and appends the goal to the end of the list, leaving existing goals untouched.

Required API key scopes

marketing_analytics:write

Request parameters

goal

Response

Example request

POST /api/projects/:project_id/marketing_analytics/conversion_goals/create
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/marketing_analytics/conversion_goals/create/\
	-d goal=undefined
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/conversion_goals/create/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={}
).json()

Example response

Status 201 The goal as created

RESPONSE
{
  "goal": {
    "conversion_goal_id": "string",
    "conversion_goal_name": "string",
    "counts_as_customer": null,
    "counts_as_revenue": null,
    "custom_name": null,
    "event": null,
    "fixedProperties": null,
    "kind": "EventsNode",
    "limit": null,
    "math": null,
    "math_group_type_index": null,
    "math_hogql": null,
    "math_multiplier": null,
    "math_property": null,
    "math_property_revenue_currency": null,
    "math_property_type": null,
    "name": null,
    "optionalInFunnel": null,
    "orderBy": null,
    "properties": null,
    "response": null,
    "schema_map": {
      "property1": "string",
      "property2": "string"
    },
    "version": null
  },
  "conversion_goals": [
    {
      "conversion_goal_id": "string",
      "conversion_goal_name": "string",
      "counts_as_customer": null,
      "counts_as_revenue": null,
      "custom_name": null,
      "event": null,
      "fixedProperties": null,
      "kind": "EventsNode",
      "limit": null,
      "math": null,
      "math_group_type_index": null,
      "math_hogql": null,
      "math_multiplier": null,
      "math_property": null,
      "math_property_revenue_currency": null,
      "math_property_type": null,
      "name": null,
      "optionalInFunnel": null,
      "orderBy": null,
      "properties": null,
      "response": null,
      "schema_map": {
        "property1": "string",
        "property2": "string"
      },
      "version": null
    }
  ]
}

Status 400 The goal does not match any conversion goal shape

Status 403 Requires project admin access

Retrieve marketing analytics conversion recommendations

Required API key scopes

marketing_analytics:read

Response

Example request

GET /api/projects/:project_id/marketing_analytics/conversion_recommendations
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/conversion_recommendations/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/conversion_recommendations/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "generation_disabled_reason": "string",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "pending",
    "lookback_days": 0,
    "date_from": "2019-08-24T14:15:22Z",
    "date_to": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "error": "string"
  },
  "result_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "pending",
    "lookback_days": 0,
    "date_from": "2019-08-24T14:15:22Z",
    "date_to": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "error": "string"
  },
  "results": {
    "recommendations": [
      {
        "source_ref": "string",
        "name": "string",
        "reason": "string",
        "intent": "conversion",
        "questions": [
          "string"
        ],
        "candidate": {
          "source_ref": "string",
          "kind": "EventsNode",
          "event": null,
          "action_id": null,
          "name": "string",
          "description": "",
          "count": null,
          "distinct_users": null,
          "numeric_properties": [
            "string"
          ],
          "property_names": [
            "string"
          ],
          "already_configured": false
        },
        "amount_property": null
      }
    ],
    "limitations": [
      "string"
    ]
  },
  "can_generate": true
}

Create marketing analytics conversion recommendations start

Required API key scopes

marketing_analytics:write

Request parameters

refresh
boolean
Default: false

Response

Example request

POST /api/projects/:project_id/marketing_analytics/conversion_recommendations/start
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/marketing_analytics/conversion_recommendations/start/\
	-d refresh="boolean"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/conversion_recommendations/start/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"refresh": "boolean"
	}
).json()

Example response

Status 200

RESPONSE
{
  "generation_disabled_reason": "string",
  "latest_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "pending",
    "lookback_days": 0,
    "date_from": "2019-08-24T14:15:22Z",
    "date_to": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "error": "string"
  },
  "result_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "status": "pending",
    "lookback_days": 0,
    "date_from": "2019-08-24T14:15:22Z",
    "date_to": "2019-08-24T14:15:22Z",
    "created_at": "2019-08-24T14:15:22Z",
    "completed_at": "2019-08-24T14:15:22Z",
    "error": "string"
  },
  "results": {
    "recommendations": [
      {
        "source_ref": "string",
        "name": "string",
        "reason": "string",
        "intent": "conversion",
        "questions": [
          "string"
        ],
        "candidate": {
          "source_ref": "string",
          "kind": "EventsNode",
          "event": null,
          "action_id": null,
          "name": "string",
          "description": "",
          "count": null,
          "distinct_users": null,
          "numeric_properties": [
            "string"
          ],
          "property_names": [
            "string"
          ],
          "already_configured": false
        },
        "amount_property": null
      }
    ],
    "limitations": [
      "string"
    ]
  },
  "can_generate": true
}

List all marketing analytics conversion recordings

Required API key scopes

marketing_analytics:readsession_recording:read

Request parameters

client_query_id
string
source
goal_id
string
group
string
source_name
string
Default:
campaign_id
string | null
after
string
limit
integer
Default: 100

Response

Example request

POST /api/projects/:project_id/marketing_analytics/conversion_recordings
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/marketing_analytics/conversion_recordings/\
	-d source=undefined,\
	-d goal_id="string",\
	-d group="string"
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.post(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/conversion_recordings/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
	data={
		"goal_id": "string",
		"group": "string"
	}
).json()

Example response

Status 200

RESPONSE
{
  "session_ids": [
    "string"
  ],
  "has_more": true,
  "preparing": true
}

Retrieve marketing analytics data sources

Check the platform → data-warehouse side of every native marketing integration: connection state, sync recency, row counts, required-table status, and schema-mapping coverage. Read-only.

Required API key scopes

marketing_analytics:read

Query parameters

source_type
string | null

Response

Example request

GET /api/projects/:project_id/marketing_analytics/data_sources
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/data_sources/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/data_sources/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Per-integration data-source (sync) health

RESPONSE
{
  "integrations": [
    {
      "source_type": "string",
      "is_native": true,
      "display_name": "string",
      "connected": true,
      "last_sync_at": "2019-08-24T14:15:22Z",
      "last_sync_status": "string",
      "last_error": "string",
      "rows_last_24h": 0,
      "rows_last_7d": 0,
      "sources_map_present": true,
      "schema_columns_mapped": [
        "string"
      ],
      "schema_columns_required_missing": [
        "string"
      ],
      "required_tables": [
        {
          "table_name": "string",
          "present": true,
          "should_sync": true,
          "status": "string",
          "last_synced_at": "2019-08-24T14:15:22Z"
        }
      ],
      "settings_url": "string",
      "schemas_url": "string",
      "diagnosis": "string",
      "fix_suggestion": "string"
    }
  ],
  "has_any_data": true,
  "overall_status": "string",
  "issues_summary": [
    "string"
  ]
}

Retrieve marketing analytics diagnose

Aggregate data-source sync health, UTM attribution health, and conversion-goal config into a single per-integration diagnostic with recommended actions. Read-only.

Required API key scopes

marketing_analytics:read

Query parameters

attribution_lookback_days
integer
Default: 7
include_conversion_goals
boolean
Default: true
source_type
string | null

Response

Example request

GET /api/projects/:project_id/marketing_analytics/diagnose
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/diagnose/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/diagnose/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 End-to-end marketing analytics diagnostic

RESPONSE
{
  "integrations": [
    {
      "integration_key": "string",
      "source_type": "string",
      "display_name": "string",
      "overall_status": "string",
      "diagnosis": "string",
      "data_source": {
        "source_type": "string",
        "is_native": true,
        "display_name": "string",
        "connected": true,
        "last_sync_at": "2019-08-24T14:15:22Z",
        "last_sync_status": "string",
        "last_error": "string",
        "rows_last_24h": 0,
        "rows_last_7d": 0,
        "sources_map_present": true,
        "schema_columns_mapped": [
          "string"
        ],
        "schema_columns_required_missing": [
          "string"
        ],
        "required_tables": [
          {
            "table_name": "string",
            "present": true,
            "should_sync": true,
            "status": "string",
            "last_synced_at": "2019-08-24T14:15:22Z"
          }
        ],
        "settings_url": "string",
        "schemas_url": "string",
        "diagnosis": "string",
        "fix_suggestion": "string"
      },
      "attribution": {
        "integration_key": "string",
        "display_name": "string",
        "events_with_utm_last_7d": 0,
        "events_matched_last_7d": 0,
        "events_unmatched_likely_yours_last_7d": 0,
        "last_event_with_matching_utm_at": "2019-08-24T14:15:22Z",
        "matched_pct": 0.1,
        "sample_unmatched_utm_sources": [
          {
            "raw_value": "string",
            "event_count": 0,
            "suggested_integration": "string"
          }
        ],
        "events_matched_paid_last_7d": 0,
        "events_matched_tagged_medium_last_7d": 0
      },
      "recommended_actions": [
        {
          "title": "string",
          "detail": "string",
          "severity": "string",
          "target_tool": "string"
        }
      ]
    }
  ],
  "overall_status": "string",
  "summary": "string",
  "conversion_goals": {
    "goals": [
      {
        "conversion_goal_id": "string",
        "name": "string",
        "kind": "EventsNode",
        "target_label": "string",
        "last_30d_count": 0,
        "integrated_count": 0,
        "events_without_utm_source": 0,
        "events_with_unmatched_utm_source": 0,
        "non_integrated_count": 0,
        "integrated_pct": 0,
        "is_misconfigured": true,
        "misconfig_reason": "string",
        "is_approximate": true,
        "approximation_reason": "string"
      }
    ],
    "attribution_window_days": 0,
    "attribution_mode": "string",
    "has_misconfigured": true
  },
  "recommended_actions": [
    {
      "title": "string",
      "detail": "string",
      "severity": "string",
      "target_tool": "string"
    }
  ]
}

Retrieve marketing analytics explain conversion goal

Break down a single conversion goal's events over a period by event name, utm_source, and matched integration, with a small sample of events. Read-only.

Required API key scopes

marketing_analytics:read

Query parameters

conversion_goal_id
string
date_from
string | null
date_to
string | null

Response

Example request

GET /api/projects/:project_id/marketing_analytics/explain_conversion_goal
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/explain_conversion_goal/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/explain_conversion_goal/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Per-event breakdown of a single conversion goal

RESPONSE
{
  "conversion_goal_id": "string",
  "goal_name": "string",
  "kind": "EventsNode",
  "period": {
    "date_from": "string",
    "date_to": "string"
  },
  "total_count": 0,
  "integrated_count": 0,
  "events_without_utm_source": 0,
  "events_with_unmatched_utm_source": 0,
  "non_integrated_count": 0,
  "by_event": [
    [
      "string",
      0
    ]
  ],
  "by_utm_source": [
    [
      "string",
      0
    ]
  ],
  "by_matched_integration": [
    [
      "string",
      0
    ]
  ],
  "samples": [
    {
      "event_uuid": "string",
      "timestamp": "2019-08-24T14:15:22Z",
      "distinct_id": "string",
      "utm_source": "string",
      "utm_campaign": "string",
      "matched_integration": "string"
    }
  ],
  "notes": [
    "string"
  ]
}

Retrieve marketing analytics setup plan

Rank everything wrong with a team's marketing analytics setup into concrete suggestions, each carrying the evidence behind it and — where one exists — an apply operation to pass straight to apply_setup_ops, plus a readiness block saying which capabilities (cost, ROAS, cost per customer, retention by channel) are unlocked and which suggestion is blocking each. Prefer this over diagnose when the question is 'what should I fix next': diagnose explains what is wrong, setup_plan says what to do about it in a form you can act on. Read-only.

Required API key scopes

marketing_analytics:read

Query parameters

date_from
string
Default: -30d
refresh
boolean
Default: false

Response

Example request

GET /api/projects/:project_id/marketing_analytics/setup_plan
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/setup_plan/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/setup_plan/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Ranked, machine-applicable setup suggestions plus per-capability readiness

RESPONSE
{
  "source_scanned_at": "string",
  "suggestions": [
    {
      "id": "string",
      "kind": "string",
      "source": "string",
      "severity": "string",
      "confidence": 0.1,
      "title": "string",
      "evidence": "string",
      "unlocks": [
        "string"
      ],
      "apply": null,
      "also_recommended": [
        null
      ],
      "safe_to_batch": true,
      "rank_score": 0.1,
      "integration": "string",
      "deep_link": "string",
      "docs_url": "string",
      "spend_at_risk": 0.1,
      "event_volume": 0
    }
  ],
  "readiness": [
    {
      "capability": "string",
      "status": "string",
      "explanation": "string",
      "blocked_by": [
        "string"
      ]
    }
  ],
  "degraded": [
    "string"
  ],
  "truncated": true,
  "summary": "string"
}

Status 404 Marketing Setup and new dashboard feature flags are both off

Retrieve marketing analytics source validation

Check connected marketing sources using the same validators as campaign queries. Read-only.

Required API key scopes

marketing_analytics:read

Response

Example request

GET /api/projects/:project_id/marketing_analytics/source_validation
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/source_validation/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/source_validation/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200

RESPONSE
{
  "errors_by_source": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Retrieve marketing analytics suggest conversion goals

Rank existing custom events as conversion-goal candidates by volume, UTM-tag coverage, and unique users, excluding system/autocaptured events. Read-only.

Required API key scopes

marketing_analytics:read

Query parameters

min_count
integer
Default: 50
top_n
integer
Default: 10

Response

Example request

GET /api/projects/:project_id/marketing_analytics/suggest_conversion_goals
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/suggest_conversion_goals/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/suggest_conversion_goals/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Ranked candidate events for conversion goals

RESPONSE
{
  "candidates": [
    {
      "event_name": "string",
      "last_30d_count": 0,
      "distinct_users_30d": 0,
      "pct_with_utm_source": 0.1,
      "pct_with_utm_campaign": 0.1,
      "top_utm_sources": [
        [
          "string",
          0
        ]
      ],
      "is_already_a_goal": true,
      "suggestion_score": 0.1,
      "suggestion_reason": "string"
    }
  ],
  "lookback_days": 0,
  "excluded_events_count": 0
}

Retrieve marketing analytics suggest utm mappings

Detect unmatched utm_source values from recent events and propose custom_source_mappings entries, alongside the full utm_source catalogue and current mappings. Read-only.

Required API key scopes

marketing_analytics:read

Query parameters

lookback_days
integer
Default: 90
min_event_count
integer
Default: 10

Response

Example request

GET /api/projects/:project_id/marketing_analytics/suggest_utm_mappings
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/suggest_utm_mappings/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/suggest_utm_mappings/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 Suggested utm_source → integration mappings

RESPONSE
{
  "source_suggestions": [
    {
      "raw_utm_source": "string",
      "suggested_target": "string",
      "suggested_target_display_name": "string",
      "reason": "string",
      "event_count_30d": 0
    }
  ],
  "campaign_suggestions": [
    {
      "integration": "string",
      "integration_display_name": "string",
      "suggested_clean_name": "string",
      "raw_campaign_values": [
        "string"
      ],
      "confidence": 0.1,
      "method": "string",
      "reason": "string",
      "event_count_30d": 0
    }
  ],
  "raw_unmatched_samples": [
    {
      "raw_utm_source": "string",
      "event_count": 0,
      "suggested_integration": "string"
    }
  ],
  "full_utm_source_catalogue": [
    {
      "raw_utm_source": "string",
      "event_count": 0,
      "matched_integration": "string",
      "matched_integration_display_name": "string",
      "suggested_integration": "string"
    }
  ],
  "current_mappings": [
    {
      "raw_utm_source": "string",
      "target": "string",
      "target_display_name": "string",
      "source": "string"
    }
  ],
  "total_unmatched_events_in_window": 0,
  "total_events_with_utm_in_window": 0,
  "lookback_days_used": 0,
  "notes": [
    "string"
  ]
}

Create marketing analytics test mapping

Example request

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

Example response

Status 200 No response body

Retrieve marketing analytics utm audit

Cross-reference campaigns with spend from ad platforms against pageview events with UTM parameters to identify tracking issues.

Required API key scopes

marketing_analytics:read

Query parameters

date_from
string
Default: -30d
date_to
string | null

Response

Example request

GET /api/projects/:project_id/marketing_analytics/utm_audit
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/marketing_analytics/utm_audit/
api_key = "[your personal api key]"
project_id = "[your project id]"
response = requests.get(
    "<ph_app_host>/api/projects/{project_id}/marketing_analytics/utm_audit/".format(
        project_id=project_id
    ),
    headers={"Authorization": "Bearer {}".format(api_key)},
).json()

Example response

Status 200 UTM audit results

RESPONSE
{
  "total_campaigns": 0,
  "campaigns_with_issues": 0,
  "campaigns_without_issues": 0,
  "total_spend_at_risk": 0.1,
  "results": [
    {
      "campaign_name": "string",
      "campaign_id": "string",
      "source_name": "string",
      "spend": 0.1,
      "clicks": 0,
      "impressions": 0,
      "has_utm_events": true,
      "event_count": 0,
      "issues": [
        {
          "field": "string",
          "severity": "error",
          "kind": "not_linked",
          "message": "string",
          "alternative_sources": [
            {
              "utm_source": "string",
              "event_count": 0
            }
          ],
          "shared_with_integrations": [
            "string"
          ],
          "missing_source_count": 0,
          "suggested_actions": [
            "fix_platform_urls"
          ],
          "mapping_candidate": "string"
        }
      ]
    }
  ],
  "all_utm_events": [
    {
      "utm_campaign": "string",
      "utm_source": "string",
      "event_count": 0,
      "campaign_match": "none",
      "source_match": "none",
      "matched_campaign": "string"
    }
  ]
}