:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
from typing import Optional, cast
from products.warehouse_sources.sources.plausible._config import PlausibleSourceConfig
from products.warehouse_sources.sources.plausible.plausible import (
PlausibleResumeConfig,
hostname_of,
plausible_source,
validate_credentials as validate_plausible_credentials,
)
from products.warehouse_sources.sources.plausible.settings import (
ENDPOINTS,
custom_property_endpoint_name,
get_endpoint_config,
parse_custom_property_keys,
)
from products.warehouse_sources.sources.sdk import (
CanonicalDescriptions,
DataWarehouseSourceCategory,
ExternalDataSourceType,
FieldType,
ProductKey,
ReleaseStatus,
ResumableSource,
ResumableSourceManager,
SourceConfig,
SourceFieldInputConfig,
SourceFieldInputConfigType,
SourceInputs,
SourceRegistry,
SourceResponse,
SourceSchema,
ValidateDatabaseHostMixin,
detect,
)
@SourceRegistry.register
class PlausibleSource(ResumableSource[PlausibleSourceConfig, PlausibleResumeConfig], ValidateDatabaseHostMixin):
codebase_detection = detect(
env=("^PLAUSIBLE_", "^NUXT_PUBLIC_PLAUSIBLE_"),
script_hosts=("plausible.io",),
npm=(
"plausible-tracker",
"@plausible-analytics/tracker",
"next-plausible",
"@nuxtjs/plausible",
"vue-plausible",
"v-plausible",
"gatsby-plugin-plausible",
"vuepress-plugin-plausible",
"gridsome-plugin-plausible-analytics",
),
pypi=("django-plausible", "django-plausible-proxy", "sphinx-plausible"),
composer=("vincentbean/laravel-plausible", "njoguamos/laravel-plausible"),
go=("github.com/andrerfcsantos/go-plausible",),
hex=("plausible",),
pub=("plausible_analytics", "plausible"),
rubygems=("plausible_api", "bridgetown-plausible"),
swiftpm=("github.com/nickoneill/plausibleswift", "github.com/brightdigit/aviaryinsights"),
alternative_to=(ProductKey.WEB_ANALYTICS,),
)
supported_versions = ("v2",)
default_version = "v2"
api_docs_url = "https://plausible.io/docs/stats-api"
@property
def source_type(self) -> ExternalDataSourceType:
return ExternalDataSourceType.PLAUSIBLE
@property
def connection_host_fields(self) -> list[str]:
# `host` determines where the stored API key is sent; retargeting it must re-require the key.
return ["host"]
def get_non_retryable_errors(self) -> dict[str, str | None]:
return {
"401 Client Error": "Your Plausible API key is invalid or has been revoked. Create a new key in your Plausible account settings, then reconnect.",
"403 Client Error": "Your Plausible API key is missing the stats read scope needed to sync this data. Grant it in your Plausible account settings, then reconnect.",
# Plausible answers 402 when the site's subscription has lapsed or its plan doesn't
# include the stats API. The billing state is fixed until the customer changes it, so
# every retry replays the same rejection. Match the status text, not the self-hosted URL.
"402 Client Error": "Your Plausible plan doesn't include API access, or its subscription has lapsed. Update the subscription in your Plausible account, then reconnect.",
# Plausible rejects the query as malformed for this site (a permanent 400 — auth and
# missing-site cases are 401/403/404 and handled above). Retrying resends the same
# request, so stop. Match the status text, not the self-hosted URL, which varies.
"400 Client Error": "Plausible rejected the request for this site. Check that the site domain is correct and that your Plausible account can access its stats, then reconnect.",
# `is_database_host_valid` raises this when the self-hosted Host doesn't resolve via
# DNS — a hostname the customer typed wrong or one that's no longer publicly reachable.
# Deterministic and permanent until the Host is corrected, so stop retrying. Match the
# stable prefix, not the customer's hostname that follows it.
"Couldn't resolve the host": "The Plausible host could not be resolved via DNS. Check that it's spelled correctly and reachable from the public internet, then reconnect.",
}
@property
def get_source_config(self) -> SourceConfig:
return SourceConfig(
name=ExternalDataSourceType.PLAUSIBLE,
category=DataWarehouseSourceCategory.ANALYTICS,
label="Plausible",
caption="""Connect Plausible Analytics to pull your web analytics into the PostHog Data warehouse.
Works with Plausible Cloud and self-hosted instances. Create an API key under **Account settings → API keys** with the `stats read` scope, then enter your site's domain (e.g. `example.com`). Leave the host blank for Plausible Cloud, or set it to your instance URL for self-hosted (e.g. `https://plausible.example.com`).""",
iconPath="/static/services/plausible.png",
docsUrl="https://posthog.com/docs/cdp/sources/plausible",
releaseStatus=ReleaseStatus.GA,
fields=cast(
list[FieldType],
[
SourceFieldInputConfig(
name="api_key",
label="API key",
type=SourceFieldInputConfigType.PASSWORD,
required=True,
placeholder="",
secret=True,
),
SourceFieldInputConfig(
name="site_id",
label="Site domain",
type=SourceFieldInputConfigType.TEXT,
required=True,
placeholder="example.com",
secret=False,
),
SourceFieldInputConfig(
name="host",
label="Host (self-hosted only)",
type=SourceFieldInputConfigType.TEXT,
required=False,
placeholder="https://plausible.io",
secret=False,
),
SourceFieldInputConfig(
name="custom_property_keys",
sync_setting=True,
label="Custom property keys",
caption="Optional. A comma-separated list of the custom properties to sync, for example `plan, signup_method`. Each property syncs as its own table. Your Plausible plan needs to include custom properties.",
type=SourceFieldInputConfigType.TEXT,
required=False,
placeholder="plan, signup_method",
secret=False,
),
],
),
)
def get_canonical_descriptions(self) -> CanonicalDescriptions:
from products.warehouse_sources.sources.plausible.canonical_descriptions import CANONICAL_DESCRIPTIONS
return CANONICAL_DESCRIPTIONS
def get_schemas(
self,
config: PlausibleSourceConfig,
team_id: int,
with_counts: bool = False,
names: list[str] | None = None,
force_refresh: bool = False,
api_version: str | None = None,
) -> list[SourceSchema]:
def _build_schema(endpoint: str) -> SourceSchema:
endpoint_config = get_endpoint_config(endpoint)
return SourceSchema(
name=endpoint,
# date_range is a genuine server-side filter, so every report supports incremental
# syncing by sliding the window forward.
supports_incremental=True,
supports_append=True,
incremental_fields=endpoint_config.incremental_fields,
should_sync_default=endpoint_config.should_sync_default,
)
custom_property_endpoints = [
custom_property_endpoint_name(key) for key in parse_custom_property_keys(config.custom_property_keys)
]
schemas = [_build_schema(endpoint) for endpoint in [*ENDPOINTS, *custom_property_endpoints]]
if names is not None:
names_set = set(names)
schemas = [s for s in schemas if s.name in names_set]
return schemas
def validate_credentials(
self,
config: PlausibleSourceConfig,
team_id: int,
schema_name: Optional[str] = None,
api_version: str | None = None,
) -> tuple[bool, str | None]:
try:
host_valid, host_error = self.is_database_host_valid(hostname_of(config.host), team_id)
except ValueError:
return False, "Invalid Plausible host URL"
if not host_valid:
return False, host_error
return validate_plausible_credentials(config.host, config.site_id, config.api_key)
def get_resumable_source_manager(self, inputs: SourceInputs) -> ResumableSourceManager[PlausibleResumeConfig]:
return ResumableSourceManager[PlausibleResumeConfig](inputs, PlausibleResumeConfig)
def source_for_pipeline(
self,
config: PlausibleSourceConfig,
resumable_source_manager: ResumableSourceManager[PlausibleResumeConfig],
inputs: SourceInputs,
) -> SourceResponse:
host_valid, host_error = self.is_database_host_valid(hostname_of(config.host), inputs.team_id)
if not host_valid:
raise ValueError(host_error or "Invalid Plausible host")
return plausible_source(
host=config.host,
site_id=config.site_id,
api_key=config.api_key,
endpoint=inputs.schema_name,
team_id=inputs.team_id,
job_id=inputs.job_id,
resumable_source_manager=resumable_source_manager,
should_use_incremental_field=inputs.should_use_incremental_field,
db_incremental_field_last_value=inputs.db_incremental_field_last_value
if inputs.should_use_incremental_field
else None,
)