Marketing

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

Endpoints

GET
GET
GET
GET
GET
GET
POST
GET

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/

Example response

Status 200 Configured conversion goals with last-30d performance
RESPONSE
{
  "goals": [
    {
      "id": "string",
      "name": "string",
      "kind": "string",
      "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
}

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
    stringnull

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/

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
    stringnull

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/

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"
          }
        ]
      },
      "recommended_actions": [
        {
          "title": "string",
          "detail": "string",
          "severity": "string",
          "target_tool": "string"
        }
      ]
    }
  ],
  "overall_status": "string",
  "summary": "string",
  "conversion_goals": {
    "goals": [
      {
        "id": "string",
        "name": "string",
        "kind": "string",
        "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

  • date_from
    stringnull
  • date_to
    stringnull
  • goal_id
    string

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/

Example response

Status 200 Per-event breakdown of a single conversion goal
RESPONSE
{
  "goal_id": "string",
  "goal_name": "string",
  "kind": "string",
  "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 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/

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/

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"
    }
  ],
  "campaign_suggestions": [
    {
      "integration": "string",
      "integration_display_name": "string",
      "suggested_clean_name": "string",
      "raw_campaign_values": [
        "string"
      ],
      "confidence": 0.1,
      "method": "string",
      "reason": "string"
    }
  ],
  "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/

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
    stringnull

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/

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",
          "message": "string"
        }
      ]
    }
  ],
  "all_utm_events": [
    {
      "utm_campaign": "string",
      "utm_source": "string",
      "event_count": 0,
      "campaign_match": "none",
      "source_match": "none",
      "matched_campaign": "string"
    }
  ]
}

Community questions