Workspace¶

The Workspace class is the unified entry point for all Mixpanel data operations.

Explore on DeepWiki

🤖 Workspace Class Deep Dive →

Ask questions about Workspace methods, explore usage patterns, or understand how services are orchestrated.

Overview¶

Workspace orchestrates internal services and provides direct App API access:

DiscoveryService — Schema exploration (events, properties, funnels, cohorts)
LiveQueryService — Real-time analytics queries (legacy) and Insights engine queries
Streaming — Stream events and profiles directly from Mixpanel
Entity CRUD — Create, read, update, delete dashboards, reports, and cohorts via Mixpanel App API (workspace-scoped)
Feature Management — Create, read, update, delete feature flags and experiments via Mixpanel App API (project-scoped)
Operational Tooling — Manage alerts, annotations, and webhooks via Mixpanel App API (workspace-scoped)
Data Governance — Manage Lexicon definitions, drop filters, custom properties, custom events, lookup tables, schema registry, schema enforcement, data auditing, volume anomalies, and event deletion requests via Mixpanel App API (workspace-scoped)
Saved Metrics & Behaviors — List, read, create, update, and delete saved metrics (behavior metrics, formulas, warehouse metrics) and saved behaviors via Mixpanel App API (project-scoped)
Business Context — Read and write the markdown documentation that grounds AI assistants (org and project scopes, 50,000-char cap)
Session Replay — Discover, sign, fetch, and analyze rrweb session recordings; project them into session-level DataFrames and an LLM-friendly action timeline

Key Features¶

Entity CRUD¶

Manage dashboards, reports (bookmarks), and cohorts programmatically via the Mixpanel App API (workspace-scoped):

import mixpanel_headless as mp

ws = mp.Workspace()

# Dashboards
dashboards = ws.list_dashboards()
new_dash = ws.create_dashboard(mp.CreateDashboardParams(title="Q1 Metrics"))
ws.update_dashboard(new_dash.id, mp.UpdateDashboardParams(title="Q1 Metrics v2"))
ws.favorite_dashboard(new_dash.id)

# Reports (Bookmarks)
reports = ws.list_bookmarks_v2()
report = ws.create_bookmark(mp.CreateBookmarkParams(
    name="Daily Signups",
    bookmark_type="insights"
))

# Cohorts
cohorts = ws.list_cohorts_full()
cohort = ws.create_cohort(mp.CreateCohortParams(name="Power Users"))
ws.update_cohort(cohort.id, mp.UpdateCohortParams(name="Super Users"))

Dashboard, report, and cohort operations require a workspace ID, set via MP_WORKSPACE_ID environment variable, --workspace / -w CLI flag, Workspace(workspace=N), or ws.use(workspace=N). List available workspaces with mp workspace list or ws.workspaces().

Feature Flags & Experiments¶

Manage feature flags and experiments programmatically. Unlike dashboards/reports/cohorts, these are project-scoped and do not require a workspace ID.

import mixpanel_headless as mp

ws = mp.Workspace()

# Feature Flags
flags = ws.list_feature_flags()
flag = ws.create_feature_flag(mp.CreateFeatureFlagParams(
    name="Dark Mode", key="dark_mode"
))
ws.update_feature_flag(flag.id, mp.UpdateFeatureFlagParams(
    name="Dark Mode", key="dark_mode",
    status=mp.FeatureFlagStatus.ENABLED,
    ruleset=flag.ruleset,
))

# Experiments (full lifecycle)
exp = ws.create_experiment(mp.CreateExperimentParams(name="Checkout Flow Test"))
launched = ws.launch_experiment(exp.id)
concluded = ws.conclude_experiment(exp.id)
decided = ws.decide_experiment(exp.id, mp.ExperimentDecideParams(success=True))

Feature flag update uses PUT semantics (all required fields must be provided). Experiment update uses PATCH semantics (only changed fields needed). See the Entity Management guide for complete coverage.

Data Governance¶

Manage Lexicon definitions, drop filters, custom properties, custom events, and lookup tables programmatically. All operations are workspace-scoped.

import mixpanel_headless as mp

ws = mp.Workspace()

# Lexicon — Event and property definitions
defs = ws.get_event_definitions(names=["Signup", "Login"])
ws.update_event_definition("Signup", mp.UpdateEventDefinitionParams(verified=True))
tags = ws.list_lexicon_tags()

# Drop filters
filters = ws.list_drop_filters()
ws.create_drop_filter(mp.CreateDropFilterParams(
    event_name="Debug Event", filters={"property": "env", "value": "test"},
))

# Custom properties
props = ws.list_custom_properties()
prop = ws.get_custom_property("abc123")

# Lookup tables
tables = ws.list_lookup_tables()
table = ws.upload_lookup_table(mp.UploadLookupTableParams(
    name="Countries", file_path="/path/to/countries.csv",
))

# Custom events
events = ws.list_custom_events()

See the Data Governance guide for complete coverage.

Saved Metrics & Behaviors¶

List, read, create, update, and delete the saved metrics and saved behaviors of the project. Both collections are project-scoped and do not require a workspace ID. One collection holds all three metric kinds (metric, formula, warehouse).

import mixpanel_headless as mp

ws = mp.Workspace()

# Saved metrics: the full server list, then local filters
metrics = ws.list_metrics()
governed = ws.list_metrics(verified=True, viewable_only=True)
metric = ws.get_metric(104700)
metric.math, metric.formula_expression, metric.referenced_metric_ids

# Create and update; the client checks each write before the request
saved = ws.create_metric(mp.CreateMetricParams(
    name="Weekly buyers", definition=mp.Metric("Purchase", math="unique"), verified=True,
))
ws.update_metric(saved.id, mp.UpdateMetricParams(display=mp.MetricDisplay(precision=0)))

# Saved behaviors
funnels = ws.list_behaviors(behavior_type="funnel")

# Deletes go through the bulk routes; the single-id forms read first
ws.delete_metric(104700)
ws.delete_behaviors([3001, 3002])

The list includes metrics that the caller cannot view (can_view is False). See the Saved Metrics and Behaviors guide for complete coverage.

Business Context¶

Read and write the markdown documentation that grounds AI assistants. Two scopes (level="organization" shared across the org, level="project" per-project), 50,000-character cap enforced client-side before any HTTP call.

import mixpanel_headless as mp

ws = mp.Workspace()

# Read
project_ctx = ws.get_business_context(level="project")
org_ctx = ws.get_business_context(level="organization")     # auto-resolves org_id

# Read both in one round-trip
chain = ws.get_business_context_chain()

# Write (full-replace; pass "" to clear)
ws.set_business_context("# About Acme\n…", level="project")
ws.clear_business_context(level="organization")

Project-scope writes require edit_project_info permission; org-scope writes require edit_project_info at the org level. See the Business Context guide for full coverage of input modes, error handling, and cross-project audit patterns.

workspaces() vs list_workspaces()

Both methods are exposed. workspaces() (recommended) returns list[WorkspaceRef] from the cached /me response — fast, typed, and consistent with events() / properties() / funnels() / cohorts(). list_workspaces() is a lower-level escape hatch that calls GET /api/app/projects/{pid}/workspaces/public directly and returns list[PublicWorkspace].

Session Replay¶

Discover a user's rrweb session recordings, fetch the raw event stream from the signed CDN, and project them into analysis-ready DataFrames. The methods: list_replays, events_for_replay / events_for_replays, sign_replay / sign_replays, fetch_replay / fetch_replays, stream_replay, replays_for_user, and analyze_replay.

import mixpanel_headless as mp

ws = mp.Workspace()

# Discovery + fetch + Mixpanel-event join in one call → a ReplayBundle
bundle = ws.replays_for_user("user-42", from_date="2025-01-01", to_date="2025-01-31")
print(bundle.sessions_df)                   # one row per session: duration, n_clicks, n_errors
print(bundle.top_clicks(10))                # most-clicked elements (focus interactions excluded)
print(bundle.replays[0].summary_markdown)   # LLM-friendly action timeline

# Single replay, with the raw rrweb stream for the JS player
replay = ws.fetch_replay("0190ebde-d50d-71b1-804c-ec1b4a533ef9")
player_json = replay.to_rrweb_player_json()

Signed CDN URLs are bearer credentials: SignedReplay masks them in repr / str and the library never logs them. A SESSION_RECORDING_SENSITIVE_DATA 403 raises SessionReplayAccessError. See the Session Replay guide for the full surface, the mp replays CLI, and the DataFrame schemas.

Report Links¶

Share a headless query as a Mixpanel URL, or turn a URL back into runnable params. The methods: create_report_link, resolve_report_link, query_report_link, and saved_report_link.

import mixpanel_headless as mp

ws = mp.Workspace()

# Query → shareable URL (one App API POST; the slug record is stored server-side)
result = ws.query(mp.Metric("Login", math="total"), last=7)
link = ws.create_report_link(result, name="Logins, last 7 days")
print(link.url)      # https://mixpanel.com/project/3/view/75/app/insights#EBrV5bW2u9Mw

# URL / slug / shortlink → raw params → typed result
r = ws.resolve_report_link("https://mixpanel.com/s/AbC123")
r.report_type, r.params
df = ws.query_report_link(r).df

# Saved report → URL, no network call
ws.saved_report_link(123, report_type="funnels")

Region mismatches raise ReportLinkScopeMismatchError before any HTTP call. Project and pinned-workspace mismatches raise it before the record fetch; for a shortlink that is after the one redirect GET. Legacy ~(...) hashes and board links raise UnsupportedReportLinkError with a hint. See the Report Links guide for the mp reports link / mp reports resolve CLI and the --link flags.

In-Session Switching¶

Workspace.use() swaps the active account, project, workspace, or target without rebuilding the underlying httpx.Client or per-account /me cache. It returns self for fluent chaining, so cross-project iteration is O(1) per swap.

import mixpanel_headless as mp

ws = mp.Workspace()
ws.use(account="team")                              # implicitly clears workspace
ws.use(project="3018488")
ws.use(workspace=3448414)
ws.use(target="ecom")                               # apply all three at once

# Persist the new state
ws.use(project="3018488", persist=True)             # writes [active]

# Read the resolved state
print(ws.account.name, ws.project.id, ws.workspace.id if ws.workspace else None)
print(ws.session)                                   # full Session snapshot

See Auth → Workspace.use() for the resolution semantics and parallel-snapshot patterns.

Class Reference¶

mixpanel_headless.Workspace ¶

Workspace(
    *,
    account: str | None = None,
    project: str | None = None,
    workspace: int | None = None,
    target: str | None = None,
    session: Session | None = None,
    _api_client: MixpanelAPIClient | None = None,
)

Unified entry point for Mixpanel data operations.

The Workspace class is a facade that orchestrates: - DiscoveryService for schema exploration - LiveQueryService for real-time analytics - App API client for CRUD and data governance operations

Examples:

Basic usage with credentials from config:

ws = Workspace()
events = ws.events()  # discover schema
result = ws.segmentation(event="login", from_date="2024-01-01", to_date="2024-01-31")
ws.close()

Stream events for external processing:

ws = Workspace()
for event in ws.stream_events(from_date="2024-01-01", to_date="2024-01-31"):
    process(event)
ws.close()

Create a new Workspace bound to a resolved :class:Session.

Resolution priority follows FR-017: env vars > kwargs > target > bridge > [active] > Account.default_project. Pass session= to bypass the resolver and use a pre-built :class:Session directly.

PARAMETER	DESCRIPTION
`account`	Named account from `~/.mp/config.toml`. TYPE: `str \| None` DEFAULT: `None`
`project`	Project ID override (digit string). TYPE: `str \| None` DEFAULT: `None`
`workspace`	Workspace ID override (positive int). TYPE: `int \| None` DEFAULT: `None`
`target`	Apply all three axes from `[targets.NAME]`. Mutually exclusive with `account`/`project`/`workspace`. TYPE: `str \| None` DEFAULT: `None`
`session`	Pre-built :class:`Session` (full resolver bypass). TYPE: `Session \| None` DEFAULT: `None`
`_api_client`	Injected :class:`MixpanelAPIClient` for testing. TYPE: `MixpanelAPIClient \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`ParamValidationError`	`target=` combined with any axis kwarg (`WS1_TARGET_MUTUALLY_EXCLUSIVE`).
`ConfigError`	Account or project axis cannot be resolved.
`OAuthError`	Auth header construction fails.

Source code in src/mixpanel_headless/workspace.py

def __init__(
    self,
    *,
    account: str | None = None,
    project: str | None = None,
    workspace: int | None = None,
    target: str | None = None,
    session: _Session | None = None,
    _api_client: MixpanelAPIClient | None = None,
) -> None:
    """Create a new Workspace bound to a resolved :class:`Session`.

    Resolution priority follows FR-017: env vars > kwargs > target >
    bridge > ``[active]`` > ``Account.default_project``. Pass
    ``session=`` to bypass the resolver and use a pre-built
    :class:`Session` directly.

    Args:
        account: Named account from ``~/.mp/config.toml``.
        project: Project ID override (digit string).
        workspace: Workspace ID override (positive int).
        target: Apply all three axes from ``[targets.NAME]``. Mutually
            exclusive with ``account``/``project``/``workspace``.
        session: Pre-built :class:`Session` (full resolver bypass).
        _api_client: Injected :class:`MixpanelAPIClient` for testing.

    Raises:
        ParamValidationError: ``target=`` combined with any axis kwarg
            (``WS1_TARGET_MUTUALLY_EXCLUSIVE``).
        ConfigError: Account or project axis cannot be resolved.
        OAuthError: Auth header construction fails.
    """
    if target is not None and (
        account is not None or project is not None or workspace is not None
    ):
        raise ParamValidationError(
            "`target=` is mutually exclusive with "
            "`account=`/`project=`/`workspace=`.",
            code="WS1_TARGET_MUTUALLY_EXCLUSIVE",
        )

    self._discovery: DiscoveryService | None = None
    self._live_query: LiveQueryService | None = None
    self._me_service: MeService | None = None
    # 044-session-replay: lazy ReplaysService, created on first replay-method
    # access so non-replay sessions never pay for the import or async client.
    self._replays_svc: ReplaysService | None = None

    if session is not None:
        sess = session
    else:
        from mixpanel_headless._internal.auth.bridge import load_bridge

        br = load_bridge()
        # If the bridge has oauth_browser tokens embedded, materialize them
        # to the per-account on-disk path so the OnDiskTokenResolver can
        # serve them downstream. This is the Cowork credential-courier
        # contract: the bridge is the source of truth at startup.
        if (
            br is not None
            and br.tokens is not None
            and br.account.type == "oauth_browser"
        ):
            from mixpanel_headless._internal.auth.storage import (
                ensure_account_dir,
            )
            from mixpanel_headless._internal.auth.token import token_payload_bytes
            from mixpanel_headless._internal.io_utils import atomic_write_bytes

            tokens_path = ensure_account_dir(br.account.name) / "tokens.json"
            # Always overwrite — the bridge is the authoritative
            # source of truth at startup, so a refreshed payload from
            # the host must replace any stale on-disk cache here.
            # ``OAuthTokens.expires_at`` is always set (required, tz-aware
            # per Fix 25) — no fall-through to None which would trip the
            # OnDiskTokenResolver expiry check. Empty scopes from the
            # bridge get a ``"read"`` default so the cached file matches
            # what `mp account login` would have written.
            tokens_to_persist = br.tokens
            if not tokens_to_persist.scope:
                tokens_to_persist = tokens_to_persist.model_copy(
                    update={"scope": "read"}
                )
            # atomic_write_bytes creates the file with 0o600 via O_EXCL
            # before any data is written, eliminating the umask-derived
            # permission window left open by write_text + chmod.
            atomic_write_bytes(tokens_path, token_payload_bytes(tokens_to_persist))
        sess = _resolve_session(
            account=account,
            project=project,
            workspace=workspace,
            target=target,
            config=ConfigManager(),
            bridge=br,
        )
    self._session = sess
    self._account_name: str = sess.account.name
    self._initial_workspace_id = sess.workspace.id if sess.workspace else None
    if _api_client is not None:
        self._api_client: MixpanelAPIClient | None = _api_client
    else:
        self._api_client = MixpanelAPIClient(session=sess)
    self._install_workspace_resolver()

account `property` ¶

account: Account

Return the resolved :class:Account for the current session.

project `property` ¶

project: Project

Return the resolved :class:Project for the current session.

workspace `property` ¶

workspace: WorkspaceRef | None

Return the resolved :class:WorkspaceRef (or None for lazy).

session `property` ¶

session: Session

Return the bound :class:Session.

api `property` ¶

api: MixpanelAPIClient

Direct access to the Mixpanel API client.

Use this escape hatch for Mixpanel API operations not covered by the Workspace class. The client handles authentication automatically.

The client provides

request(method, url, **kwargs): Make authenticated requests to any Mixpanel API endpoint.
project_id: The configured project ID for constructing URLs.
region: The configured region ('us', 'eu', or 'in').

RETURNS	DESCRIPTION
`MixpanelAPIClient`	The underlying MixpanelAPIClient.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Example

Fetch event schema from the Lexicon Schemas API::

import mixpanel_headless as mp
from urllib.parse import quote

ws = mp.Workspace()
client = ws.api

# Build the URL with proper encoding
event_name = quote("Added To Cart", safe="")
url = f"https://mixpanel.com/api/app/projects/{client.project_id}/schemas/event/{event_name}"

# Make the authenticated request
schema = client.request("GET", url)
print(schema)

close ¶

close() -> None

Close all resources (HTTP client).

This method is idempotent and safe to call multiple times.

Source code in src/mixpanel_headless/workspace.py

def close(self) -> None:
    """Close all resources (HTTP client).

    This method is idempotent and safe to call multiple times.
    """
    # Close API client if we created one
    if self._api_client is not None:
        self._api_client.close()
        self._api_client = None

use ¶

use(
    *,
    account: str | None = None,
    project: str | None = None,
    workspace: int | None = None,
    target: str | None = None,
    persist: bool = False,
) -> Workspace

Swap one or more session axes in place; return self for chaining.

target= is mutually exclusive with account=/project=/ workspace=. The HTTP transport is preserved across all switches (per Research R5).

use(workspace=<workspace_id>) explicitly pins the workspace: subsequent Query API and discovery calls carry that workspace ID as the workspace_id parameter so Mixpanel data view filters apply, and App API calls scope via /workspaces/{workspace_id}/... paths. Raw export streaming (stream_events() / stream_profiles()) remains project-scoped by design. Swapping the account or project axis clears the pin (unless a new workspace is supplied), and the lazy discovery service — including its result cache — is rebuilt on every switch.

When account= is supplied, the project axis re-resolves through the FR-017 chain ending at the new account's default_project (env MP_PROJECT_ID > explicit project= > new account's default_project). If no source provides a project, the call raises :class:ConfigError per FR-033 — the prior session's project is NEVER carried forward across an account swap because cross-account project access is not guaranteed. The workspace axis is cleared on account swap (workspaces are project-scoped; the prior workspace doesn't apply to the new project) — explicit workspace= or MP_WORKSPACE_ID env override is honored.

PARAMETER	DESCRIPTION
`account`	Replacement account name. TYPE: `str \| None` DEFAULT: `None`
`project`	Replacement project ID. TYPE: `str \| None` DEFAULT: `None`
`workspace`	Replacement workspace ID. TYPE: `int \| None` DEFAULT: `None`
`target`	Apply this target's three axes atomically. TYPE: `str \| None` DEFAULT: `None`
`persist`	When `True`, also write the new state to `[active]`. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Workspace`	`self` for fluent chaining.

RAISES	DESCRIPTION
`ParamValidationError`	Mutually exclusive args (`WS1_TARGET_MUTUALLY_EXCLUSIVE`).
`ValueError`	Referenced name missing.
`OAuthError`	New auth header construction fails (atomic on success).
`ConfigError`	`account=` swap cannot resolve a project axis.

Source code in src/mixpanel_headless/workspace.py

def use(
    self,
    *,
    account: str | None = None,
    project: str | None = None,
    workspace: int | None = None,
    target: str | None = None,
    persist: bool = False,
) -> Workspace:
    """Swap one or more session axes in place; return ``self`` for chaining.

    ``target=`` is mutually exclusive with ``account=``/``project=``/
    ``workspace=``. The HTTP transport is preserved across all switches
    (per Research R5).

    ``use(workspace=<workspace_id>)`` explicitly pins the workspace:
    subsequent Query API and discovery calls carry that workspace ID as
    the ``workspace_id`` parameter so Mixpanel data view filters apply,
    and App API calls scope via ``/workspaces/{workspace_id}/...``
    paths. Raw export streaming
    (``stream_events()`` / ``stream_profiles()``) remains project-scoped
    by design. Swapping the account or project axis clears the pin
    (unless a new workspace is supplied), and the lazy discovery service
    — including its result cache — is rebuilt on every switch.

    When ``account=`` is supplied, the project axis re-resolves through
    the FR-017 chain ending at the new account's ``default_project``
    (env ``MP_PROJECT_ID`` > explicit ``project=`` > new account's
    ``default_project``). If no source provides a project, the call
    raises :class:`ConfigError` per FR-033 — the prior session's
    project is NEVER carried forward across an account swap because
    cross-account project access is not guaranteed. The workspace
    axis is cleared on account swap (workspaces are project-scoped;
    the prior workspace doesn't apply to the new project) — explicit
    ``workspace=`` or ``MP_WORKSPACE_ID`` env override is honored.

    Args:
        account: Replacement account name.
        project: Replacement project ID.
        workspace: Replacement workspace ID.
        target: Apply this target's three axes atomically.
        persist: When ``True``, also write the new state to ``[active]``.

    Returns:
        ``self`` for fluent chaining.

    Raises:
        ParamValidationError: Mutually exclusive args
            (``WS1_TARGET_MUTUALLY_EXCLUSIVE``).
        ValueError: Referenced name missing.
        OAuthError: New auth header construction fails (atomic on success).
        ConfigError: ``account=`` swap cannot resolve a project axis.
    """
    if target is not None and (
        account is not None or project is not None or workspace is not None
    ):
        raise ParamValidationError(
            "`target=` is mutually exclusive with `account=`/`project=`/`workspace=`.",
            code="WS1_TARGET_MUTUALLY_EXCLUSIVE",
        )

    cm = ConfigManager()
    client = self._require_api_client()
    new_account_obj: _AccountUnion | None = None
    new_project_obj: _Project | None = None
    new_workspace_obj: _WorkspaceRef | None = None
    if target is not None:
        # Route through the same resolver as Workspace() construction so
        # env > param > target > bridge > config ordering applies (FR-017).
        # Without this, mid-process env-var overrides would be honored at
        # construction but silently ignored on `ws.use(target=...)`.
        sess = _resolve_session(
            target=target,
            config=cm,
            bridge=_load_bridge(),
        )
        new_account_obj = sess.account
        new_project_obj = sess.project
        new_workspace_obj = sess.workspace
    elif account is not None:
        # Explicit account swap: the user told us which account to use,
        # so the env-vars-override-param rule (FR-017) on the account
        # axis doesn't apply here — load the requested account directly.
        # Project re-resolves through the FR-017 chain ending at the
        # NEW account's default_project (env > explicit > new account's
        # default); raises ConfigError if nothing resolves (per FR-033,
        # cross-account project access is not guaranteed).
        # Workspace is cleared (workspaces are project-scoped; the
        # prior workspace is meaningless under the new account/project)
        # — explicit `workspace=` overrides the clear, and env override
        # via MP_WORKSPACE_ID still applies for parity with FR-017.
        new_account_obj = cm.get_account(account)
        br = _load_bridge()
        project_id = _resolve_project_axis(
            explicit=project,
            target_project=None,
            bridge=br,
            account=new_account_obj,
        )
        if project_id is None:
            raise ConfigError(_format_no_project_error(new_account_obj))
        new_project_obj = _Project(id=project_id)
        # Account-swap intentionally clears workspace per FR-033 (workspaces
        # are project-scoped; the prior workspace doesn't apply to the new
        # project). Only an explicit ``workspace=`` kwarg or a validated
        # ``MP_WORKSPACE_ID`` env var can populate it. We bypass
        # ``resolve_workspace_axis`` because that consults ``[active].workspace``
        # — which is exactly the fallback we need to skip here.
        if workspace is not None:
            new_workspace_obj = _WorkspaceRef(id=workspace)
        else:
            env_ws = _env_workspace_id()
            new_workspace_obj = (
                _WorkspaceRef(id=env_ws) if env_ws is not None else None
            )
    else:
        new_project_obj = _Project(id=project) if project is not None else None
        new_workspace_obj = (
            _WorkspaceRef(id=workspace) if workspace is not None else None
        )
    client.use(
        account=new_account_obj,
        project=new_project_obj,
        workspace=new_workspace_obj,
    )
    self._session = client.session

    # Clear lazy services so subsequent reads of `project` / `account` /
    # `workspaces()` / `_me_svc` observe the new session rather than the
    # prior one.
    self._account_name = self._session.account.name
    self._initial_workspace_id = (
        self._session.workspace.id if self._session.workspace else None
    )
    self._discovery = None
    self._live_query = None
    self._me_service = None
    self._replays_svc = None

    if persist:
        self._persist_active()
    return self

me ¶

me(*, force_refresh: bool = False) -> Any

Get /me response for current credentials (cached 24h).

Returns the authenticated user's profile including all accessible organizations, projects, and workspaces.

PARAMETER	DESCRIPTION
`force_refresh`	If True, bypass cache and call the API. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`Any`	MeResponse with user profile, projects, and workspaces.

RAISES	DESCRIPTION
`ConfigError`	If credentials lack /me access (401 or 403).
`QueryError`	If the API returns a non-403 error.

Example

ws = Workspace()
me = ws.me()
print(me.user_email)
for pid, proj in me.projects.items():
    print(f"  {pid}: {proj.name}")

Source code in src/mixpanel_headless/workspace.py

def me(self, *, force_refresh: bool = False) -> Any:
    """Get /me response for current credentials (cached 24h).

    Returns the authenticated user's profile including all accessible
    organizations, projects, and workspaces.

    Args:
        force_refresh: If True, bypass cache and call the API.

    Returns:
        MeResponse with user profile, projects, and workspaces.

    Raises:
        ConfigError: If credentials lack /me access (401 or 403).
        QueryError: If the API returns a non-403 error.

    Example:
        ```python
        ws = Workspace()
        me = ws.me()
        print(me.user_email)
        for pid, proj in me.projects.items():
            print(f"  {pid}: {proj.name}")
        ```
    """
    return self._me_svc.fetch(force_refresh=force_refresh)

projects ¶

projects(*, refresh: bool = False) -> list[_Project]

List all accessible projects via the /me API (FR-035).

Returns projects from the cached /me response, sorted by name. Each entry is a v3 :class:Project (id + name + organization_id + timezone), built from the underlying MeProjectInfo payload — callers iterate for project in ws.projects(): ws.use(project=project.id) per the documented cross-project iteration pattern.

Replaces the deprecated discover_projects() (which returned list[tuple[str, MeProjectInfo]]) — for the raw /me shape with extra fields (has_workspaces, domain, type, ...), call self._me_svc.list_projects() directly from internal code.

PARAMETER	DESCRIPTION
`refresh`	When True, bypass the on-disk and in-memory `/me` caches and refetch from the API. Default False uses the 24h cache. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`list[Project]`	List of :class:`Project` records sorted by name.

RAISES	DESCRIPTION
`ConfigError`	If credentials lack /me access.

Example

ws = Workspace()
for project in ws.projects():
    ws.use(project=project.id)
    print(project.id, project.name, len(ws.events()))

Source code in src/mixpanel_headless/workspace.py

def projects(self, *, refresh: bool = False) -> list[_Project]:
    """List all accessible projects via the /me API (FR-035).

    Returns projects from the cached /me response, sorted by name. Each
    entry is a v3 :class:`Project` (id + name + organization_id +
    timezone), built from the underlying ``MeProjectInfo`` payload —
    callers iterate ``for project in ws.projects(): ws.use(project=project.id)``
    per the documented cross-project iteration pattern.

    Replaces the deprecated ``discover_projects()`` (which returned
    ``list[tuple[str, MeProjectInfo]]``) — for the raw ``/me`` shape
    with extra fields (``has_workspaces``, ``domain``, ``type``, ...),
    call ``self._me_svc.list_projects()`` directly from internal code.

    Args:
        refresh: When True, bypass the on-disk and in-memory ``/me``
            caches and refetch from the API. Default False uses the
            24h cache.

    Returns:
        List of :class:`Project` records sorted by name.

    Raises:
        ConfigError: If credentials lack /me access.

    Example:
        ```python
        ws = Workspace()
        for project in ws.projects():
            ws.use(project=project.id)
            print(project.id, project.name, len(ws.events()))
        ```
    """
    if refresh:
        self._me_svc.fetch(force_refresh=True)
    return [
        _Project(
            id=pid,
            name=info.name,
            organization_id=info.organization_id,
            timezone=info.timezone,
        )
        for pid, info in self._me_svc.list_projects()
    ]

workspaces ¶

workspaces(
    *, project_id: str | None = None, refresh: bool = False
) -> list[_WorkspaceRef]

List workspaces for a project via the /me API (FR-036).

Returns workspaces from the cached /me response, sorted by name. Defaults to the current project if project_id is not provided.

Replaces the deprecated discover_workspaces() (which returned list[MeWorkspaceInfo]) — for the raw /me shape with extra fields (is_global, is_restricted, description, ...), call self._me_svc.list_workspaces(project_id=) directly from internal code.

PARAMETER	DESCRIPTION
`project_id`	Project ID to list workspaces for. Defaults to the current project. TYPE: `str \| None` DEFAULT: `None`
`refresh`	When True, bypass the on-disk and in-memory `/me` caches and refetch from the API. Default False uses the 24h cache. Mirrors :meth:`projects(refresh=)` (FR-047). TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`list[WorkspaceRef]`	List of :class:`WorkspaceRef` records sorted by name.

RAISES	DESCRIPTION
`ConfigError`	If credentials lack /me access.

Example

ws = Workspace()
for workspace in ws.workspaces():
    print(workspace.id, workspace.name, workspace.is_default)

Source code in src/mixpanel_headless/workspace.py

def workspaces(
    self,
    *,
    project_id: str | None = None,
    refresh: bool = False,
) -> list[_WorkspaceRef]:
    """List workspaces for a project via the /me API (FR-036).

    Returns workspaces from the cached /me response, sorted by name.
    Defaults to the current project if ``project_id`` is not provided.

    Replaces the deprecated ``discover_workspaces()`` (which returned
    ``list[MeWorkspaceInfo]``) — for the raw ``/me`` shape with extra
    fields (``is_global``, ``is_restricted``, ``description``, ...),
    call ``self._me_svc.list_workspaces(project_id=)`` directly from
    internal code.

    Args:
        project_id: Project ID to list workspaces for. Defaults to
            the current project.
        refresh: When True, bypass the on-disk and in-memory ``/me``
            caches and refetch from the API. Default False uses the
            24h cache. Mirrors :meth:`projects(refresh=)` (FR-047).

    Returns:
        List of :class:`WorkspaceRef` records sorted by name.

    Raises:
        ConfigError: If credentials lack /me access.

    Example:
        ```python
        ws = Workspace()
        for workspace in ws.workspaces():
            print(workspace.id, workspace.name, workspace.is_default)
        ```
    """
    if refresh:
        self._me_svc.fetch(force_refresh=True)
    pid = project_id
    if pid is None:
        pid = self._session.project.id
    return [
        _WorkspaceRef(id=info.id, name=info.name, is_default=info.is_default)
        for info in self._me_svc.list_workspaces(project_id=pid)
    ]

list_workspaces ¶

list_workspaces() -> list[PublicWorkspace]

List all public workspaces for the current project.

Delegates to the API client's list_workspaces() method, which calls GET /api/app/projects/{pid}/workspaces/public.

RETURNS	DESCRIPTION
`list[PublicWorkspace]`	List of `PublicWorkspace` models for the project.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
workspaces = ws.list_workspaces()
for w in workspaces:
    print(f"{w.name} (id={w.id}, default={w.is_default})")

Source code in src/mixpanel_headless/workspace.py

def list_workspaces(self) -> list[PublicWorkspace]:
    """List all public workspaces for the current project.

    Delegates to the API client's ``list_workspaces()`` method, which
    calls ``GET /api/app/projects/{pid}/workspaces/public``.

    Returns:
        List of ``PublicWorkspace`` models for the project.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        workspaces = ws.list_workspaces()
        for w in workspaces:
            print(f"{w.name} (id={w.id}, default={w.is_default})")
        ```
    """
    client = self._require_api_client()
    return client.list_workspaces()

resolve_workspace_id ¶

resolve_workspace_id() -> int

Resolve the workspace ID for scoped requests.

Resolution order: 1. Workspace ID already pinned on the resolved session (for example via Workspace(workspace=N), Workspace.use(workspace=N), MP_WORKSPACE_ID, saved targets, bridge pins, or persisted [active].workspace state) 2. Cached auto-discovered workspace ID 3. Auto-discover across the cached /me view, then GET /projects/{pid}/workspaces/public, then the projects metadata index — each applying the shared preference of :func:~mixpanel_headless._internal.me.select_workspace_id (global view, then "All Project Data", then default, then first visible, then first). See :meth:MixpanelAPIClient.resolve_workspace_id for the full source-by-source rules and error behavior.

RETURNS	DESCRIPTION
`int`	The resolved workspace ID.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`WorkspaceScopeError`	If no workspace could be resolved for the project from any source.

Example

ws = Workspace()
ws_id = ws.resolve_workspace_id()
print(f"Using workspace {ws_id}")

Source code in src/mixpanel_headless/workspace.py

def resolve_workspace_id(self) -> int:
    """Resolve the workspace ID for scoped requests.

    Resolution order:
    1. Workspace ID already pinned on the resolved session (for example
       via ``Workspace(workspace=N)``, ``Workspace.use(workspace=N)``,
       ``MP_WORKSPACE_ID``, saved targets, bridge pins, or persisted
       ``[active].workspace`` state)
    2. Cached auto-discovered workspace ID
    3. Auto-discover across the cached ``/me`` view, then
       ``GET /projects/{pid}/workspaces/public``, then the projects metadata
       index — each applying the shared preference of
       :func:`~mixpanel_headless._internal.me.select_workspace_id` (global
       view, then "All Project Data", then default, then first visible, then
       first). See :meth:`MixpanelAPIClient.resolve_workspace_id` for the
       full source-by-source rules and error behavior.

    Returns:
        The resolved workspace ID.

    Raises:
        ConfigError: If credentials are not available.
        WorkspaceScopeError: If no workspace could be resolved for the
            project from any source.

    Example:
        ```python
        ws = Workspace()
        ws_id = ws.resolve_workspace_id()
        print(f"Using workspace {ws_id}")
        ```
    """
    client = self._require_api_client()
    return client.resolve_workspace_id()

events ¶

events(
    *,
    limit: int | None = None,
    from_date: str | None = None,
    to_date: str | None = None,
) -> list[str]

List event names in the Mixpanel project.

Defaults to the widest window the underlying /events/names endpoint will accept: limit=5000 (the server-side ceiling), from_date=2000-01-01 (the API's earliest accepted year — pre-2000 values come back as "invalid date, bad year"), and to_date set to today. The endpoint is gated by the per-project max_data_history_days feature; if the wide from_date is rejected (HTTP 403, "Date range exceeds N days into the past"), the call automatically retries with today - N days.

Note that this method reflects events seen during the queried window — it is not the schema registry. Events that were registered in Lexicon but never fired in the window are absent. For the full registered schema, use the Lexicon endpoints (e.g. :meth:get_event_definitions).

Results are cached per (limit, from_date, to_date) triple for the lifetime of the Workspace.

PARAMETER	DESCRIPTION
`limit`	Maximum events to return. Defaults to the server-side ceiling (5000). TYPE: `int \| None` DEFAULT: `None`
`from_date`	`YYYY-MM-DD` lower bound. Defaults to `2000-01-01` and falls back to the project's `max_data_history_days` ceiling on rejection. TYPE: `str \| None` DEFAULT: `None`
`to_date`	`YYYY-MM-DD` upper bound. Defaults to today. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[str]`	Alphabetically sorted list of event names.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.
`AuthenticationError`	If credentials are invalid.
`QueryError`	403 errors unrelated to date-range gating, or any other 4xx the `/events/names` endpoint emits.

Source code in src/mixpanel_headless/workspace.py

def events(
    self,
    *,
    limit: int | None = None,
    from_date: str | None = None,
    to_date: str | None = None,
) -> list[str]:
    """List event names in the Mixpanel project.

    Defaults to the widest window the underlying
    ``/events/names`` endpoint will accept: ``limit=5000`` (the
    server-side ceiling), ``from_date=2000-01-01`` (the API's
    earliest accepted year — pre-2000 values come back as
    ``"invalid date, bad year"``), and ``to_date`` set to today.
    The endpoint is gated by the per-project
    ``max_data_history_days`` feature; if the wide ``from_date``
    is rejected (HTTP 403, "Date range exceeds N days into the
    past"), the call automatically retries with ``today - N days``.

    Note that this method reflects events seen during the queried
    window — it is not the schema registry. Events that were
    registered in Lexicon but never fired in the window are
    absent. For the full registered schema, use the Lexicon
    endpoints (e.g. :meth:`get_event_definitions`).

    Results are cached per ``(limit, from_date, to_date)`` triple
    for the lifetime of the Workspace.

    Args:
        limit: Maximum events to return. Defaults to the
            server-side ceiling (5000).
        from_date: ``YYYY-MM-DD`` lower bound. Defaults to
            ``2000-01-01`` and falls back to the project's
            ``max_data_history_days`` ceiling on rejection.
        to_date: ``YYYY-MM-DD`` upper bound. Defaults to today.

    Returns:
        Alphabetically sorted list of event names.

    Raises:
        ConfigError: If API credentials not available.
        AuthenticationError: If credentials are invalid.
        QueryError: 403 errors unrelated to date-range gating, or
            any other 4xx the ``/events/names`` endpoint emits.
    """
    return self._discovery_service.list_events(
        limit=limit,
        from_date=from_date,
        to_date=to_date,
    )

properties ¶

properties(event: str) -> list[str]

List all property names for an event.

Results are cached per event for the lifetime of the Workspace.

PARAMETER	DESCRIPTION
`event`	Event name to get properties for. TYPE: `str`

RETURNS	DESCRIPTION
`list[str]`	Alphabetically sorted list of property names.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def properties(self, event: str) -> list[str]:
    """List all property names for an event.

    Results are cached per event for the lifetime of the Workspace.

    Args:
        event: Event name to get properties for.

    Returns:
        Alphabetically sorted list of property names.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._discovery_service.list_properties(event)

property_values ¶

property_values(
    property_name: str, *, event: str | None = None, limit: int = 100
) -> list[str]

Get sample values for a property.

Results are cached per (property, event, limit) for the lifetime of the Workspace.

PARAMETER	DESCRIPTION
`property_name`	Property to get values for. TYPE: `str`
`event`	Optional event to filter by. TYPE: `str \| None` DEFAULT: `None`
`limit`	Maximum number of values to return. TYPE: `int` DEFAULT: `100`

RETURNS	DESCRIPTION
`list[str]`	List of sample property values as strings.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def property_values(
    self,
    property_name: str,
    *,
    event: str | None = None,
    limit: int = 100,
) -> list[str]:
    """Get sample values for a property.

    Results are cached per (property, event, limit) for the lifetime of the Workspace.

    Args:
        property_name: Property to get values for.
        event: Optional event to filter by.
        limit: Maximum number of values to return.

    Returns:
        List of sample property values as strings.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._discovery_service.list_property_values(
        property_name, event=event, limit=limit
    )

subproperties ¶

subproperties(
    property_name: str, *, event: str | None = None, sample_size: int = 50
) -> list[SubPropertyInfo]

List inferred subproperties of a list-of-object event property.

Samples values via :meth:property_values, parses each as JSON, and returns one :class:SubPropertyInfo per discovered scalar subproperty. Designed for properties like cart whose values are objects with subkeys (Brand, Category, Price, Item ID). The returned name and type plug directly into :meth:GroupBy.list_item and :meth:Filter.list_contains.

Scope: only scalar subproperty values (string / number / boolean / ISO datetime string) are reported. Subproperties whose values are themselves dicts or lists are silently skipped — they cannot be used by GroupBy.list_item or Filter.list_contains anyway.

PARAMETER	DESCRIPTION
`property_name`	Top-level list-of-object property name (e.g. `"cart"`). TYPE: `str`
`event`	Optional event name to scope the sample. Strongly recommended; without it the API may return values from across all events. TYPE: `str \| None` DEFAULT: `None`
`sample_size`	Number of raw values to sample. Default: 50. TYPE: `int` DEFAULT: `50`

RETURNS	DESCRIPTION
`list[SubPropertyInfo]`	Alphabetically sorted list of :class:`SubPropertyInfo`.
`list[SubPropertyInfo]`	Empty list if no parseable dict values were found.

RAISES	DESCRIPTION
`ConfigError`	If API credentials cannot be resolved.
`AuthenticationError`	If credentials are configured but rejected by Mixpanel.

WARNS	DESCRIPTION
`UserWarning`	When a subproperty has values of mixed scalar types across rows (collapses to `"string"`); when a sub-key is observed with both scalar and nested-object shapes (reports the scalar form); or when a sub-key is observed but all sampled values were `null` (excluded from output).

Example

for sp in ws.subproperties("cart", event="Cart Viewed"):
    print(sp.name, sp.type, sp.sample_values)
# Brand string ('nike', 'puma', 'h&m')
# Category string ('hats', 'jeans')
# Item ID number (35317, 35318)
# Price number (51, 87, 102)

Source code in src/mixpanel_headless/workspace.py

def subproperties(
    self,
    property_name: str,
    *,
    event: str | None = None,
    sample_size: int = 50,
) -> list[SubPropertyInfo]:
    """List inferred subproperties of a list-of-object event property.

    Samples values via :meth:`property_values`, parses each as JSON,
    and returns one :class:`SubPropertyInfo` per discovered scalar
    subproperty. Designed for properties like ``cart`` whose values
    are objects with subkeys (``Brand``, ``Category``, ``Price``,
    ``Item ID``). The returned ``name`` and ``type`` plug directly
    into :meth:`GroupBy.list_item` and :meth:`Filter.list_contains`.

    Scope: only **scalar** subproperty values (string / number /
    boolean / ISO datetime string) are reported. Subproperties whose
    values are themselves dicts or lists are silently skipped — they
    cannot be used by ``GroupBy.list_item`` or
    ``Filter.list_contains`` anyway.

    Args:
        property_name: Top-level list-of-object property name (e.g.
            ``"cart"``).
        event: Optional event name to scope the sample. Strongly
            recommended; without it the API may return values from
            across all events.
        sample_size: Number of raw values to sample. Default: 50.

    Returns:
        Alphabetically sorted list of :class:`SubPropertyInfo`.
        Empty list if no parseable dict values were found.

    Raises:
        ConfigError: If API credentials cannot be resolved.
        AuthenticationError: If credentials are configured but
            rejected by Mixpanel.

    Warns:
        UserWarning: When a subproperty has values of mixed scalar
            types across rows (collapses to ``"string"``); when a
            sub-key is observed with both scalar and nested-object
            shapes (reports the scalar form); or when a sub-key
            is observed but all sampled values were ``null``
            (excluded from output).

    Example:
        ```python
        for sp in ws.subproperties("cart", event="Cart Viewed"):
            print(sp.name, sp.type, sp.sample_values)
        # Brand string ('nike', 'puma', 'h&m')
        # Category string ('hats', 'jeans')
        # Item ID number (35317, 35318)
        # Price number (51, 87, 102)
        ```
    """
    return self._discovery_service.list_subproperties(
        property_name, event=event, sample_size=sample_size
    )

funnels ¶

funnels() -> list[FunnelInfo]

List saved funnels in the Mixpanel project.

Results are cached for the lifetime of the Workspace.

RETURNS	DESCRIPTION
`list[FunnelInfo]`	List of FunnelInfo objects (funnel_id, name).

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def funnels(self) -> list[FunnelInfo]:
    """List saved funnels in the Mixpanel project.

    Results are cached for the lifetime of the Workspace.

    Returns:
        List of FunnelInfo objects (funnel_id, name).

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._discovery_service.list_funnels()

cohorts ¶

cohorts() -> list[SavedCohort]

List saved cohorts in the Mixpanel project.

Results are cached for the lifetime of the Workspace.

RETURNS	DESCRIPTION
`list[SavedCohort]`	List of SavedCohort objects.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def cohorts(self) -> list[SavedCohort]:
    """List saved cohorts in the Mixpanel project.

    Results are cached for the lifetime of the Workspace.

    Returns:
        List of SavedCohort objects.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._discovery_service.list_cohorts()

list_bookmarks ¶

list_bookmarks(bookmark_type: BookmarkType | None = None) -> list[BookmarkInfo]

List all saved reports (bookmarks) in the project.

Retrieves metadata for all saved Insights, Funnel, Retention, and Flows reports in the project.

PARAMETER	DESCRIPTION
`bookmark_type`	Optional filter by report type. Valid values are 'insights', 'funnels', 'retention', 'flows', 'launch-analysis'. If None, returns all bookmark types. TYPE: `BookmarkType \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[BookmarkInfo]`	List of BookmarkInfo objects with report metadata.
`list[BookmarkInfo]`	Empty list if no bookmarks exist.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.
`QueryError`	Permission denied or invalid type parameter.

Source code in src/mixpanel_headless/workspace.py

def list_bookmarks(
    self,
    bookmark_type: BookmarkType | None = None,
) -> list[BookmarkInfo]:
    """List all saved reports (bookmarks) in the project.

    Retrieves metadata for all saved Insights, Funnel, Retention, and
    Flows reports in the project.

    Args:
        bookmark_type: Optional filter by report type. Valid values are
            'insights', 'funnels', 'retention', 'flows', 'launch-analysis'.
            If None, returns all bookmark types.

    Returns:
        List of BookmarkInfo objects with report metadata.
        Empty list if no bookmarks exist.

    Raises:
        ConfigError: If API credentials not available.
        QueryError: Permission denied or invalid type parameter.
    """
    return self._discovery_service.list_bookmarks(bookmark_type=bookmark_type)

top_events ¶

top_events(
    *,
    type: Literal["general", "average", "unique"] = "general",
    limit: int | None = None,
) -> list[TopEvent]

Get today's most active events.

This method is NOT cached (returns real-time data).

PARAMETER	DESCRIPTION
`type`	Counting method (general, average, unique). TYPE: `Literal['general', 'average', 'unique']` DEFAULT: `'general'`
`limit`	Maximum number of events to return. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[TopEvent]`	List of TopEvent objects with `event`, `count`, and
`list[TopEvent]`	`percent_change` fields.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Example

top = ws.top_events(limit=10)
for t in top:
    print(f"{t.event}: {t.count:,} ({t.percent_change:+.1%})")

Source code in src/mixpanel_headless/workspace.py

def top_events(
    self,
    *,
    type: Literal["general", "average", "unique"] = "general",
    limit: int | None = None,
) -> list[TopEvent]:
    """Get today's most active events.

    This method is NOT cached (returns real-time data).

    Args:
        type: Counting method (general, average, unique).
        limit: Maximum number of events to return.

    Returns:
        List of TopEvent objects with ``event``, ``count``, and
        ``percent_change`` fields.

    Raises:
        ConfigError: If API credentials not available.

    Example:
        ```python
        top = ws.top_events(limit=10)
        for t in top:
            print(f"{t.event}: {t.count:,} ({t.percent_change:+.1%})")
        ```
    """
    return self._discovery_service.list_top_events(type=type, limit=limit)

lexicon_schemas ¶

lexicon_schemas(
    *, entity_type: EntityType | None = None
) -> list[LexiconSchema]

List Lexicon schemas in the project.

Retrieves documented event and profile property schemas from the Mixpanel Lexicon (data dictionary).

Results are cached for the lifetime of the Workspace.

PARAMETER	DESCRIPTION
`entity_type`	Optional filter by type ("event" or "profile"). If None, returns all schemas. TYPE: `EntityType \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[LexiconSchema]`	Alphabetically sorted list of LexiconSchema objects.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.
`AuthenticationError`	If credentials are invalid.

Note

The Lexicon API has a strict 5 requests/minute rate limit. Caching helps avoid hitting this limit; call clear_discovery_cache() only when fresh data is needed.

Source code in src/mixpanel_headless/workspace.py

def lexicon_schemas(
    self,
    *,
    entity_type: EntityType | None = None,
) -> list[LexiconSchema]:
    """List Lexicon schemas in the project.

    Retrieves documented event and profile property schemas from the
    Mixpanel Lexicon (data dictionary).

    Results are cached for the lifetime of the Workspace.

    Args:
        entity_type: Optional filter by type ("event" or "profile").
            If None, returns all schemas.

    Returns:
        Alphabetically sorted list of LexiconSchema objects.

    Raises:
        ConfigError: If API credentials not available.
        AuthenticationError: If credentials are invalid.

    Note:
        The Lexicon API has a strict 5 requests/minute rate limit.
        Caching helps avoid hitting this limit; call clear_discovery_cache()
        only when fresh data is needed.
    """
    return self._discovery_service.list_schemas(entity_type=entity_type)

lexicon_schema ¶

lexicon_schema(entity_type: EntityType, name: str) -> LexiconSchema

Get a single Lexicon schema by entity type and name.

Retrieves a documented schema for a specific event or profile property from the Mixpanel Lexicon (data dictionary).

Results are cached for the lifetime of the Workspace.

PARAMETER	DESCRIPTION
`entity_type`	Entity type ("event" or "profile"). TYPE: `EntityType`
`name`	Entity name. TYPE: `str`

RETURNS	DESCRIPTION
`LexiconSchema`	LexiconSchema for the specified entity.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.
`AuthenticationError`	If credentials are invalid.
`QueryError`	If schema not found.

Note

The Lexicon API has a strict 5 requests/minute rate limit. Caching helps avoid hitting this limit; call clear_discovery_cache() only when fresh data is needed.

Source code in src/mixpanel_headless/workspace.py

def lexicon_schema(
    self,
    entity_type: EntityType,
    name: str,
) -> LexiconSchema:
    """Get a single Lexicon schema by entity type and name.

    Retrieves a documented schema for a specific event or profile property
    from the Mixpanel Lexicon (data dictionary).

    Results are cached for the lifetime of the Workspace.

    Args:
        entity_type: Entity type ("event" or "profile").
        name: Entity name.

    Returns:
        LexiconSchema for the specified entity.

    Raises:
        ConfigError: If API credentials not available.
        AuthenticationError: If credentials are invalid.
        QueryError: If schema not found.

    Note:
        The Lexicon API has a strict 5 requests/minute rate limit.
        Caching helps avoid hitting this limit; call clear_discovery_cache()
        only when fresh data is needed.
    """
    return self._discovery_service.get_schema(entity_type, name)

schema_graph ¶

schema_graph(
    *,
    include_density: bool = False,
    include_user_properties: bool = True,
    force_refresh: bool = False,
) -> SchemaGraphResult

Gather the full Lexicon schema and event<->property relationships.

Adapts the power-tools getSchema view: one call returns the project's event definitions, event properties, and user properties, plus the adjacency between events and the properties that appear on them. The adjacency comes from the query API's per-event properties gather, which tolerates large projects (the App API join it replaces timed out at the ~120s gateway deadline); on very large projects the gather can still take minutes. The result is a typed :class:SchemaGraphResult with DataFrame views (events_df, properties_df, relationships_df) and a to_graph() networkx export.

Group properties are not gathered yet (headless has no data-groups listing to enumerate them).

Results are cached for the lifetime of the Workspace.

PARAMETER	DESCRIPTION
`include_density`	Request the property-level density (`densityLocal`) the bulk call returns; it repeats onto each of a property's relationship edges and is `None` otherwise. TYPE: `bool` DEFAULT: `False`
`include_user_properties`	Also gather user properties. TYPE: `bool` DEFAULT: `True`
`force_refresh`	Bypass the cache and re-fetch. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`A`	class:`SchemaGraphResult`. TYPE: `SchemaGraphResult`

RAISES	DESCRIPTION
`ConfigError`	If API credentials are not available.
`AuthenticationError`	If credentials are invalid.

Example

ws = Workspace()
schema = ws.schema_graph()
schema.properties_for_event("Purchase")
schema.relationships_df.head()
graph = schema.to_graph()

Source code in src/mixpanel_headless/workspace.py

def schema_graph(
    self,
    *,
    include_density: bool = False,
    include_user_properties: bool = True,
    force_refresh: bool = False,
) -> SchemaGraphResult:
    """Gather the full Lexicon schema and event<->property relationships.

    Adapts the power-tools ``getSchema`` view: one call returns the project's
    event definitions, event properties, and user properties, plus the
    adjacency between events and the properties that appear on them. The
    adjacency comes from the query API's per-event properties gather, which
    tolerates large projects (the App API join it replaces timed out at the
    ~120s gateway deadline); on very large projects the gather can still
    take minutes. The result is a typed :class:`SchemaGraphResult` with
    DataFrame views (``events_df``, ``properties_df``,
    ``relationships_df``) and a ``to_graph()`` networkx export.

    Group properties are not gathered yet (headless has no data-groups
    listing to enumerate them).

    Results are cached for the lifetime of the Workspace.

    Args:
        include_density: Request the property-level density (``densityLocal``)
            the bulk call returns; it repeats onto each of a property's
            relationship edges and is ``None`` otherwise.
        include_user_properties: Also gather user properties.
        force_refresh: Bypass the cache and re-fetch.

    Returns:
        A :class:`SchemaGraphResult`.

    Raises:
        ConfigError: If API credentials are not available.
        AuthenticationError: If credentials are invalid.

    Example:
        ```python
        ws = Workspace()
        schema = ws.schema_graph()
        schema.properties_for_event("Purchase")
        schema.relationships_df.head()
        graph = schema.to_graph()
        ```
    """
    return self._discovery_service.get_schema_graph(
        include_density=include_density,
        include_user_properties=include_user_properties,
        force_refresh=force_refresh,
    )

clear_discovery_cache ¶

clear_discovery_cache() -> None

Clear cached discovery results.

Subsequent discovery calls will fetch fresh data from the API.

Source code in src/mixpanel_headless/workspace.py

def clear_discovery_cache(self) -> None:
    """Clear cached discovery results.

    Subsequent discovery calls will fetch fresh data from the API.
    """
    if self._discovery is not None:
        self._discovery.clear_cache()

stream_events ¶

stream_events(
    *,
    from_date: str,
    to_date: str,
    events: list[str] | None = None,
    where: str | None = None,
    limit: int | None = None,
    raw: bool = False,
) -> Iterator[dict[str, Any]]

Stream events directly from Mixpanel API without storing.

Yields events one at a time as they are received from the API. No database files or tables are created.

PARAMETER	DESCRIPTION
`from_date`	Start date inclusive (YYYY-MM-DD format). TYPE: `str`
`to_date`	End date inclusive (YYYY-MM-DD format). TYPE: `str`
`events`	Optional list of event names to filter. If None, all events returned. TYPE: `list[str] \| None` DEFAULT: `None`
`where`	Optional Mixpanel filter expression (e.g., 'properties["country"]=="US"'). TYPE: `str \| None` DEFAULT: `None`
`limit`	Optional maximum number of events to return (max 100000). TYPE: `int \| None` DEFAULT: `None`
`raw`	If True, return events in raw Mixpanel API format. If False (default), return normalized format with datetime objects. TYPE: `bool` DEFAULT: `False`

YIELDS	DESCRIPTION
`dict[str, Any]`	dict[str, Any]: Event dictionaries in normalized or raw format.

RAISES	DESCRIPTION
`ConfigError`	If API credentials are not available.
`AuthenticationError`	If credentials are invalid.
`RateLimitError`	If rate limit exceeded after max retries.
`QueryError`	If filter expression is invalid.
`ValueError`	If limit is outside valid range (1-100000).

Example

ws = Workspace()
for event in ws.stream_events(from_date="2024-01-01", to_date="2024-01-31"):
    process(event)
ws.close()

With raw format:

for event in ws.stream_events(
    from_date="2024-01-01", to_date="2024-01-31", raw=True
):
    legacy_system.ingest(event)

Source code in src/mixpanel_headless/workspace.py

def stream_events(
    self,
    *,
    from_date: str,
    to_date: str,
    events: list[str] | None = None,
    where: str | None = None,
    limit: int | None = None,
    raw: bool = False,
) -> Iterator[dict[str, Any]]:
    """Stream events directly from Mixpanel API without storing.

    Yields events one at a time as they are received from the API.
    No database files or tables are created.

    Args:
        from_date: Start date inclusive (YYYY-MM-DD format).
        to_date: End date inclusive (YYYY-MM-DD format).
        events: Optional list of event names to filter. If None, all events returned.
        where: Optional Mixpanel filter expression (e.g., 'properties["country"]=="US"').
        limit: Optional maximum number of events to return (max 100000).
        raw: If True, return events in raw Mixpanel API format.
             If False (default), return normalized format with datetime objects.

    Yields:
        dict[str, Any]: Event dictionaries in normalized or raw format.

    Raises:
        ConfigError: If API credentials are not available.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If rate limit exceeded after max retries.
        QueryError: If filter expression is invalid.
        ValueError: If limit is outside valid range (1-100000).

    Example:
        ```python
        ws = Workspace()
        for event in ws.stream_events(from_date="2024-01-01", to_date="2024-01-31"):
            process(event)
        ws.close()
        ```

        With raw format:

        ```python
        for event in ws.stream_events(
            from_date="2024-01-01", to_date="2024-01-31", raw=True
        ):
            legacy_system.ingest(event)
        ```
    """
    # Validate limit early to avoid wasted API calls
    _validate_limit(limit)

    api_client = self._require_api_client()
    event_iterator = api_client.export_events(
        from_date=from_date,
        to_date=to_date,
        events=events,
        where=where,
        limit=limit,
    )

    if raw:
        yield from event_iterator
    else:
        for event in event_iterator:
            yield transform_event(event)

stream_profiles ¶

stream_profiles(
    *,
    where: str | None = None,
    cohort_id: str | None = None,
    output_properties: list[str] | None = None,
    raw: bool = False,
    distinct_id: str | None = None,
    distinct_ids: list[str] | None = None,
    group_id: str | None = None,
    behaviors: list[dict[str, Any]] | None = None,
    as_of_timestamp: int | None = None,
    include_all_users: bool = False,
) -> Iterator[dict[str, Any]]

Stream user profiles directly from Mixpanel API without storing.

Yields profiles one at a time as they are received from the API. No database files or tables are created.

PARAMETER	DESCRIPTION
`where`	Optional Mixpanel filter expression for profile properties. TYPE: `str \| None` DEFAULT: `None`
`cohort_id`	Optional cohort ID to filter by. Only profiles that are members of this cohort will be returned. TYPE: `str \| None` DEFAULT: `None`
`output_properties`	Optional list of property names to include in the response. If None, all properties are returned. TYPE: `list[str] \| None` DEFAULT: `None`
`raw`	If True, return profiles in raw Mixpanel API format. If False (default), return normalized format. TYPE: `bool` DEFAULT: `False`
`distinct_id`	Optional single user ID to fetch. Mutually exclusive with distinct_ids. TYPE: `str \| None` DEFAULT: `None`
`distinct_ids`	Optional list of user IDs to fetch. Mutually exclusive with distinct_id. Duplicates are automatically removed. TYPE: `list[str] \| None` DEFAULT: `None`
`group_id`	Optional group type identifier (e.g., "companies") to fetch group profiles instead of user profiles. TYPE: `str \| None` DEFAULT: `None`
`behaviors`	Optional list of behavioral filters. Each dict should have 'window' (e.g., "30d"), 'name' (identifier), and 'event_selectors' (list of {"event": "Name"}). Use with `where` parameter to filter, e.g., where='(behaviors["name"] > 0)'. Mutually exclusive with cohort_id. TYPE: `list[dict[str, Any]] \| None` DEFAULT: `None`
`as_of_timestamp`	Optional Unix timestamp to query profile state at a specific point in time. Must be in the past. TYPE: `int \| None` DEFAULT: `None`
`include_all_users`	If True, include all users and mark cohort membership. Only valid when cohort_id is provided. TYPE: `bool` DEFAULT: `False`

YIELDS	DESCRIPTION
`dict[str, Any]`	dict[str, Any]: Profile dictionaries in normalized or raw format.

RAISES	DESCRIPTION
`ConfigError`	If API credentials are not available.
`AuthenticationError`	If credentials are invalid.
`RateLimitError`	If rate limit exceeded after max retries.
`ValueError`	If mutually exclusive parameters are provided.

Example

ws = Workspace()
for profile in ws.stream_profiles():
    sync_to_crm(profile)
ws.close()

Filter to premium users:

for profile in ws.stream_profiles(where='properties["plan"]=="premium"'):
    send_survey(profile)

Filter by cohort and select specific properties:

for profile in ws.stream_profiles(
    cohort_id="12345",
    output_properties=["$email", "$name"]
):
    send_email(profile)

Fetch specific users by ID:

for profile in ws.stream_profiles(distinct_ids=["user_1", "user_2"]):
    print(profile)

Fetch group profiles:

for company in ws.stream_profiles(group_id="companies"):
    print(company)

Source code in src/mixpanel_headless/workspace.py

def stream_profiles(
    self,
    *,
    where: str | None = None,
    cohort_id: str | None = None,
    output_properties: list[str] | None = None,
    raw: bool = False,
    distinct_id: str | None = None,
    distinct_ids: list[str] | None = None,
    group_id: str | None = None,
    behaviors: list[dict[str, Any]] | None = None,
    as_of_timestamp: int | None = None,
    include_all_users: bool = False,
) -> Iterator[dict[str, Any]]:
    """Stream user profiles directly from Mixpanel API without storing.

    Yields profiles one at a time as they are received from the API.
    No database files or tables are created.

    Args:
        where: Optional Mixpanel filter expression for profile properties.
        cohort_id: Optional cohort ID to filter by. Only profiles that are
            members of this cohort will be returned.
        output_properties: Optional list of property names to include in
            the response. If None, all properties are returned.
        raw: If True, return profiles in raw Mixpanel API format.
             If False (default), return normalized format.
        distinct_id: Optional single user ID to fetch. Mutually exclusive
            with distinct_ids.
        distinct_ids: Optional list of user IDs to fetch. Mutually exclusive
            with distinct_id. Duplicates are automatically removed.
        group_id: Optional group type identifier (e.g., "companies") to fetch
            group profiles instead of user profiles.
        behaviors: Optional list of behavioral filters. Each dict should have
            'window' (e.g., "30d"), 'name' (identifier), and 'event_selectors'
            (list of {"event": "Name"}). Use with `where` parameter to filter,
            e.g., where='(behaviors["name"] > 0)'. Mutually exclusive with
            cohort_id.
        as_of_timestamp: Optional Unix timestamp to query profile state at
            a specific point in time. Must be in the past.
        include_all_users: If True, include all users and mark cohort membership.
            Only valid when cohort_id is provided.

    Yields:
        dict[str, Any]: Profile dictionaries in normalized or raw format.

    Raises:
        ConfigError: If API credentials are not available.
        AuthenticationError: If credentials are invalid.
        RateLimitError: If rate limit exceeded after max retries.
        ValueError: If mutually exclusive parameters are provided.

    Example:
        ```python
        ws = Workspace()
        for profile in ws.stream_profiles():
            sync_to_crm(profile)
        ws.close()
        ```

        Filter to premium users:

        ```python
        for profile in ws.stream_profiles(where='properties["plan"]=="premium"'):
            send_survey(profile)
        ```

        Filter by cohort and select specific properties:

        ```python
        for profile in ws.stream_profiles(
            cohort_id="12345",
            output_properties=["$email", "$name"]
        ):
            send_email(profile)
        ```

        Fetch specific users by ID:

        ```python
        for profile in ws.stream_profiles(distinct_ids=["user_1", "user_2"]):
            print(profile)
        ```

        Fetch group profiles:

        ```python
        for company in ws.stream_profiles(group_id="companies"):
            print(company)
        ```
    """
    api_client = self._require_api_client()
    profile_iterator = api_client.export_profiles(
        where=where,
        cohort_id=cohort_id,
        output_properties=output_properties,
        distinct_id=distinct_id,
        distinct_ids=distinct_ids,
        group_id=group_id,
        behaviors=behaviors,
        as_of_timestamp=as_of_timestamp,
        include_all_users=include_all_users,
    )

    if raw:
        yield from profile_iterator
    else:
        for profile in profile_iterator:
            yield transform_profile(profile)

get_business_context ¶

get_business_context(
    *,
    level: Literal["organization", "project"] = "project",
    organization_id: int | None = None,
) -> BusinessContext

Read business context content at the given scope.

Calls GET /api/app/projects/{pid}/business-context (when level="project") or GET /api/app/organizations/{org_id}/business-context (when level="organization"). Returns a populated BusinessContext with content="" when no context is set.

PARAMETER	DESCRIPTION
`level`	`"project"` (default) reads the project-level context for the active session's project. `"organization"` reads the org-level context shared across all projects in the organization. TYPE: `Literal['organization', 'project']` DEFAULT: `'project'`
`organization_id`	Optional explicit org ID, only honored when `level="organization"`. When omitted, the org ID is auto-resolved from the cached `/me` response (which may trigger a `/me` API call when the cache is cold). TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`BusinessContext`	`BusinessContext` whose `content` reflects the server's
`BusinessContext`	current state. `organization_id` is populated for
`BusinessContext`	org-level returns; `project_id` for project-level.

RAISES	DESCRIPTION
`ValueError`	`level` is not `"organization"` or `"project"`.
`ConfigError`	Credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400, 403, 404).
`ServerError`	Server-side errors (5xx).
`WorkspaceScopeError`	`level="organization"` and the org ID could not be auto-resolved.
`MixpanelHeadlessError`	API response is missing the `content` field.

Example

ws = Workspace()
project_ctx = ws.get_business_context(level="project")
org_ctx = ws.get_business_context(
    level="organization", organization_id=100,
)
print(project_ctx.content)

Source code in src/mixpanel_headless/workspace.py

def get_business_context(
    self,
    *,
    level: Literal["organization", "project"] = "project",
    organization_id: int | None = None,
) -> BusinessContext:
    """Read business context content at the given scope.

    Calls ``GET /api/app/projects/{pid}/business-context`` (when
    ``level="project"``) or
    ``GET /api/app/organizations/{org_id}/business-context``
    (when ``level="organization"``). Returns a populated
    ``BusinessContext`` with ``content=""`` when no context is set.

    Args:
        level: ``"project"`` (default) reads the project-level
            context for the active session's project.
            ``"organization"`` reads the org-level context shared
            across all projects in the organization.
        organization_id: Optional explicit org ID, only honored
            when ``level="organization"``. When omitted, the org ID
            is auto-resolved from the cached ``/me`` response
            (which may trigger a ``/me`` API call when the cache
            is cold).

    Returns:
        ``BusinessContext`` whose ``content`` reflects the server's
        current state. ``organization_id`` is populated for
        org-level returns; ``project_id`` for project-level.

    Raises:
        ValueError: ``level`` is not ``"organization"`` or ``"project"``.
        ConfigError: Credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400, 403, 404).
        ServerError: Server-side errors (5xx).
        WorkspaceScopeError: ``level="organization"`` and the org
            ID could not be auto-resolved.
        MixpanelHeadlessError: API response is missing the ``content``
            field.

    Example:
        ```python
        ws = Workspace()
        project_ctx = ws.get_business_context(level="project")
        org_ctx = ws.get_business_context(
            level="organization", organization_id=100,
        )
        print(project_ctx.content)
        ```
    """
    self._validate_level(level)
    client = self._require_api_client()
    if level == "organization":
        org_id = self._resolve_organization_id(organization_id)
        raw = client.get_business_context(organization_id=org_id)
        return BusinessContext(
            level="organization",
            content=self._require_str_field(
                raw,
                "content",
                method="get_business_context",
            ),
            organization_id=org_id,
        )
    raw = client.get_business_context()
    return BusinessContext(
        level="project",
        content=self._require_str_field(
            raw,
            "content",
            method="get_business_context",
        ),
        project_id=self._session.project.id,
    )

set_business_context ¶

set_business_context(
    content: str,
    *,
    level: Literal["organization", "project"] = "project",
    organization_id: int | None = None,
) -> BusinessContext

Replace business context content at the given scope.

Validates len(content) <= BUSINESS_CONTEXT_MAX_CHARS (50,000) client-side BEFORE the HTTP call so callers fail fast and avoid a wasted round-trip to the server (which enforces the same limit and returns 400 above it). Then calls PUT /api/app/projects/{pid}/business-context (project) or PUT /api/app/organizations/{org_id}/business-context (org).

The PUT is full-replace — pass an empty string to clear (or use clear_business_context for clarity).

PARAMETER	DESCRIPTION
`content`	New markdown content. Empty string clears the context at this scope. TYPE: `str`
`level`	`"project"` (default) or `"organization"`. TYPE: `Literal['organization', 'project']` DEFAULT: `'project'`
`organization_id`	Optional explicit org ID, only honored when `level="organization"`. Auto-resolved from `/me` when omitted. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`BusinessContext`	`BusinessContext` echoing the server's saved content.

RAISES	DESCRIPTION
`ValueError`	`level` is not `"organization"` or `"project"`.
`BusinessContextValidationError`	`len(content) > 50_000` (client-side check, no HTTP call made).
`ConfigError`	Credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Caller lacks `edit_project_info` permission (403) or other API error (400).
`ServerError`	Server-side errors (5xx).
`WorkspaceScopeError`	`level="organization"` and the org ID could not be auto-resolved.
`MixpanelHeadlessError`	API response is missing the `content` field.

Example

ws = Workspace()
ws.set_business_context("# Acme Corp\n...", level="project")
ws.set_business_context(
    "# Org-wide context", level="organization",
)

Source code in src/mixpanel_headless/workspace.py

def set_business_context(
    self,
    content: str,
    *,
    level: Literal["organization", "project"] = "project",
    organization_id: int | None = None,
) -> BusinessContext:
    """Replace business context content at the given scope.

    Validates ``len(content) <= BUSINESS_CONTEXT_MAX_CHARS`` (50,000)
    client-side BEFORE the HTTP call so callers fail fast and avoid
    a wasted round-trip to the server (which enforces the same limit
    and returns 400 above it). Then calls
    ``PUT /api/app/projects/{pid}/business-context`` (project) or
    ``PUT /api/app/organizations/{org_id}/business-context`` (org).

    The PUT is full-replace — pass an empty string to clear (or use
    ``clear_business_context`` for clarity).

    Args:
        content: New markdown content. Empty string clears the
            context at this scope.
        level: ``"project"`` (default) or ``"organization"``.
        organization_id: Optional explicit org ID, only honored
            when ``level="organization"``. Auto-resolved from
            ``/me`` when omitted.

    Returns:
        ``BusinessContext`` echoing the server's saved content.

    Raises:
        ValueError: ``level`` is not ``"organization"`` or ``"project"``.
        BusinessContextValidationError: ``len(content) > 50_000``
            (client-side check, no HTTP call made).
        ConfigError: Credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Caller lacks ``edit_project_info`` permission
            (403) or other API error (400).
        ServerError: Server-side errors (5xx).
        WorkspaceScopeError: ``level="organization"`` and the org
            ID could not be auto-resolved.
        MixpanelHeadlessError: API response is missing the ``content``
            field.

    Example:
        ```python
        ws = Workspace()
        ws.set_business_context("# Acme Corp\\n...", level="project")
        ws.set_business_context(
            "# Org-wide context", level="organization",
        )
        ```
    """
    self._validate_level(level)
    if len(content) > BUSINESS_CONTEXT_MAX_CHARS:
        raise BusinessContextValidationError(
            f"content exceeds maximum length of "
            f"{BUSINESS_CONTEXT_MAX_CHARS} characters (got {len(content)})",
            details={
                "length": len(content),
                "max": BUSINESS_CONTEXT_MAX_CHARS,
            },
        )
    client = self._require_api_client()
    if level == "organization":
        org_id = self._resolve_organization_id(organization_id)
        raw = client.set_business_context(content, organization_id=org_id)
        return BusinessContext(
            level="organization",
            content=self._require_str_field(
                raw,
                "content",
                method="set_business_context",
            ),
            organization_id=org_id,
        )
    raw = client.set_business_context(content)
    return BusinessContext(
        level="project",
        content=self._require_str_field(
            raw,
            "content",
            method="set_business_context",
        ),
        project_id=self._session.project.id,
    )

clear_business_context ¶

clear_business_context(
    *,
    level: Literal["organization", "project"] = "project",
    organization_id: int | None = None,
) -> BusinessContext

Clear business context at the given scope.

Convenience wrapper that calls set_business_context("", level=..., organization_id=...). Useful for documenting intent — equivalent to passing an empty string explicitly.

PARAMETER	DESCRIPTION
`level`	`"project"` (default) or `"organization"`. TYPE: `Literal['organization', 'project']` DEFAULT: `'project'`
`organization_id`	Optional explicit org ID for `level="organization"`. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`BusinessContext`	`BusinessContext` with `content=""` (the cleared state
`BusinessContext`	echoed back from the server).

RAISES	DESCRIPTION
`ValueError`	`level` is not `"organization"` or `"project"`.
`ConfigError`	Credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Caller lacks `edit_project_info` permission (403) or other API error (400).
`ServerError`	Server-side errors (5xx).
`WorkspaceScopeError`	`level="organization"` and the org ID could not be auto-resolved.

Example

ws = Workspace()
ws.clear_business_context(level="project")

Source code in src/mixpanel_headless/workspace.py

def clear_business_context(
    self,
    *,
    level: Literal["organization", "project"] = "project",
    organization_id: int | None = None,
) -> BusinessContext:
    """Clear business context at the given scope.

    Convenience wrapper that calls
    ``set_business_context("", level=..., organization_id=...)``.
    Useful for documenting intent — equivalent to passing an empty
    string explicitly.

    Args:
        level: ``"project"`` (default) or ``"organization"``.
        organization_id: Optional explicit org ID for
            ``level="organization"``.

    Returns:
        ``BusinessContext`` with ``content=""`` (the cleared state
        echoed back from the server).

    Raises:
        ValueError: ``level`` is not ``"organization"`` or ``"project"``.
        ConfigError: Credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Caller lacks ``edit_project_info`` permission
            (403) or other API error (400).
        ServerError: Server-side errors (5xx).
        WorkspaceScopeError: ``level="organization"`` and the org
            ID could not be auto-resolved.

    Example:
        ```python
        ws = Workspace()
        ws.clear_business_context(level="project")
        ```
    """
    return self.set_business_context(
        "",
        level=level,
        organization_id=organization_id,
    )

get_business_context_chain ¶

get_business_context_chain() -> BusinessContextChain

Read both organization and project business context together.

Issues exactly one App API request to GET /api/app/projects/{pid}/business-context/chain — a server-side convenience that returns both scopes for the active project. organization.organization_id is populated on a best-effort basis from the cached /me response (in-memory or disk); when the cache is cold it is left as None rather than triggering an extra /me round-trip. Callers that need a guaranteed org ID should use get_business_context(level= "organization"), which performs full resolution.

RETURNS	DESCRIPTION
`BusinessContextChain`	`BusinessContextChain` with populated `organization` and
`BusinessContextChain`	`project` fields. Either `content` may be empty when no
`BusinessContextChain`	context is set at that scope.
`BusinessContextChain`	`organization.organization_id` may be `None` when the
`BusinessContextChain`	`/me` cache is cold (see method description).

RAISES	DESCRIPTION
`ConfigError`	Credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Caller lacks project access (403, 404) or other API error (400).
`ServerError`	Server-side errors (5xx).
`MixpanelHeadlessError`	API response is missing `org_context` or `project_context`.

Example

ws = Workspace()
chain = ws.get_business_context_chain()
print("ORG:", chain.organization.content)
print("PROJECT:", chain.project.content)

Source code in src/mixpanel_headless/workspace.py

def get_business_context_chain(self) -> BusinessContextChain:
    """Read both organization and project business context together.

    Issues exactly one App API request to
    ``GET /api/app/projects/{pid}/business-context/chain`` —
    a server-side convenience that returns both scopes for the
    active project. ``organization.organization_id`` is populated
    on a best-effort basis from the cached ``/me`` response (in-memory
    or disk); when the cache is cold it is left as ``None`` rather
    than triggering an extra ``/me`` round-trip. Callers that need a
    guaranteed org ID should use ``get_business_context(level=
    "organization")``, which performs full resolution.

    Returns:
        ``BusinessContextChain`` with populated ``organization`` and
        ``project`` fields. Either ``content`` may be empty when no
        context is set at that scope.
        ``organization.organization_id`` may be ``None`` when the
        ``/me`` cache is cold (see method description).

    Raises:
        ConfigError: Credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Caller lacks project access (403, 404) or
            other API error (400).
        ServerError: Server-side errors (5xx).
        MixpanelHeadlessError: API response is missing ``org_context``
            or ``project_context``.

    Example:
        ```python
        ws = Workspace()
        chain = ws.get_business_context_chain()
        print("ORG:", chain.organization.content)
        print("PROJECT:", chain.project.content)
        ```
    """
    client = self._require_api_client()
    raw = client.get_business_context_chain()
    org_content = self._require_str_field(
        raw,
        "org_context",
        method="get_business_context_chain",
    )
    project_content = self._require_str_field(
        raw,
        "project_context",
        method="get_business_context_chain",
    )
    org_id = self._cached_organization_id()
    return BusinessContextChain(
        organization=BusinessContext(
            level="organization",
            content=org_content,
            organization_id=org_id,
        ),
        project=BusinessContext(
            level="project",
            content=project_content,
            project_id=self._session.project.id,
        ),
    )

query ¶

query(
    events: str
    | Metric
    | CohortMetric
    | FunnelMetric
    | RetentionMetric
    | MetricRef
    | SavedMetric
    | Formula
    | Sequence[
        str
        | Metric
        | CohortMetric
        | FunnelMetric
        | RetentionMetric
        | MetricRef
        | SavedMetric
        | Formula
    ],
    *,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: MathType = "total",
    math_property: str | None = None,
    per_user: PerUserAggregation | None = None,
    percentile_value: int | float | None = None,
    group_by: str
    | GroupBy
    | CohortBreakdown
    | FrequencyBreakdown
    | list[str | GroupBy | CohortBreakdown | FrequencyBreakdown]
    | None = None,
    where: Filter
    | FrequencyFilter
    | list[Filter | FrequencyFilter]
    | None = None,
    formula: str | None = None,
    formula_label: str | None = None,
    rolling: int | None = None,
    cumulative: bool = False,
    mode: Literal["timeseries", "total", "table"] = "timeseries",
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
    limit: int | None = None,
) -> QueryResult

Run a typed insights query against the Mixpanel API.

Generates bookmark params from keyword arguments, POSTs them inline to /api/query/insights, and returns a structured QueryResult with lazy DataFrame conversion.

PARAMETER	DESCRIPTION
`events`	Event name(s) to query. Accepts a single string, a Metric object, a CohortMetric object, a FunnelMetric, a RetentionMetric, a MetricRef or a SavedMetric (from `list_metrics` or `get_metric`), a Formula object, or a sequence mixing them. Formula objects in the list are extracted and appended as formula show clauses. A Formula with its own operands (`metrics=`) can be the only item. A Metric can count a custom event or more than one event as one series. `math`, `math_property`, and `per_user` apply to plain strings only: a CohortMetric always counts unique users (CM3), and a saved metric keeps its saved definition except for its own overrides. The params keep each saved metric as a reference, so the server expands the saved definition at query time. TYPE: `str \| Metric \| CohortMetric \| FunnelMetric \| RetentionMetric \| MetricRef \| SavedMetric \| Formula \| Sequence[str \| Metric \| CohortMetric \| FunnelMetric \| RetentionMetric \| MetricRef \| SavedMetric \| Formula]`
`from_date`	Start date (YYYY-MM-DD). If set, overrides `last`. TYPE: `str \| None` DEFAULT: `None`
`to_date`	End date (YYYY-MM-DD). Requires `from_date`. TYPE: `str \| None` DEFAULT: `None`
`last`	Relative time range in days. Default: 30. Ignored if `from_date` is set. TYPE: `int` DEFAULT: `30`
`unit`	Time aggregation unit. Default: `"day"`. TYPE: `QueryTimeUnit` DEFAULT: `'day'`
`math`	Aggregation function for plain-string events. Default: `"total"`. TYPE: `MathType` DEFAULT: `'total'`
`math_property`	Property name for property-based math (average, sum, percentiles). TYPE: `str \| None` DEFAULT: `None`
`per_user`	Per-user pre-aggregation (average, total, min, max). TYPE: `PerUserAggregation \| None` DEFAULT: `None`
`percentile_value`	Custom percentile value (e.g. 95 for p95). Required when `math="percentile"`. Maps to `percentile` in bookmark measurement. Ignored for other math types. TYPE: `int \| float \| None` DEFAULT: `None`
`group_by`	Break down results by property or cohort membership. Accepts a string, `GroupBy`, `CohortBreakdown`, or list of any mix. TYPE: `str \| GroupBy \| CohortBreakdown \| FrequencyBreakdown \| list[str \| GroupBy \| CohortBreakdown \| FrequencyBreakdown] \| None` DEFAULT: `None`
`where`	Filter results by conditions. Accepts a Filter, a FrequencyFilter, or a list mixing both. A `FrequencyFilter` threshold is evaluated per time bucket (`unit`), not over the whole date range: with the default `unit="day"` it keeps only users who reach the count within a single day, and an empty series is the expected result when nobody does. Choose the `unit` that matches the period you mean (`"day"` for "N times in a day", `"month"` for "N times in a month"); `unit="month"` over a multi-month range still yields one threshold per month, and "over the whole period" needs a date range that fits inside one bucket. See `FrequencyFilter`. TYPE: `Filter \| FrequencyFilter \| list[Filter \| FrequencyFilter] \| None` DEFAULT: `None`
`formula`	Formula expression referencing events by position (A, B, C...). Requires 2+ events. Cannot be combined with Formula objects in `events`. TYPE: `str \| None` DEFAULT: `None`
`formula_label`	Display label for formula result. TYPE: `str \| None` DEFAULT: `None`
`rolling`	Rolling window size in periods. Mutually exclusive with `cumulative`. TYPE: `int \| None` DEFAULT: `None`
`cumulative`	Enable cumulative analysis mode. Mutually exclusive with `rolling`. TYPE: `bool` DEFAULT: `False`
`mode`	Result shape. `"timeseries"` returns per-period data, `"total"` returns a single aggregate, `"table"` returns tabular data. Default: `"timeseries"`. TYPE: `Literal['timeseries', 'total', 'table']` DEFAULT: `'timeseries'`
`time_comparison`	Optional period-over-period comparison. Use `TimeComparison.relative("month")` for previous month, `TimeComparison.absolute_start("2026-01-01")` for a fixed start date, etc. Default: `None`. TYPE: `TimeComparison \| None` DEFAULT: `None`
`data_group_id`	Optional data group ID for group-level analytics. Scopes the query to a specific data group. Default: `None`. TYPE: `int \| None` DEFAULT: `None`
`limit`	Segments to return, 1 to 50000. Default `None` keeps the 3000 the Mixpanel UI uses. Raise it for a high-cardinality breakdown, and check `result.meta["is_segmentation_limit_hit"]` to see whether the answer was still truncated. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`QueryResult`	QueryResult with series data, DataFrame, and metadata.

RAISES	DESCRIPTION
`ValueError`	If arguments violate validation rules.
`ParamValidationError`	`events` holds a `WarehouseMetric`, which defines a saved warehouse metric and is not a query value (`MR3_WAREHOUSE_INLINE`); query it by reference.
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials.
`QueryError`	Invalid query parameters.
`RateLimitError`	Rate limit exceeded.

Example

ws = Workspace()

# Simple event query
result = ws.query("Login")
print(result.df.head())

# With aggregation and time range
result = ws.query("Login", math="unique", last=7, unit="day")

# Multi-event with formula (top-level parameter)
result = ws.query(
    [Metric("Signup", math="unique"), Metric("Purchase", math="unique")],
    formula="(B / A) * 100",
    formula_label="Conversion Rate",
)

# Multi-event with formula (Formula in list)
result = ws.query(
    [Metric("Signup", math="unique"),
     Metric("Purchase", math="unique"),
     Formula("(B / A) * 100", label="Conversion Rate")],
)

# A saved metric by id, with a report-level override
result = ws.query(MetricRef(88999, segment_method="first"))

Source code in src/mixpanel_headless/workspace.py

def query(
    self,
    events: str
    | Metric
    | CohortMetric
    | FunnelMetric
    | RetentionMetric
    | MetricRef
    | SavedMetric
    | Formula
    | Sequence[
        str
        | Metric
        | CohortMetric
        | FunnelMetric
        | RetentionMetric
        | MetricRef
        | SavedMetric
        | Formula
    ],
    *,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: MathType = "total",
    math_property: str | None = None,
    per_user: PerUserAggregation | None = None,
    percentile_value: int | float | None = None,
    group_by: str
    | GroupBy
    | CohortBreakdown
    | FrequencyBreakdown
    | list[str | GroupBy | CohortBreakdown | FrequencyBreakdown]
    | None = None,
    where: Filter | FrequencyFilter | list[Filter | FrequencyFilter] | None = None,
    formula: str | None = None,
    formula_label: str | None = None,
    rolling: int | None = None,
    cumulative: bool = False,
    mode: Literal["timeseries", "total", "table"] = "timeseries",
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
    limit: int | None = None,
) -> QueryResult:
    """Run a typed insights query against the Mixpanel API.

    Generates bookmark params from keyword arguments, POSTs them inline
    to ``/api/query/insights``, and returns a structured QueryResult
    with lazy DataFrame conversion.

    Args:
        events: Event name(s) to query. Accepts a single string,
            a Metric object, a CohortMetric object, a FunnelMetric,
            a RetentionMetric, a MetricRef or a SavedMetric (from
            ``list_metrics`` or ``get_metric``), a Formula object, or
            a sequence mixing them. Formula objects in the list are
            extracted and appended as formula show clauses. A Formula
            with its own operands (``metrics=``) can be the only
            item. A Metric can count a custom event or more than one
            event as one series. ``math``, ``math_property``, and
            ``per_user`` apply to plain strings only: a CohortMetric
            always counts unique users (CM3), and a saved metric keeps
            its saved definition except for its own overrides. The
            params keep each saved metric as a reference, so the
            server expands the saved definition at query time.
        from_date: Start date (YYYY-MM-DD). If set, overrides ``last``.
        to_date: End date (YYYY-MM-DD). Requires ``from_date``.
        last: Relative time range in days. Default: 30.
            Ignored if ``from_date`` is set.
        unit: Time aggregation unit. Default: ``"day"``.
        math: Aggregation function for plain-string events.
            Default: ``"total"``.
        math_property: Property name for property-based math
            (average, sum, percentiles).
        per_user: Per-user pre-aggregation (average, total, min, max).
        percentile_value: Custom percentile value (e.g. 95 for p95).
            Required when ``math="percentile"``. Maps to ``percentile``
            in bookmark measurement. Ignored for other math types.
        group_by: Break down results by property or cohort membership.
            Accepts a string, ``GroupBy``, ``CohortBreakdown``, or
            list of any mix.
        where: Filter results by conditions. Accepts a Filter, a
            FrequencyFilter, or a list mixing both. A
            ``FrequencyFilter`` threshold is evaluated per time
            bucket (``unit``), not over the whole date range: with
            the default ``unit="day"`` it keeps only users who reach
            the count within a single day, and an empty series is the
            expected result when nobody does. Choose the ``unit`` that
            matches the period you mean (``"day"`` for "N times in a
            day", ``"month"`` for "N times in a month");
            ``unit="month"`` over a multi-month range still yields one
            threshold per month, and "over the whole period" needs a
            date range that fits inside one bucket. See
            ``FrequencyFilter``.
        formula: Formula expression referencing events by position
            (A, B, C...). Requires 2+ events. Cannot be combined
            with Formula objects in ``events``.
        formula_label: Display label for formula result.
        rolling: Rolling window size in periods.
            Mutually exclusive with ``cumulative``.
        cumulative: Enable cumulative analysis mode.
            Mutually exclusive with ``rolling``.
        mode: Result shape. ``"timeseries"`` returns per-period data,
            ``"total"`` returns a single aggregate, ``"table"`` returns
            tabular data. Default: ``"timeseries"``.
        time_comparison: Optional period-over-period comparison.
            Use ``TimeComparison.relative("month")`` for previous
            month, ``TimeComparison.absolute_start("2026-01-01")``
            for a fixed start date, etc. Default: ``None``.
        data_group_id: Optional data group ID for group-level
            analytics. Scopes the query to a specific data group.
            Default: ``None``.
        limit: Segments to return, 1 to 50000. Default ``None`` keeps
            the 3000 the Mixpanel UI uses. Raise it for a
            high-cardinality breakdown, and check
            ``result.meta["is_segmentation_limit_hit"]`` to see whether
            the answer was still truncated.

    Returns:
        QueryResult with series data, DataFrame, and metadata.

    Raises:
        ValueError: If arguments violate validation rules.
        ParamValidationError: ``events`` holds a ``WarehouseMetric``,
            which defines a saved warehouse metric and is not a query
            value (``MR3_WAREHOUSE_INLINE``); query it by reference.
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials.
        QueryError: Invalid query parameters.
        RateLimitError: Rate limit exceeded.

    Example:
        ```python
        ws = Workspace()

        # Simple event query
        result = ws.query("Login")
        print(result.df.head())

        # With aggregation and time range
        result = ws.query("Login", math="unique", last=7, unit="day")

        # Multi-event with formula (top-level parameter)
        result = ws.query(
            [Metric("Signup", math="unique"), Metric("Purchase", math="unique")],
            formula="(B / A) * 100",
            formula_label="Conversion Rate",
        )

        # Multi-event with formula (Formula in list)
        result = ws.query(
            [Metric("Signup", math="unique"),
             Metric("Purchase", math="unique"),
             Formula("(B / A) * 100", label="Conversion Rate")],
        )

        # A saved metric by id, with a report-level override
        result = ws.query(MetricRef(88999, segment_method="first"))
        ```
    """
    params = self._resolve_and_build_params(
        events=events,
        from_date=from_date,
        to_date=to_date,
        last=last,
        unit=unit,
        math=math,
        math_property=math_property,
        per_user=per_user,
        percentile_value=percentile_value,
        group_by=group_by,
        where=where,
        formula=formula,
        formula_label=formula_label,
        rolling=rolling,
        cumulative=cumulative,
        mode=mode,
        time_comparison=time_comparison,
        data_group_id=data_group_id,
    )

    return self._live_query_service.query(
        bookmark_params=params,
        project_id=int(self._session.project.id),
        limit=limit,
    )

build_params ¶

build_params(
    events: str
    | Metric
    | CohortMetric
    | FunnelMetric
    | RetentionMetric
    | MetricRef
    | SavedMetric
    | Formula
    | Sequence[
        str
        | Metric
        | CohortMetric
        | FunnelMetric
        | RetentionMetric
        | MetricRef
        | SavedMetric
        | Formula
    ],
    *,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: MathType = "total",
    math_property: str | None = None,
    per_user: PerUserAggregation | None = None,
    percentile_value: int | float | None = None,
    group_by: str
    | GroupBy
    | CohortBreakdown
    | FrequencyBreakdown
    | list[str | GroupBy | CohortBreakdown | FrequencyBreakdown]
    | None = None,
    where: Filter
    | FrequencyFilter
    | list[Filter | FrequencyFilter]
    | None = None,
    formula: str | None = None,
    formula_label: str | None = None,
    rolling: int | None = None,
    cumulative: bool = False,
    mode: Literal["timeseries", "total", "table"] = "timeseries",
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
) -> dict[str, Any]

Build validated bookmark params without executing the API call.

Has the same signature as :meth:query but returns the generated bookmark params dict instead of querying the Mixpanel API. Useful for debugging, inspecting generated JSON, persisting via :meth:create_bookmark, or testing.

PARAMETER	DESCRIPTION
`events`	Event name(s) to query. Accepts a single string, a `Metric`, `CohortMetric`, `FunnelMetric`, `RetentionMetric`, `MetricRef`, `SavedMetric`, `Formula`, or a sequence mixing them. A `Formula` with its own operands can be the only item. A `MetricRef` or `SavedMetric` stays a reference in the params (`{"type", "id", "overrides"}`), so a report built from them follows the saved metric. TYPE: `str \| Metric \| CohortMetric \| FunnelMetric \| RetentionMetric \| MetricRef \| SavedMetric \| Formula \| Sequence[str \| Metric \| CohortMetric \| FunnelMetric \| RetentionMetric \| MetricRef \| SavedMetric \| Formula]`
`from_date`	Start date (YYYY-MM-DD). If set, overrides `last`. TYPE: `str \| None` DEFAULT: `None`
`to_date`	End date (YYYY-MM-DD). Requires `from_date`. TYPE: `str \| None` DEFAULT: `None`
`last`	Relative time range in days. Default: 30. TYPE: `int` DEFAULT: `30`
`unit`	Time aggregation unit. Default: `"day"`. TYPE: `QueryTimeUnit` DEFAULT: `'day'`
`math`	Aggregation function for plain-string events. Default: `"total"`. TYPE: `MathType` DEFAULT: `'total'`
`math_property`	Property name for property-based math. TYPE: `str \| None` DEFAULT: `None`
`per_user`	Per-user pre-aggregation. TYPE: `PerUserAggregation \| None` DEFAULT: `None`
`percentile_value`	Custom percentile value (e.g. 95). Required when `math="percentile"`. TYPE: `int \| float \| None` DEFAULT: `None`
`group_by`	Break down results by property or cohort membership. Accepts a string, `GroupBy`, `CohortBreakdown`, or list of any mix. TYPE: `str \| GroupBy \| CohortBreakdown \| FrequencyBreakdown \| list[str \| GroupBy \| CohortBreakdown \| FrequencyBreakdown] \| None` DEFAULT: `None`
`where`	Filter results by conditions. A `FrequencyFilter` threshold is evaluated per `unit` bucket, not over the whole date range; see `FrequencyFilter` and `query`. TYPE: `Filter \| FrequencyFilter \| list[Filter \| FrequencyFilter] \| None` DEFAULT: `None`
`formula`	Formula expression referencing events by position. TYPE: `str \| None` DEFAULT: `None`
`formula_label`	Display label for formula result. TYPE: `str \| None` DEFAULT: `None`
`rolling`	Rolling window size in periods. TYPE: `int \| None` DEFAULT: `None`
`cumulative`	Enable cumulative analysis mode. TYPE: `bool` DEFAULT: `False`
`mode`	Result shape. Default: `"timeseries"`. TYPE: `Literal['timeseries', 'total', 'table']` DEFAULT: `'timeseries'`
`time_comparison`	Optional period-over-period comparison. Use `TimeComparison.relative("month")` for previous month, etc. Default: `None`. TYPE: `TimeComparison \| None` DEFAULT: `None`
`data_group_id`	Optional data group ID for group-level analytics. Scopes the query to a specific data group. Default: `None`. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict[str, Any]`	Bookmark params dict with `sections` and `displayOptions`
`dict[str, Any]`	keys, ready for use with the insights API or
`dict[str, Any]`	meth:`create_bookmark`.

RAISES	DESCRIPTION
`BookmarkValidationError`	If arguments violate validation rules.
`ParamValidationError`	`events` holds a `WarehouseMetric` (`MR3_WAREHOUSE_INLINE`); query it by reference.

Example

ws = Workspace()

# Inspect generated bookmark JSON
params = ws.build_params("Login", math="unique", last=7)
print(json.dumps(params, indent=2))

# Save as a bookmark (dashboard_id required)
ws.create_bookmark(CreateBookmarkParams(
    name="Daily Unique Logins",
    bookmark_type="insights",
    params=params,
    dashboard_id=12345,
))

Source code in src/mixpanel_headless/workspace.py

def build_params(
    self,
    events: str
    | Metric
    | CohortMetric
    | FunnelMetric
    | RetentionMetric
    | MetricRef
    | SavedMetric
    | Formula
    | Sequence[
        str
        | Metric
        | CohortMetric
        | FunnelMetric
        | RetentionMetric
        | MetricRef
        | SavedMetric
        | Formula
    ],
    *,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: MathType = "total",
    math_property: str | None = None,
    per_user: PerUserAggregation | None = None,
    percentile_value: int | float | None = None,
    group_by: str
    | GroupBy
    | CohortBreakdown
    | FrequencyBreakdown
    | list[str | GroupBy | CohortBreakdown | FrequencyBreakdown]
    | None = None,
    where: Filter | FrequencyFilter | list[Filter | FrequencyFilter] | None = None,
    formula: str | None = None,
    formula_label: str | None = None,
    rolling: int | None = None,
    cumulative: bool = False,
    mode: Literal["timeseries", "total", "table"] = "timeseries",
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
) -> dict[str, Any]:
    """Build validated bookmark params without executing the API call.

    Has the same signature as :meth:`query` but returns the generated
    bookmark params dict instead of querying the Mixpanel API. Useful
    for debugging, inspecting generated JSON, persisting via
    :meth:`create_bookmark`, or testing.

    Args:
        events: Event name(s) to query. Accepts a single string,
            a ``Metric``, ``CohortMetric``, ``FunnelMetric``,
            ``RetentionMetric``, ``MetricRef``, ``SavedMetric``,
            ``Formula``, or a sequence mixing them. A ``Formula`` with
            its own operands can be the only item. A ``MetricRef`` or
            ``SavedMetric`` stays a reference in the params
            (``{"type", "id", "overrides"}``), so a report built from
            them follows the saved metric.
        from_date: Start date (YYYY-MM-DD). If set, overrides ``last``.
        to_date: End date (YYYY-MM-DD). Requires ``from_date``.
        last: Relative time range in days. Default: 30.
        unit: Time aggregation unit. Default: ``"day"``.
        math: Aggregation function for plain-string events.
            Default: ``"total"``.
        math_property: Property name for property-based math.
        per_user: Per-user pre-aggregation.
        percentile_value: Custom percentile value (e.g. 95).
            Required when ``math="percentile"``.
        group_by: Break down results by property or cohort membership.
            Accepts a string, ``GroupBy``, ``CohortBreakdown``, or
            list of any mix.
        where: Filter results by conditions. A ``FrequencyFilter``
            threshold is evaluated per ``unit`` bucket, not over the
            whole date range; see ``FrequencyFilter`` and ``query``.
        formula: Formula expression referencing events by position.
        formula_label: Display label for formula result.
        rolling: Rolling window size in periods.
        cumulative: Enable cumulative analysis mode.
        mode: Result shape. Default: ``"timeseries"``.
        time_comparison: Optional period-over-period comparison.
            Use ``TimeComparison.relative("month")`` for previous
            month, etc. Default: ``None``.
        data_group_id: Optional data group ID for group-level
            analytics. Scopes the query to a specific data group.
            Default: ``None``.

    Returns:
        Bookmark params dict with ``sections`` and ``displayOptions``
        keys, ready for use with the insights API or
        :meth:`create_bookmark`.

    Raises:
        BookmarkValidationError: If arguments violate validation rules.
        ParamValidationError: ``events`` holds a ``WarehouseMetric``
            (``MR3_WAREHOUSE_INLINE``); query it by reference.

    Example:
        ```python
        ws = Workspace()

        # Inspect generated bookmark JSON
        params = ws.build_params("Login", math="unique", last=7)
        print(json.dumps(params, indent=2))

        # Save as a bookmark (dashboard_id required)
        ws.create_bookmark(CreateBookmarkParams(
            name="Daily Unique Logins",
            bookmark_type="insights",
            params=params,
            dashboard_id=12345,
        ))
        ```
    """
    return self._resolve_and_build_params(
        events=events,
        from_date=from_date,
        to_date=to_date,
        last=last,
        unit=unit,
        math=math,
        math_property=math_property,
        per_user=per_user,
        percentile_value=percentile_value,
        group_by=group_by,
        where=where,
        formula=formula,
        formula_label=formula_label,
        rolling=rolling,
        cumulative=cumulative,
        mode=mode,
        time_comparison=time_comparison,
        data_group_id=data_group_id,
    )

run_params ¶

run_params(
    params: dict[str, Any],
    *,
    limit: int | None = None,
    workspace_id: int | None = None,
) -> QueryResult

Run pre-built insights bookmark params against the Mixpanel API.

The execution half of :meth:build_params. Use it when the params need editing before they run, or when they express something the typed builders do not cover, such as a lookup-table join breakdown.

PARAMETER	DESCRIPTION
`params`	Bookmark params dict, normally from :meth:`build_params`. Sent as the request `bookmark`. TYPE: `dict[str, Any]`
`limit`	Segments to return, 1 to 50000. Default `None` keeps the 3000 the Mixpanel UI uses. TYPE: `int \| None` DEFAULT: `None`
`workspace_id`	Optional data view to run under. Wins over the pinned session workspace. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`QueryResult`	QueryResult with series data, DataFrame, and metadata.

RAISES	DESCRIPTION
`ValueError`	`limit` is not an integer from 1 to 50000.
`AuthenticationError`	Invalid credentials.
`QueryError`	Invalid bookmark params.
`RateLimitError`	Rate limit exceeded.

Example

params = ws.build_params("Login", group_by="$city", last=7)
params["sections"]["filter"] = my_custom_filter
result = ws.run_params(params, limit=50_000)

Source code in src/mixpanel_headless/workspace.py

def run_params(
    self,
    params: dict[str, Any],
    *,
    limit: int | None = None,
    workspace_id: int | None = None,
) -> QueryResult:
    """Run pre-built insights bookmark params against the Mixpanel API.

    The execution half of :meth:`build_params`. Use it when the params
    need editing before they run, or when they express something the
    typed builders do not cover, such as a lookup-table join breakdown.

    Args:
        params: Bookmark params dict, normally from
            :meth:`build_params`. Sent as the request ``bookmark``.
        limit: Segments to return, 1 to 50000. Default ``None`` keeps
            the 3000 the Mixpanel UI uses.
        workspace_id: Optional data view to run under. Wins over the
            pinned session workspace.

    Returns:
        QueryResult with series data, DataFrame, and metadata.

    Raises:
        ValueError: ``limit`` is not an integer from 1 to 50000.
        AuthenticationError: Invalid credentials.
        QueryError: Invalid bookmark params.
        RateLimitError: Rate limit exceeded.

    Example:
        ```python
        params = ws.build_params("Login", group_by="$city", last=7)
        params["sections"]["filter"] = my_custom_filter
        result = ws.run_params(params, limit=50_000)
        ```
    """
    return self._live_query_service.query(
        bookmark_params=params,
        project_id=int(self._session.project.id),
        limit=limit,
        workspace_id=workspace_id,
    )

query_funnel ¶

query_funnel(
    steps: list[str | FunnelStep] | BehaviorRef | SavedBehavior,
    *,
    conversion_window: int = 14,
    conversion_window_unit: Literal[
        "second", "minute", "hour", "day", "week", "month", "session"
    ] = "day",
    order: Literal["loose", "any"] = "loose",
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: FunnelMathType = "conversion_rate_unique",
    math_property: str | None = None,
    group_by: str
    | GroupBy
    | CohortBreakdown
    | list[str | GroupBy | CohortBreakdown]
    | None = None,
    where: Filter | list[Filter] | None = None,
    exclusions: list[str | Exclusion] | None = None,
    holding_constant: str
    | HoldingConstant
    | list[str | HoldingConstant]
    | None = None,
    mode: Literal["steps", "trends", "table"] = "steps",
    reentry_mode: FunnelReentryMode | None = None,
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
    limit: int | None = None,
) -> FunnelQueryResult

Run a typed funnel query against the Mixpanel API.

Generates funnel bookmark params from keyword arguments, POSTs them inline to /api/query/insights, and returns a structured FunnelQueryResult with lazy DataFrame conversion.

PARAMETER	DESCRIPTION
`steps`	Funnel step specifications. At least 2 required. Accepts event name strings or `FunnelStep` objects for per-step filters, labels, and ordering. A `BehaviorRef` or `SavedBehavior` for a saved funnel behavior replaces the list: the saved behavior sets the steps, the conversion window, the order, the exclusions, the held properties, and the reentry mode, so those arguments must keep their defaults (`F14_BEHAVIOR_REF_SETTINGS`). TYPE: `list[str \| FunnelStep] \| BehaviorRef \| SavedBehavior`
`conversion_window`	How long users have to complete the funnel. Default: 14. TYPE: `int` DEFAULT: `14`
`conversion_window_unit`	Time unit for conversion window. Default: `"day"`. TYPE: `Literal['second', 'minute', 'hour', 'day', 'week', 'month', 'session']` DEFAULT: `'day'`
`order`	Step ordering mode. `"loose"` requires steps in order but allows other events between. `"any"` allows steps in any order. Default: `"loose"`. TYPE: `Literal['loose', 'any']` DEFAULT: `'loose'`
`from_date`	Start date (YYYY-MM-DD). If set, overrides `last`. TYPE: `str \| None` DEFAULT: `None`
`to_date`	End date (YYYY-MM-DD). Requires `from_date`. TYPE: `str \| None` DEFAULT: `None`
`last`	Relative time range in days. Default: 30. TYPE: `int` DEFAULT: `30`
`unit`	Time aggregation unit. Default: `"day"`. TYPE: `QueryTimeUnit` DEFAULT: `'day'`
`math`	Funnel aggregation function. Default: `"conversion_rate_unique"`. TYPE: `FunnelMathType` DEFAULT: `'conversion_rate_unique'`
`math_property`	Numeric property name for property-aggregation math types (`"average"`, `"median"`, `"min"`, `"max"`, `"p25"`, `"p75"`, `"p90"`, `"p99"`). Required when using those math types; must be `None` for count/rate math types. Default: `None`. TYPE: `str \| None` DEFAULT: `None`
`group_by`	Break down results by property or cohort membership. Accepts a string, `GroupBy`, `CohortBreakdown`, or list of any mix. TYPE: `str \| GroupBy \| CohortBreakdown \| list[str \| GroupBy \| CohortBreakdown] \| None` DEFAULT: `None`
`where`	Filter results by conditions. TYPE: `Filter \| list[Filter] \| None` DEFAULT: `None`
`exclusions`	Events to exclude between steps. Accepts event name strings or `Exclusion` objects. TYPE: `list[str \| Exclusion] \| None` DEFAULT: `None`
`holding_constant`	Properties to hold constant across steps. Accepts strings, `HoldingConstant` objects, or a list mixing both. TYPE: `str \| HoldingConstant \| list[str \| HoldingConstant] \| None` DEFAULT: `None`
`mode`	Result display mode. `"steps"` shows step-level data, `"trends"` shows conversion over time, `"table"` shows tabular breakdown. Default: `"steps"`. TYPE: `Literal['steps', 'trends', 'table']` DEFAULT: `'steps'`
`reentry_mode`	Funnel reentry mode controlling how users re-enter the funnel after conversion. One of `"default"`, `"basic"`, `"aggressive"`, or `"optimized"`. Default: `None` (server default). TYPE: `FunnelReentryMode \| None` DEFAULT: `None`
`time_comparison`	Optional period-over-period comparison. Use `TimeComparison.relative("month")` for previous month, etc. Default: `None`. TYPE: `TimeComparison \| None` DEFAULT: `None`
`data_group_id`	Optional data group ID for group-level analytics. Scopes the query to a specific data group. Default: `None`. TYPE: `int \| None` DEFAULT: `None`
`limit`	Segments to return, 1 to 50000. Default `None` keeps the 3000 the Mixpanel UI uses. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`FunnelQueryResult`	FunnelQueryResult with step data, DataFrame, and metadata.

RAISES	DESCRIPTION
`ValueError`	`limit` is not an integer from 1 to 50000.
`BookmarkValidationError`	If arguments violate validation rules (before API call).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials.
`QueryError`	Invalid query parameters.
`RateLimitError`	Rate limit exceeded.

Example

ws = Workspace()

# Simple two-step funnel
result = ws.query_funnel(["Signup", "Purchase"])
print(result.overall_conversion_rate)

# Configured funnel
result = ws.query_funnel(
    ["Signup", "Add to Cart", "Checkout", "Purchase"],
    conversion_window=7,
    order="loose",
    last=90,
)
print(result.df)

# A saved funnel behavior by id
result = ws.query_funnel(BehaviorRef(3120, "funnel"), last=90)

Source code in src/mixpanel_headless/workspace.py

def query_funnel(
    self,
    steps: list[str | FunnelStep] | BehaviorRef | SavedBehavior,
    *,
    conversion_window: int = 14,
    conversion_window_unit: Literal[
        "second", "minute", "hour", "day", "week", "month", "session"
    ] = "day",
    order: Literal["loose", "any"] = "loose",
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: FunnelMathType = "conversion_rate_unique",
    math_property: str | None = None,
    group_by: str
    | GroupBy
    | CohortBreakdown
    | list[str | GroupBy | CohortBreakdown]
    | None = None,
    where: Filter | list[Filter] | None = None,
    exclusions: list[str | Exclusion] | None = None,
    holding_constant: (
        str | HoldingConstant | list[str | HoldingConstant] | None
    ) = None,
    mode: Literal["steps", "trends", "table"] = "steps",
    reentry_mode: FunnelReentryMode | None = None,
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
    limit: int | None = None,
) -> FunnelQueryResult:
    """Run a typed funnel query against the Mixpanel API.

    Generates funnel bookmark params from keyword arguments, POSTs
    them inline to ``/api/query/insights``, and returns a structured
    FunnelQueryResult with lazy DataFrame conversion.

    Args:
        steps: Funnel step specifications. At least 2 required.
            Accepts event name strings or ``FunnelStep`` objects
            for per-step filters, labels, and ordering. A
            ``BehaviorRef`` or ``SavedBehavior`` for a saved funnel
            behavior replaces the list: the saved behavior sets the
            steps, the conversion window, the order, the exclusions,
            the held properties, and the reentry mode, so those
            arguments must keep their defaults
            (``F14_BEHAVIOR_REF_SETTINGS``).
        conversion_window: How long users have to complete the
            funnel. Default: 14.
        conversion_window_unit: Time unit for conversion window.
            Default: ``"day"``.
        order: Step ordering mode. ``"loose"`` requires steps in
            order but allows other events between. ``"any"`` allows
            steps in any order. Default: ``"loose"``.
        from_date: Start date (YYYY-MM-DD). If set, overrides
            ``last``.
        to_date: End date (YYYY-MM-DD). Requires ``from_date``.
        last: Relative time range in days. Default: 30.
        unit: Time aggregation unit. Default: ``"day"``.
        math: Funnel aggregation function. Default:
            ``"conversion_rate_unique"``.
        math_property: Numeric property name for property-aggregation
            math types (``"average"``, ``"median"``, ``"min"``,
            ``"max"``, ``"p25"``, ``"p75"``, ``"p90"``, ``"p99"``).
            Required when using those math types; must be ``None``
            for count/rate math types. Default: ``None``.
        group_by: Break down results by property or cohort
            membership. Accepts a string, ``GroupBy``,
            ``CohortBreakdown``, or list of any mix.
        where: Filter results by conditions.
        exclusions: Events to exclude between steps. Accepts
            event name strings or ``Exclusion`` objects.
        holding_constant: Properties to hold constant across
            steps. Accepts strings, ``HoldingConstant`` objects,
            or a list mixing both.
        mode: Result display mode. ``"steps"`` shows step-level
            data, ``"trends"`` shows conversion over time,
            ``"table"`` shows tabular breakdown. Default:
            ``"steps"``.
        reentry_mode: Funnel reentry mode controlling how users
            re-enter the funnel after conversion. One of
            ``"default"``, ``"basic"``, ``"aggressive"``, or
            ``"optimized"``. Default: ``None`` (server default).
        time_comparison: Optional period-over-period comparison.
            Use ``TimeComparison.relative("month")`` for previous
            month, etc. Default: ``None``.
        data_group_id: Optional data group ID for group-level
            analytics. Scopes the query to a specific data group.
            Default: ``None``.
        limit: Segments to return, 1 to 50000. Default ``None`` keeps
            the 3000 the Mixpanel UI uses.

    Returns:
        FunnelQueryResult with step data, DataFrame, and metadata.

    Raises:
        ValueError: ``limit`` is not an integer from 1 to 50000.
        BookmarkValidationError: If arguments violate validation
            rules (before API call).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials.
        QueryError: Invalid query parameters.
        RateLimitError: Rate limit exceeded.

    Example:
        ```python
        ws = Workspace()

        # Simple two-step funnel
        result = ws.query_funnel(["Signup", "Purchase"])
        print(result.overall_conversion_rate)

        # Configured funnel
        result = ws.query_funnel(
            ["Signup", "Add to Cart", "Checkout", "Purchase"],
            conversion_window=7,
            order="loose",
            last=90,
        )
        print(result.df)

        # A saved funnel behavior by id
        result = ws.query_funnel(BehaviorRef(3120, "funnel"), last=90)
        ```
    """
    params = self._resolve_and_build_funnel_params(
        steps=steps,
        conversion_window=conversion_window,
        conversion_window_unit=conversion_window_unit,
        order=order,
        math=math,
        math_property=math_property,
        from_date=from_date,
        to_date=to_date,
        last=last,
        unit=unit,
        group_by=group_by,
        where=where,
        exclusions=exclusions,
        holding_constant=holding_constant,
        mode=mode,
        reentry_mode=reentry_mode,
        time_comparison=time_comparison,
        data_group_id=data_group_id,
    )

    return self._live_query_service.query_funnel(
        bookmark_params=params,
        project_id=int(self._session.project.id),
        limit=limit,
    )

build_funnel_params ¶

build_funnel_params(
    steps: list[str | FunnelStep] | BehaviorRef | SavedBehavior,
    *,
    conversion_window: int = 14,
    conversion_window_unit: Literal[
        "second", "minute", "hour", "day", "week", "month", "session"
    ] = "day",
    order: Literal["loose", "any"] = "loose",
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: FunnelMathType = "conversion_rate_unique",
    math_property: str | None = None,
    group_by: str
    | GroupBy
    | CohortBreakdown
    | list[str | GroupBy | CohortBreakdown]
    | None = None,
    where: Filter | list[Filter] | None = None,
    exclusions: list[str | Exclusion] | None = None,
    holding_constant: str
    | HoldingConstant
    | list[str | HoldingConstant]
    | None = None,
    mode: Literal["steps", "trends", "table"] = "steps",
    reentry_mode: FunnelReentryMode | None = None,
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
) -> dict[str, Any]

Build validated funnel bookmark params without executing.

Has the same signature as :meth:query_funnel but returns the generated bookmark params dict instead of querying the API. Useful for debugging, inspecting generated JSON, persisting via :meth:create_bookmark, or testing.

PARAMETER	DESCRIPTION
`steps`	Funnel step specifications. At least 2 required. A `BehaviorRef` or `SavedBehavior` for a saved funnel behavior replaces the list; see :meth:`query_funnel`. TYPE: `list[str \| FunnelStep] \| BehaviorRef \| SavedBehavior`
`conversion_window`	Conversion window size. Default: 14. TYPE: `int` DEFAULT: `14`
`conversion_window_unit`	Time unit. Default: `"day"`. TYPE: `Literal['second', 'minute', 'hour', 'day', 'week', 'month', 'session']` DEFAULT: `'day'`
`order`	Step ordering mode. Default: `"loose"`. TYPE: `Literal['loose', 'any']` DEFAULT: `'loose'`
`from_date`	Start date (YYYY-MM-DD) or None. TYPE: `str \| None` DEFAULT: `None`
`to_date`	End date (YYYY-MM-DD) or None. TYPE: `str \| None` DEFAULT: `None`
`last`	Relative time range in days. Default: 30. TYPE: `int` DEFAULT: `30`
`unit`	Time aggregation unit. Default: `"day"`. TYPE: `QueryTimeUnit` DEFAULT: `'day'`
`math`	Aggregation function. Default: `"conversion_rate_unique"`. TYPE: `FunnelMathType` DEFAULT: `'conversion_rate_unique'`
`math_property`	Numeric property name for property-aggregation math types. Required for `"average"`, `"median"`, etc. Default: `None`. TYPE: `str \| None` DEFAULT: `None`
`group_by`	Break down results by property or cohort membership. Accepts a string, `GroupBy`, `CohortBreakdown`, or list of any mix. TYPE: `str \| GroupBy \| CohortBreakdown \| list[str \| GroupBy \| CohortBreakdown] \| None` DEFAULT: `None`
`where`	Filter results by conditions. TYPE: `Filter \| list[Filter] \| None` DEFAULT: `None`
`exclusions`	Events to exclude between steps. TYPE: `list[str \| Exclusion] \| None` DEFAULT: `None`
`holding_constant`	Properties to hold constant. TYPE: `str \| HoldingConstant \| list[str \| HoldingConstant] \| None` DEFAULT: `None`
`mode`	Display mode. Default: `"steps"`. TYPE: `Literal['steps', 'trends', 'table']` DEFAULT: `'steps'`
`reentry_mode`	Funnel reentry mode controlling how users re-enter the funnel after conversion. One of `"default"`, `"basic"`, `"aggressive"`, or `"optimized"`. Default: `None` (server default). TYPE: `FunnelReentryMode \| None` DEFAULT: `None`
`time_comparison`	Optional period-over-period comparison. Use `TimeComparison.relative("month")` for previous month, etc. Default: `None`. TYPE: `TimeComparison \| None` DEFAULT: `None`
`data_group_id`	Optional data group ID for group-level analytics. Scopes the query to a specific data group. Default: `None`. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict[str, Any]`	Bookmark params dict with `sections` and
`dict[str, Any]`	`displayOptions` keys.

RAISES	DESCRIPTION
`BookmarkValidationError`	If arguments violate validation rules.

Example

ws = Workspace()

# Inspect generated JSON
params = ws.build_funnel_params(["Signup", "Purchase"])
print(json.dumps(params, indent=2))

# Save as a report (dashboard_id required)
ws.create_bookmark(CreateBookmarkParams(
    name="Signup → Purchase Funnel",
    bookmark_type="funnels",
    params=params,
    dashboard_id=12345,
))

Source code in src/mixpanel_headless/workspace.py

def build_funnel_params(
    self,
    steps: list[str | FunnelStep] | BehaviorRef | SavedBehavior,
    *,
    conversion_window: int = 14,
    conversion_window_unit: Literal[
        "second", "minute", "hour", "day", "week", "month", "session"
    ] = "day",
    order: Literal["loose", "any"] = "loose",
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: FunnelMathType = "conversion_rate_unique",
    math_property: str | None = None,
    group_by: str
    | GroupBy
    | CohortBreakdown
    | list[str | GroupBy | CohortBreakdown]
    | None = None,
    where: Filter | list[Filter] | None = None,
    exclusions: list[str | Exclusion] | None = None,
    holding_constant: (
        str | HoldingConstant | list[str | HoldingConstant] | None
    ) = None,
    mode: Literal["steps", "trends", "table"] = "steps",
    reentry_mode: FunnelReentryMode | None = None,
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
) -> dict[str, Any]:
    """Build validated funnel bookmark params without executing.

    Has the same signature as :meth:`query_funnel` but returns the
    generated bookmark params dict instead of querying the API.
    Useful for debugging, inspecting generated JSON, persisting
    via :meth:`create_bookmark`, or testing.

    Args:
        steps: Funnel step specifications. At least 2 required.
            A ``BehaviorRef`` or ``SavedBehavior`` for a saved funnel
            behavior replaces the list; see :meth:`query_funnel`.
        conversion_window: Conversion window size. Default: 14.
        conversion_window_unit: Time unit. Default: ``"day"``.
        order: Step ordering mode. Default: ``"loose"``.
        from_date: Start date (YYYY-MM-DD) or None.
        to_date: End date (YYYY-MM-DD) or None.
        last: Relative time range in days. Default: 30.
        unit: Time aggregation unit. Default: ``"day"``.
        math: Aggregation function. Default:
            ``"conversion_rate_unique"``.
        math_property: Numeric property name for property-aggregation
            math types. Required for ``"average"``, ``"median"``,
            etc. Default: ``None``.
        group_by: Break down results by property or cohort
            membership. Accepts a string, ``GroupBy``,
            ``CohortBreakdown``, or list of any mix.
        where: Filter results by conditions.
        exclusions: Events to exclude between steps.
        holding_constant: Properties to hold constant.
        mode: Display mode. Default: ``"steps"``.
        reentry_mode: Funnel reentry mode controlling how users
            re-enter the funnel after conversion. One of
            ``"default"``, ``"basic"``, ``"aggressive"``, or
            ``"optimized"``. Default: ``None`` (server default).
        time_comparison: Optional period-over-period comparison.
            Use ``TimeComparison.relative("month")`` for previous
            month, etc. Default: ``None``.
        data_group_id: Optional data group ID for group-level
            analytics. Scopes the query to a specific data group.
            Default: ``None``.

    Returns:
        Bookmark params dict with ``sections`` and
        ``displayOptions`` keys.

    Raises:
        BookmarkValidationError: If arguments violate validation
            rules.

    Example:
        ```python
        ws = Workspace()

        # Inspect generated JSON
        params = ws.build_funnel_params(["Signup", "Purchase"])
        print(json.dumps(params, indent=2))

        # Save as a report (dashboard_id required)
        ws.create_bookmark(CreateBookmarkParams(
            name="Signup → Purchase Funnel",
            bookmark_type="funnels",
            params=params,
            dashboard_id=12345,
        ))
        ```
    """
    return self._resolve_and_build_funnel_params(
        steps=steps,
        conversion_window=conversion_window,
        conversion_window_unit=conversion_window_unit,
        order=order,
        math=math,
        math_property=math_property,
        from_date=from_date,
        to_date=to_date,
        last=last,
        unit=unit,
        group_by=group_by,
        where=where,
        exclusions=exclusions,
        holding_constant=holding_constant,
        mode=mode,
        reentry_mode=reentry_mode,
        time_comparison=time_comparison,
        data_group_id=data_group_id,
    )

run_funnel_params ¶

run_funnel_params(
    params: dict[str, Any],
    *,
    limit: int | None = None,
    workspace_id: int | None = None,
) -> FunnelQueryResult

Run pre-built funnel bookmark params against the Mixpanel API.

The execution half of :meth:build_funnel_params.

PARAMETER	DESCRIPTION
`params`	Funnel bookmark params dict, normally from :meth:`build_funnel_params`. Sent as the request `bookmark`. TYPE: `dict[str, Any]`
`limit`	Segments to return, 1 to 50000. Default `None` keeps the 3000 the Mixpanel UI uses. TYPE: `int \| None` DEFAULT: `None`
`workspace_id`	Optional data view to run under. Wins over the pinned session workspace. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`FunnelQueryResult`	FunnelQueryResult with step data, DataFrame, and metadata.

RAISES	DESCRIPTION
`ValueError`	`limit` is not an integer from 1 to 50000.
`AuthenticationError`	Invalid credentials.
`QueryError`	Invalid bookmark params.
`RateLimitError`	Rate limit exceeded.

Example

params = ws.build_funnel_params(["Signup", "Purchase"])
result = ws.run_funnel_params(params, limit=50_000)

Source code in src/mixpanel_headless/workspace.py

def run_funnel_params(
    self,
    params: dict[str, Any],
    *,
    limit: int | None = None,
    workspace_id: int | None = None,
) -> FunnelQueryResult:
    """Run pre-built funnel bookmark params against the Mixpanel API.

    The execution half of :meth:`build_funnel_params`.

    Args:
        params: Funnel bookmark params dict, normally from
            :meth:`build_funnel_params`. Sent as the request
            ``bookmark``.
        limit: Segments to return, 1 to 50000. Default ``None`` keeps
            the 3000 the Mixpanel UI uses.
        workspace_id: Optional data view to run under. Wins over the
            pinned session workspace.

    Returns:
        FunnelQueryResult with step data, DataFrame, and metadata.

    Raises:
        ValueError: ``limit`` is not an integer from 1 to 50000.
        AuthenticationError: Invalid credentials.
        QueryError: Invalid bookmark params.
        RateLimitError: Rate limit exceeded.

    Example:
        ```python
        params = ws.build_funnel_params(["Signup", "Purchase"])
        result = ws.run_funnel_params(params, limit=50_000)
        ```
    """
    return self._live_query_service.query_funnel(
        bookmark_params=params,
        project_id=int(self._session.project.id),
        limit=limit,
        workspace_id=workspace_id,
    )

query_retention ¶

query_retention(
    born_event: str | RetentionEvent | BehaviorRef | SavedBehavior,
    return_event: str | RetentionEvent | None = None,
    *,
    retention_unit: TimeUnit = "week",
    alignment: RetentionAlignment = "birth",
    bucket_sizes: list[int] | None = None,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: RetentionMathType = "retention_rate",
    group_by: str
    | GroupBy
    | CohortBreakdown
    | list[str | GroupBy | CohortBreakdown]
    | None = None,
    where: Filter | list[Filter] | None = None,
    mode: RetentionMode = "curve",
    unbounded_mode: RetentionUnboundedMode | None = None,
    retention_cumulative: bool = False,
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
    limit: int | None = None,
) -> RetentionQueryResult

Run a typed retention query against the Mixpanel API.

Generates retention bookmark params from keyword arguments, POSTs them inline to /api/query/insights, and returns a structured RetentionQueryResult with lazy DataFrame conversion.

PARAMETER	DESCRIPTION
`born_event`	Event that defines cohort membership. Accepts an event name string or a `RetentionEvent` object for per-event filters. A `BehaviorRef` or `SavedBehavior` for a saved retention behavior replaces both events: the saved behavior sets the events, the retention unit, the alignment, the buckets, and the unbounded mode, so `return_event` stays `None` and those arguments keep their defaults (`R15_BEHAVIOR_REF_SETTINGS`). TYPE: `str \| RetentionEvent \| BehaviorRef \| SavedBehavior`
`return_event`	Event that defines return. Accepts an event name string or a `RetentionEvent` object. Required unless `born_event` is a `BehaviorRef`. TYPE: `str \| RetentionEvent \| None` DEFAULT: `None`
`retention_unit`	Retention period unit. Default: `"week"`. TYPE: `TimeUnit` DEFAULT: `'week'`
`alignment`	Retention alignment mode. Default: `"birth"`. TYPE: `RetentionAlignment` DEFAULT: `'birth'`
`bucket_sizes`	Custom bucket sizes (positive ints in ascending order). Default: `None` (uniform buckets). TYPE: `list[int] \| None` DEFAULT: `None`
`from_date`	Start date (YYYY-MM-DD). If set, overrides `last`. TYPE: `str \| None` DEFAULT: `None`
`to_date`	End date (YYYY-MM-DD). Requires `from_date`. TYPE: `str \| None` DEFAULT: `None`
`last`	Relative time range in days. Default: 30. TYPE: `int` DEFAULT: `30`
`unit`	Time aggregation unit (`day`, `week`, or `month` — `hour` is not supported for retention). Default: `"day"`. TYPE: `QueryTimeUnit` DEFAULT: `'day'`
`math`	Retention aggregation function. Default: `"retention_rate"`. TYPE: `RetentionMathType` DEFAULT: `'retention_rate'`
`group_by`	Break down results by property or cohort membership. Accepts a string, `GroupBy`, `CohortBreakdown`, or list of any mix. TYPE: `str \| GroupBy \| CohortBreakdown \| list[str \| GroupBy \| CohortBreakdown] \| None` DEFAULT: `None`
`where`	Filter results by conditions. TYPE: `Filter \| list[Filter] \| None` DEFAULT: `None`
`mode`	Result display mode. Default: `"curve"`. TYPE: `RetentionMode` DEFAULT: `'curve'`
`unbounded_mode`	Retention unbounded mode controlling how retention is counted in unbounded periods. One of `"none"`, `"carry_back"`, `"carry_forward"`, or `"consecutive_forward"`. Default: `None` (server default). TYPE: `RetentionUnboundedMode \| None` DEFAULT: `None`
`retention_cumulative`	Whether to use cumulative retention counting. Default: `False`. TYPE: `bool` DEFAULT: `False`
`time_comparison`	Optional period-over-period comparison. Use `TimeComparison.relative("month")` for previous month, etc. Default: `None`. TYPE: `TimeComparison \| None` DEFAULT: `None`
`data_group_id`	Optional data group ID for group-level analytics. Scopes the query to a specific data group. Default: `None`. TYPE: `int \| None` DEFAULT: `None`
`limit`	Segments to return, 1 to 50000. Default `None` keeps the 3000 the Mixpanel UI uses. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`RetentionQueryResult`	RetentionQueryResult with cohort data, DataFrame, and
`RetentionQueryResult`	metadata.

RAISES	DESCRIPTION
`ValueError`	`limit` is not an integer from 1 to 50000.
`BookmarkValidationError`	If arguments violate validation rules (before API call).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials.
`QueryError`	Invalid query parameters.
`RateLimitError`	Rate limit exceeded.

Example

ws = Workspace()

# Simple retention query
result = ws.query_retention("Signup", "Login")
print(result.average)

# With configuration
result = ws.query_retention(
    "Signup", "Login",
    retention_unit="day",
    bucket_sizes=[1, 3, 7, 14, 30],
    last=90,
)
print(result.df)

# A saved retention behavior by id
result = ws.query_retention(BehaviorRef(4410, "retention"))

Source code in src/mixpanel_headless/workspace.py

def query_retention(
    self,
    born_event: str | RetentionEvent | BehaviorRef | SavedBehavior,
    return_event: str | RetentionEvent | None = None,
    *,
    retention_unit: TimeUnit = "week",
    alignment: RetentionAlignment = "birth",
    bucket_sizes: list[int] | None = None,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: RetentionMathType = "retention_rate",
    group_by: str
    | GroupBy
    | CohortBreakdown
    | list[str | GroupBy | CohortBreakdown]
    | None = None,
    where: Filter | list[Filter] | None = None,
    mode: RetentionMode = "curve",
    unbounded_mode: RetentionUnboundedMode | None = None,
    retention_cumulative: bool = False,
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
    limit: int | None = None,
) -> RetentionQueryResult:
    """Run a typed retention query against the Mixpanel API.

    Generates retention bookmark params from keyword arguments, POSTs
    them inline to ``/api/query/insights``, and returns a structured
    RetentionQueryResult with lazy DataFrame conversion.

    Args:
        born_event: Event that defines cohort membership. Accepts
            an event name string or a ``RetentionEvent`` object
            for per-event filters. A ``BehaviorRef`` or
            ``SavedBehavior`` for a saved retention behavior replaces
            both events: the saved behavior sets the events, the
            retention unit, the alignment, the buckets, and the
            unbounded mode, so ``return_event`` stays ``None`` and
            those arguments keep their defaults
            (``R15_BEHAVIOR_REF_SETTINGS``).
        return_event: Event that defines return. Accepts an event
            name string or a ``RetentionEvent`` object. Required
            unless ``born_event`` is a ``BehaviorRef``.
        retention_unit: Retention period unit. Default: ``"week"``.
        alignment: Retention alignment mode. Default: ``"birth"``.
        bucket_sizes: Custom bucket sizes (positive ints in
            ascending order). Default: ``None`` (uniform buckets).
        from_date: Start date (YYYY-MM-DD). If set, overrides
            ``last``.
        to_date: End date (YYYY-MM-DD). Requires ``from_date``.
        last: Relative time range in days. Default: 30.
        unit: Time aggregation unit (``day``, ``week``, or
            ``month`` — ``hour`` is not supported for retention).
            Default: ``"day"``.
        math: Retention aggregation function. Default:
            ``"retention_rate"``.
        group_by: Break down results by property or cohort
            membership. Accepts a string, ``GroupBy``,
            ``CohortBreakdown``, or list of any mix.
        where: Filter results by conditions.
        mode: Result display mode. Default: ``"curve"``.
        unbounded_mode: Retention unbounded mode controlling how
            retention is counted in unbounded periods. One of
            ``"none"``, ``"carry_back"``, ``"carry_forward"``, or
            ``"consecutive_forward"``. Default: ``None``
            (server default).
        retention_cumulative: Whether to use cumulative retention
            counting. Default: ``False``.
        time_comparison: Optional period-over-period comparison.
            Use ``TimeComparison.relative("month")`` for previous
            month, etc. Default: ``None``.
        data_group_id: Optional data group ID for group-level
            analytics. Scopes the query to a specific data group.
            Default: ``None``.
        limit: Segments to return, 1 to 50000. Default ``None`` keeps
            the 3000 the Mixpanel UI uses.

    Returns:
        RetentionQueryResult with cohort data, DataFrame, and
        metadata.

    Raises:
        ValueError: ``limit`` is not an integer from 1 to 50000.
        BookmarkValidationError: If arguments violate validation
            rules (before API call).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials.
        QueryError: Invalid query parameters.
        RateLimitError: Rate limit exceeded.

    Example:
        ```python
        ws = Workspace()

        # Simple retention query
        result = ws.query_retention("Signup", "Login")
        print(result.average)

        # With configuration
        result = ws.query_retention(
            "Signup", "Login",
            retention_unit="day",
            bucket_sizes=[1, 3, 7, 14, 30],
            last=90,
        )
        print(result.df)

        # A saved retention behavior by id
        result = ws.query_retention(BehaviorRef(4410, "retention"))
        ```
    """
    params = self._resolve_and_build_retention_params(
        born_event=born_event,
        return_event=return_event,
        retention_unit=retention_unit,
        alignment=alignment,
        bucket_sizes=bucket_sizes,
        math=math,
        from_date=from_date,
        to_date=to_date,
        last=last,
        unit=unit,
        group_by=group_by,
        where=where,
        mode=mode,
        unbounded_mode=unbounded_mode,
        retention_cumulative=retention_cumulative,
        time_comparison=time_comparison,
        data_group_id=data_group_id,
    )

    return self._live_query_service.query_retention(
        bookmark_params=params,
        project_id=int(self._session.project.id),
        limit=limit,
    )

build_retention_params ¶

build_retention_params(
    born_event: str | RetentionEvent | BehaviorRef | SavedBehavior,
    return_event: str | RetentionEvent | None = None,
    *,
    retention_unit: TimeUnit = "week",
    alignment: RetentionAlignment = "birth",
    bucket_sizes: list[int] | None = None,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: RetentionMathType = "retention_rate",
    group_by: str
    | GroupBy
    | CohortBreakdown
    | list[str | GroupBy | CohortBreakdown]
    | None = None,
    where: Filter | list[Filter] | None = None,
    mode: RetentionMode = "curve",
    unbounded_mode: RetentionUnboundedMode | None = None,
    retention_cumulative: bool = False,
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
) -> dict[str, Any]

Build validated retention bookmark params without executing.

Accepts the same arguments as :meth:query_retention but returns the generated bookmark params dict (not a RetentionQueryResult) instead of querying the API. Useful for debugging, inspecting generated JSON, persisting via :meth:create_bookmark, or testing.

PARAMETER	DESCRIPTION
`born_event`	Event that defines cohort membership, or a `BehaviorRef` or `SavedBehavior` for a saved retention behavior; see :meth:`query_retention`. TYPE: `str \| RetentionEvent \| BehaviorRef \| SavedBehavior`
`return_event`	Event that defines return. Required unless `born_event` is a `BehaviorRef`. TYPE: `str \| RetentionEvent \| None` DEFAULT: `None`
`retention_unit`	Retention period unit. Default: `"week"`. TYPE: `TimeUnit` DEFAULT: `'week'`
`alignment`	Retention alignment mode. Default: `"birth"`. TYPE: `RetentionAlignment` DEFAULT: `'birth'`
`bucket_sizes`	Custom bucket sizes. Default: `None`. TYPE: `list[int] \| None` DEFAULT: `None`
`from_date`	Start date (YYYY-MM-DD) or None. TYPE: `str \| None` DEFAULT: `None`
`to_date`	End date (YYYY-MM-DD) or None. TYPE: `str \| None` DEFAULT: `None`
`last`	Relative time range in days. Default: 30. TYPE: `int` DEFAULT: `30`
`unit`	Time aggregation unit (`day`, `week`, or `month` — `hour` is not supported for retention). Default: `"day"`. TYPE: `QueryTimeUnit` DEFAULT: `'day'`
`math`	Aggregation function. Default: `"retention_rate"`. TYPE: `RetentionMathType` DEFAULT: `'retention_rate'`
`group_by`	Break down results by property or cohort membership. Accepts a string, `GroupBy`, `CohortBreakdown`, or list of any mix. TYPE: `str \| GroupBy \| CohortBreakdown \| list[str \| GroupBy \| CohortBreakdown] \| None` DEFAULT: `None`
`where`	Filter results by conditions. TYPE: `Filter \| list[Filter] \| None` DEFAULT: `None`
`mode`	Display mode. Default: `"curve"`. TYPE: `RetentionMode` DEFAULT: `'curve'`
`unbounded_mode`	Retention unbounded mode controlling how retention is counted in unbounded periods. One of `"none"`, `"carry_back"`, `"carry_forward"`, or `"consecutive_forward"`. Default: `None` (server default). TYPE: `RetentionUnboundedMode \| None` DEFAULT: `None`
`retention_cumulative`	Whether to use cumulative retention counting. Default: `False`. TYPE: `bool` DEFAULT: `False`
`time_comparison`	Optional period-over-period comparison. Use `TimeComparison.relative("month")` for previous month, etc. Default: `None`. TYPE: `TimeComparison \| None` DEFAULT: `None`
`data_group_id`	Optional data group ID for group-level analytics. Scopes the query to a specific data group. Default: `None`. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict[str, Any]`	Bookmark params dict with `sections` and
`dict[str, Any]`	`displayOptions` keys.

RAISES	DESCRIPTION
`BookmarkValidationError`	If arguments violate validation rules.

Example

ws = Workspace()

# Inspect generated JSON
params = ws.build_retention_params("Signup", "Login")
print(json.dumps(params, indent=2))

# Save as a report (dashboard_id required)
ws.create_bookmark(CreateBookmarkParams(
    name="Signup → Login Retention",
    bookmark_type="retention",
    params=params,
    dashboard_id=12345,
))

Source code in src/mixpanel_headless/workspace.py

def build_retention_params(
    self,
    born_event: str | RetentionEvent | BehaviorRef | SavedBehavior,
    return_event: str | RetentionEvent | None = None,
    *,
    retention_unit: TimeUnit = "week",
    alignment: RetentionAlignment = "birth",
    bucket_sizes: list[int] | None = None,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    unit: QueryTimeUnit = "day",
    math: RetentionMathType = "retention_rate",
    group_by: str
    | GroupBy
    | CohortBreakdown
    | list[str | GroupBy | CohortBreakdown]
    | None = None,
    where: Filter | list[Filter] | None = None,
    mode: RetentionMode = "curve",
    unbounded_mode: RetentionUnboundedMode | None = None,
    retention_cumulative: bool = False,
    time_comparison: TimeComparison | None = None,
    data_group_id: int | None = None,
) -> dict[str, Any]:
    """Build validated retention bookmark params without executing.

    Accepts the same arguments as :meth:`query_retention` but returns
    the generated bookmark params ``dict`` (not a
    ``RetentionQueryResult``) instead of querying the API. Useful for
    debugging, inspecting generated JSON, persisting via
    :meth:`create_bookmark`, or testing.

    Args:
        born_event: Event that defines cohort membership, or a
            ``BehaviorRef`` or ``SavedBehavior`` for a saved retention
            behavior; see :meth:`query_retention`.
        return_event: Event that defines return. Required unless
            ``born_event`` is a ``BehaviorRef``.
        retention_unit: Retention period unit. Default: ``"week"``.
        alignment: Retention alignment mode. Default: ``"birth"``.
        bucket_sizes: Custom bucket sizes. Default: ``None``.
        from_date: Start date (YYYY-MM-DD) or None.
        to_date: End date (YYYY-MM-DD) or None.
        last: Relative time range in days. Default: 30.
        unit: Time aggregation unit (``day``, ``week``, or
            ``month`` — ``hour`` is not supported for retention).
            Default: ``"day"``.
        math: Aggregation function. Default:
            ``"retention_rate"``.
        group_by: Break down results by property or cohort
            membership. Accepts a string, ``GroupBy``,
            ``CohortBreakdown``, or list of any mix.
        where: Filter results by conditions.
        mode: Display mode. Default: ``"curve"``.
        unbounded_mode: Retention unbounded mode controlling how
            retention is counted in unbounded periods. One of
            ``"none"``, ``"carry_back"``, ``"carry_forward"``, or
            ``"consecutive_forward"``. Default: ``None``
            (server default).
        retention_cumulative: Whether to use cumulative retention
            counting. Default: ``False``.
        time_comparison: Optional period-over-period comparison.
            Use ``TimeComparison.relative("month")`` for previous
            month, etc. Default: ``None``.
        data_group_id: Optional data group ID for group-level
            analytics. Scopes the query to a specific data group.
            Default: ``None``.

    Returns:
        Bookmark params dict with ``sections`` and
        ``displayOptions`` keys.

    Raises:
        BookmarkValidationError: If arguments violate validation
            rules.

    Example:
        ```python
        ws = Workspace()

        # Inspect generated JSON
        params = ws.build_retention_params("Signup", "Login")
        print(json.dumps(params, indent=2))

        # Save as a report (dashboard_id required)
        ws.create_bookmark(CreateBookmarkParams(
            name="Signup → Login Retention",
            bookmark_type="retention",
            params=params,
            dashboard_id=12345,
        ))
        ```
    """
    return self._resolve_and_build_retention_params(
        born_event=born_event,
        return_event=return_event,
        retention_unit=retention_unit,
        alignment=alignment,
        bucket_sizes=bucket_sizes,
        math=math,
        from_date=from_date,
        to_date=to_date,
        last=last,
        unit=unit,
        group_by=group_by,
        where=where,
        mode=mode,
        unbounded_mode=unbounded_mode,
        retention_cumulative=retention_cumulative,
        time_comparison=time_comparison,
        data_group_id=data_group_id,
    )

run_retention_params ¶

run_retention_params(
    params: dict[str, Any],
    *,
    limit: int | None = None,
    workspace_id: int | None = None,
) -> RetentionQueryResult

Run pre-built retention bookmark params against the Mixpanel API.

The execution half of :meth:build_retention_params.

PARAMETER	DESCRIPTION
`params`	Retention bookmark params dict, normally from :meth:`build_retention_params`. Sent as the request `bookmark`. TYPE: `dict[str, Any]`
`limit`	Segments to return, 1 to 50000. Default `None` keeps the 3000 the Mixpanel UI uses. TYPE: `int \| None` DEFAULT: `None`
`workspace_id`	Optional data view to run under. Wins over the pinned session workspace. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`RetentionQueryResult`	RetentionQueryResult with cohort data, DataFrame, and
`RetentionQueryResult`	metadata.

RAISES	DESCRIPTION
`ValueError`	`limit` is not an integer from 1 to 50000.
`AuthenticationError`	Invalid credentials.
`QueryError`	Invalid bookmark params.
`RateLimitError`	Rate limit exceeded.

Example

params = ws.build_retention_params("Signup", "Login")
result = ws.run_retention_params(params, limit=50_000)

Source code in src/mixpanel_headless/workspace.py

def run_retention_params(
    self,
    params: dict[str, Any],
    *,
    limit: int | None = None,
    workspace_id: int | None = None,
) -> RetentionQueryResult:
    """Run pre-built retention bookmark params against the Mixpanel API.

    The execution half of :meth:`build_retention_params`.

    Args:
        params: Retention bookmark params dict, normally from
            :meth:`build_retention_params`. Sent as the request
            ``bookmark``.
        limit: Segments to return, 1 to 50000. Default ``None`` keeps
            the 3000 the Mixpanel UI uses.
        workspace_id: Optional data view to run under. Wins over the
            pinned session workspace.

    Returns:
        RetentionQueryResult with cohort data, DataFrame, and
        metadata.

    Raises:
        ValueError: ``limit`` is not an integer from 1 to 50000.
        AuthenticationError: Invalid credentials.
        QueryError: Invalid bookmark params.
        RateLimitError: Rate limit exceeded.

    Example:
        ```python
        params = ws.build_retention_params("Signup", "Login")
        result = ws.run_retention_params(params, limit=50_000)
        ```
    """
    return self._live_query_service.query_retention(
        bookmark_params=params,
        project_id=int(self._session.project.id),
        limit=limit,
        workspace_id=workspace_id,
    )

query_flow ¶

query_flow(
    event: str | FlowStep | Sequence[str | FlowStep],
    *,
    forward: int = 3,
    reverse: int = 0,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    conversion_window: int = 7,
    conversion_window_unit: Literal["day", "week", "month", "session"] = "day",
    count_type: Literal["unique", "total", "session"] = "unique",
    cardinality: int = 3,
    collapse_repeated: bool = False,
    hidden_events: list[str] | None = None,
    mode: Literal["sankey", "paths", "tree"] = "sankey",
    where: Filter | list[Filter] | None = None,
    data_group_id: int | None = None,
    segments: str
    | GroupBy
    | CohortBreakdown
    | FrequencyBreakdown
    | list[str | GroupBy | CohortBreakdown | FrequencyBreakdown]
    | None = None,
    exclusions: list[str] | None = None,
) -> FlowQueryResult

Run a typed flow query against the Mixpanel API.

Generates flow bookmark params from keyword arguments, POSTs them inline to /arb_funnels, and returns a structured FlowQueryResult with lazy DataFrame conversion.

PARAMETER	DESCRIPTION
`event`	Event specification. Accepts an event name string, a `FlowStep` object for per-step configuration, or a list of strings/`FlowStep` objects for multi-step flows. TYPE: `str \| FlowStep \| Sequence[str \| FlowStep]`
`forward`	Default number of forward steps to trace from each anchor event. Overridden by per-step values. Default: `3`. TYPE: `int` DEFAULT: `3`
`reverse`	Default number of reverse steps to trace from each anchor event. Overridden by per-step values. Default: `0`. TYPE: `int` DEFAULT: `0`
`from_date`	Start date (YYYY-MM-DD). If set, overrides `last`. TYPE: `str \| None` DEFAULT: `None`
`to_date`	End date (YYYY-MM-DD). Requires `from_date`. TYPE: `str \| None` DEFAULT: `None`
`last`	Relative time range in days. Default: 30. TYPE: `int` DEFAULT: `30`
`conversion_window`	Conversion window size. Default: 7. TYPE: `int` DEFAULT: `7`
`conversion_window_unit`	Conversion window unit. Default: `"day"`. TYPE: `Literal['day', 'week', 'month', 'session']` DEFAULT: `'day'`
`count_type`	Counting method for flow analysis. Default: `"unique"`. TYPE: `Literal['unique', 'total', 'session']` DEFAULT: `'unique'`
`cardinality`	Number of top paths to display. Default: `3`. TYPE: `int` DEFAULT: `3`
`collapse_repeated`	Whether to merge consecutive repeated events. Default: `False`. TYPE: `bool` DEFAULT: `False`
`hidden_events`	Events to hide from the flow visualization. Default: `None`. TYPE: `list[str] \| None` DEFAULT: `None`
`mode`	Flow visualization mode. Default: `"sankey"`. TYPE: `Literal['sankey', 'paths', 'tree']` DEFAULT: `'sankey'`
`where`	Filter results by cohort membership or property conditions. Cohort filters (`Filter.in_cohort` / `Filter.not_in_cohort`) produce `filter_by_cohort`. Property filters (`Filter.equals`, etc.) produce `filter_by_event`. Default: `None`. TYPE: `Filter \| list[Filter] \| None` DEFAULT: `None`
`data_group_id`	Optional data group ID for group-level analytics. Scopes the query to a specific data group. Default: `None`. TYPE: `int \| None` DEFAULT: `None`
`segments`	Segment (breakdown) specification for flow results. Accepts a string, `GroupBy`, or list of strings/`GroupBy` objects. Default: `None`. TYPE: `str \| GroupBy \| CohortBreakdown \| FrequencyBreakdown \| list[str \| GroupBy \| CohortBreakdown \| FrequencyBreakdown] \| None` DEFAULT: `None`
`exclusions`	List of event names to exclude from flow paths. Default: `None`. TYPE: `list[str] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`FlowQueryResult`	FlowQueryResult with steps, flows, breakdowns, and
`FlowQueryResult`	metadata.

RAISES	DESCRIPTION
`BookmarkValidationError`	If arguments violate validation rules (before API call).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials.
`QueryError`	Invalid query parameters.
`RateLimitError`	Rate limit exceeded.

Example

ws = Workspace()

# Simple flow query
result = ws.query_flow("Login")
print(result.overall_conversion_rate)

# With configuration
result = ws.query_flow(
    FlowStep("Login", forward=5, reverse=2),
    mode="paths",
    last=90,
)
print(result.df)

# With property filter and segments
result = ws.query_flow(
    "Login",
    where=Filter.equals("country", "US"),
    segments=GroupBy("platform"),
    exclusions=["Error Event"],
)

Source code in src/mixpanel_headless/workspace.py

def query_flow(
    self,
    event: str | FlowStep | Sequence[str | FlowStep],
    *,
    forward: int = 3,
    reverse: int = 0,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    conversion_window: int = 7,
    conversion_window_unit: Literal["day", "week", "month", "session"] = "day",
    count_type: Literal["unique", "total", "session"] = "unique",
    cardinality: int = 3,
    collapse_repeated: bool = False,
    hidden_events: list[str] | None = None,
    mode: Literal["sankey", "paths", "tree"] = "sankey",
    where: Filter | list[Filter] | None = None,
    data_group_id: int | None = None,
    segments: str
    | GroupBy
    | CohortBreakdown
    | FrequencyBreakdown
    | list[str | GroupBy | CohortBreakdown | FrequencyBreakdown]
    | None = None,
    exclusions: list[str] | None = None,
) -> FlowQueryResult:
    """Run a typed flow query against the Mixpanel API.

    Generates flow bookmark params from keyword arguments, POSTs
    them inline to ``/arb_funnels``, and returns a structured
    ``FlowQueryResult`` with lazy DataFrame conversion.

    Args:
        event: Event specification. Accepts an event name string,
            a ``FlowStep`` object for per-step configuration, or
            a list of strings/``FlowStep`` objects for multi-step
            flows.
        forward: Default number of forward steps to trace from
            each anchor event. Overridden by per-step values.
            Default: ``3``.
        reverse: Default number of reverse steps to trace from
            each anchor event. Overridden by per-step values.
            Default: ``0``.
        from_date: Start date (YYYY-MM-DD). If set, overrides
            ``last``.
        to_date: End date (YYYY-MM-DD). Requires ``from_date``.
        last: Relative time range in days. Default: 30.
        conversion_window: Conversion window size. Default: 7.
        conversion_window_unit: Conversion window unit.
            Default: ``"day"``.
        count_type: Counting method for flow analysis.
            Default: ``"unique"``.
        cardinality: Number of top paths to display.
            Default: ``3``.
        collapse_repeated: Whether to merge consecutive repeated
            events. Default: ``False``.
        hidden_events: Events to hide from the flow visualization.
            Default: ``None``.
        mode: Flow visualization mode. Default: ``"sankey"``.
        where: Filter results by cohort membership or property
            conditions. Cohort filters (``Filter.in_cohort`` /
            ``Filter.not_in_cohort``) produce ``filter_by_cohort``.
            Property filters (``Filter.equals``, etc.) produce
            ``filter_by_event``. Default: ``None``.
        data_group_id: Optional data group ID for group-level
            analytics. Scopes the query to a specific data group.
            Default: ``None``.
        segments: Segment (breakdown) specification for flow
            results. Accepts a string, ``GroupBy``, or list of
            strings/``GroupBy`` objects. Default: ``None``.
        exclusions: List of event names to exclude from flow
            paths. Default: ``None``.

    Returns:
        FlowQueryResult with steps, flows, breakdowns, and
        metadata.

    Raises:
        BookmarkValidationError: If arguments violate validation
            rules (before API call).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials.
        QueryError: Invalid query parameters.
        RateLimitError: Rate limit exceeded.

    Example:
        ```python
        ws = Workspace()

        # Simple flow query
        result = ws.query_flow("Login")
        print(result.overall_conversion_rate)

        # With configuration
        result = ws.query_flow(
            FlowStep("Login", forward=5, reverse=2),
            mode="paths",
            last=90,
        )
        print(result.df)

        # With property filter and segments
        result = ws.query_flow(
            "Login",
            where=Filter.equals("country", "US"),
            segments=GroupBy("platform"),
            exclusions=["Error Event"],
        )
        ```
    """
    params = self._resolve_and_build_flow_params(
        event=event,
        forward=forward,
        reverse=reverse,
        from_date=from_date,
        to_date=to_date,
        last=last,
        conversion_window=conversion_window,
        conversion_window_unit=conversion_window_unit,
        count_type=count_type,
        cardinality=cardinality,
        collapse_repeated=collapse_repeated,
        hidden_events=hidden_events,
        mode=mode,
        where=where,
        data_group_id=data_group_id,
        segments=segments,
        exclusions=exclusions,
    )

    return self._live_query_service.query_flow(
        bookmark_params=params,
        project_id=int(self._session.project.id),
        mode=mode,
    )

build_flow_params ¶

build_flow_params(
    event: str | FlowStep | Sequence[str | FlowStep],
    *,
    forward: int = 3,
    reverse: int = 0,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    conversion_window: int = 7,
    conversion_window_unit: Literal["day", "week", "month", "session"] = "day",
    count_type: Literal["unique", "total", "session"] = "unique",
    cardinality: int = 3,
    collapse_repeated: bool = False,
    hidden_events: list[str] | None = None,
    mode: Literal["sankey", "paths", "tree"] = "sankey",
    where: Filter | list[Filter] | None = None,
    data_group_id: int | None = None,
    segments: str
    | GroupBy
    | CohortBreakdown
    | FrequencyBreakdown
    | list[str | GroupBy | CohortBreakdown | FrequencyBreakdown]
    | None = None,
    exclusions: list[str] | None = None,
) -> dict[str, Any]

Build validated flow bookmark params without executing.

Accepts the same arguments as :meth:query_flow but returns the generated bookmark params dict instead of querying the API. Useful for debugging, inspecting generated JSON, persisting via :meth:create_bookmark, or testing.

PARAMETER	DESCRIPTION
`event`	Event specification. Accepts an event name string, a `FlowStep` object, or a list of strings/`FlowStep` objects. TYPE: `str \| FlowStep \| Sequence[str \| FlowStep]`
`forward`	Default forward step count. Default: `3`. TYPE: `int` DEFAULT: `3`
`reverse`	Default reverse step count. Default: `0`. TYPE: `int` DEFAULT: `0`
`from_date`	Start date (YYYY-MM-DD) or `None`. TYPE: `str \| None` DEFAULT: `None`
`to_date`	End date (YYYY-MM-DD) or `None`. TYPE: `str \| None` DEFAULT: `None`
`last`	Relative time range in days. Default: 30. TYPE: `int` DEFAULT: `30`
`conversion_window`	Conversion window size. Default: 7. TYPE: `int` DEFAULT: `7`
`conversion_window_unit`	Conversion window unit. Default: `"day"`. TYPE: `Literal['day', 'week', 'month', 'session']` DEFAULT: `'day'`
`count_type`	Counting method. Default: `"unique"`. TYPE: `Literal['unique', 'total', 'session']` DEFAULT: `'unique'`
`cardinality`	Number of top paths. Default: `3`. TYPE: `int` DEFAULT: `3`
`collapse_repeated`	Merge repeated events. Default: `False`. TYPE: `bool` DEFAULT: `False`
`hidden_events`	Events to hide. Default: `None`. TYPE: `list[str] \| None` DEFAULT: `None`
`mode`	Display mode. Default: `"sankey"`. TYPE: `Literal['sankey', 'paths', 'tree']` DEFAULT: `'sankey'`
`where`	Filter results by cohort membership or property conditions. Cohort filters produce `filter_by_cohort`, property filters produce `filter_by_event`. Default: `None`. TYPE: `Filter \| list[Filter] \| None` DEFAULT: `None`
`data_group_id`	Optional data group ID for group-level analytics. Scopes the query to a specific data group. Default: `None`. TYPE: `int \| None` DEFAULT: `None`
`segments`	Segment (breakdown) specification for flow results. Accepts a string, `GroupBy`, or list of strings/`GroupBy` objects. Default: `None`. TYPE: `str \| GroupBy \| CohortBreakdown \| FrequencyBreakdown \| list[str \| GroupBy \| CohortBreakdown \| FrequencyBreakdown] \| None` DEFAULT: `None`
`exclusions`	List of event names to exclude from flow paths. Default: `None`. TYPE: `list[str] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict[str, Any]`	Flat bookmark params dict with `steps`, `date_range`,
`dict[str, Any]`	`chartType`, `count_type`, and `version` keys.

RAISES	DESCRIPTION
`BookmarkValidationError`	If arguments violate validation rules.

Example

ws = Workspace()

# Inspect generated JSON
params = ws.build_flow_params("Login")
print(json.dumps(params, indent=2))

# With segments and exclusions
params = ws.build_flow_params(
    "Login",
    segments=GroupBy("country"),
    exclusions=["Error Event"],
    where=Filter.equals("platform", "iOS"),
)

Source code in src/mixpanel_headless/workspace.py

def build_flow_params(
    self,
    event: str | FlowStep | Sequence[str | FlowStep],
    *,
    forward: int = 3,
    reverse: int = 0,
    from_date: str | None = None,
    to_date: str | None = None,
    last: int = 30,
    conversion_window: int = 7,
    conversion_window_unit: Literal["day", "week", "month", "session"] = "day",
    count_type: Literal["unique", "total", "session"] = "unique",
    cardinality: int = 3,
    collapse_repeated: bool = False,
    hidden_events: list[str] | None = None,
    mode: Literal["sankey", "paths", "tree"] = "sankey",
    where: Filter | list[Filter] | None = None,
    data_group_id: int | None = None,
    segments: str
    | GroupBy
    | CohortBreakdown
    | FrequencyBreakdown
    | list[str | GroupBy | CohortBreakdown | FrequencyBreakdown]
    | None = None,
    exclusions: list[str] | None = None,
) -> dict[str, Any]:
    """Build validated flow bookmark params without executing.

    Accepts the same arguments as :meth:`query_flow` but returns
    the generated bookmark params ``dict`` instead of querying
    the API. Useful for debugging, inspecting generated JSON,
    persisting via :meth:`create_bookmark`, or testing.

    Args:
        event: Event specification. Accepts an event name string,
            a ``FlowStep`` object, or a list of strings/``FlowStep``
            objects.
        forward: Default forward step count. Default: ``3``.
        reverse: Default reverse step count. Default: ``0``.
        from_date: Start date (YYYY-MM-DD) or ``None``.
        to_date: End date (YYYY-MM-DD) or ``None``.
        last: Relative time range in days. Default: 30.
        conversion_window: Conversion window size. Default: 7.
        conversion_window_unit: Conversion window unit.
            Default: ``"day"``.
        count_type: Counting method. Default: ``"unique"``.
        cardinality: Number of top paths. Default: ``3``.
        collapse_repeated: Merge repeated events. Default: ``False``.
        hidden_events: Events to hide. Default: ``None``.
        mode: Display mode. Default: ``"sankey"``.
        where: Filter results by cohort membership or property
            conditions. Cohort filters produce ``filter_by_cohort``,
            property filters produce ``filter_by_event``.
            Default: ``None``.
        data_group_id: Optional data group ID for group-level
            analytics. Scopes the query to a specific data group.
            Default: ``None``.
        segments: Segment (breakdown) specification for flow
            results. Accepts a string, ``GroupBy``, or list of
            strings/``GroupBy`` objects. Default: ``None``.
        exclusions: List of event names to exclude from flow
            paths. Default: ``None``.

    Returns:
        Flat bookmark params dict with ``steps``, ``date_range``,
        ``chartType``, ``count_type``, and ``version`` keys.

    Raises:
        BookmarkValidationError: If arguments violate validation
            rules.

    Example:
        ```python
        ws = Workspace()

        # Inspect generated JSON
        params = ws.build_flow_params("Login")
        print(json.dumps(params, indent=2))

        # With segments and exclusions
        params = ws.build_flow_params(
            "Login",
            segments=GroupBy("country"),
            exclusions=["Error Event"],
            where=Filter.equals("platform", "iOS"),
        )
        ```
    """
    return self._resolve_and_build_flow_params(
        event=event,
        forward=forward,
        reverse=reverse,
        from_date=from_date,
        to_date=to_date,
        last=last,
        conversion_window=conversion_window,
        conversion_window_unit=conversion_window_unit,
        count_type=count_type,
        cardinality=cardinality,
        collapse_repeated=collapse_repeated,
        hidden_events=hidden_events,
        mode=mode,
        where=where,
        data_group_id=data_group_id,
        segments=segments,
        exclusions=exclusions,
    )

run_flow_params ¶

run_flow_params(
    params: dict[str, Any],
    *,
    mode: Literal["sankey", "paths", "tree"] | None = None,
    workspace_id: int | None = None,
) -> FlowQueryResult

Run pre-built flow bookmark params against the Mixpanel API.

The execution half of :meth:build_flow_params.

PARAMETER	DESCRIPTION
`params`	Flow bookmark params dict, normally from :meth:`build_flow_params`. Sent as the request `bookmark`. TYPE: `dict[str, Any]`
`mode`	Flow chart mode. `None` (default) derives it from the params: `flows_merge_type` (`"tree"`, `"list"` for paths, `"graph"` for sankey) when present, else `chartType` (`"top-paths"` or `"paths"` for paths, `"tree"`, anything else sankey). Params from :meth:`build_flow_params` always resolve to the mode they were built with. Pass a value to override. TYPE: `Literal['sankey', 'paths', 'tree'] \| None` DEFAULT: `None`
`workspace_id`	Optional data view to run under. Wins over the pinned session workspace. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`FlowQueryResult`	FlowQueryResult with steps, paths, or trees, DataFrame, and
`FlowQueryResult`	metadata.

RAISES	DESCRIPTION
`AuthenticationError`	Invalid credentials.
`QueryError`	Invalid bookmark params.
`RateLimitError`	Rate limit exceeded.

Example

params = ws.build_flow_params("Login", mode="tree", last=7)
result = ws.run_flow_params(params)   # runs as tree
print(result.df.head())

Source code in src/mixpanel_headless/workspace.py

def run_flow_params(
    self,
    params: dict[str, Any],
    *,
    mode: Literal["sankey", "paths", "tree"] | None = None,
    workspace_id: int | None = None,
) -> FlowQueryResult:
    """Run pre-built flow bookmark params against the Mixpanel API.

    The execution half of :meth:`build_flow_params`.

    Args:
        params: Flow bookmark params dict, normally from
            :meth:`build_flow_params`. Sent as the request ``bookmark``.
        mode: Flow chart mode. ``None`` (default) derives it from the
            params: ``flows_merge_type`` (``"tree"``, ``"list"`` for
            paths, ``"graph"`` for sankey) when present, else
            ``chartType`` (``"top-paths"`` or ``"paths"`` for paths,
            ``"tree"``, anything else sankey). Params from
            :meth:`build_flow_params` always resolve to the mode they
            were built with. Pass a value to override.
        workspace_id: Optional data view to run under. Wins over the
            pinned session workspace.

    Returns:
        FlowQueryResult with steps, paths, or trees, DataFrame, and
        metadata.

    Raises:
        AuthenticationError: Invalid credentials.
        QueryError: Invalid bookmark params.
        RateLimitError: Rate limit exceeded.

    Example:
        ```python
        params = ws.build_flow_params("Login", mode="tree", last=7)
        result = ws.run_flow_params(params)   # runs as tree
        print(result.df.head())
        ```
    """
    resolved_mode = mode if mode is not None else _flow_mode_from_params(params)
    return self._live_query_service.query_flow(
        bookmark_params=params,
        project_id=int(self._session.project.id),
        mode=resolved_mode,
        workspace_id=workspace_id,
    )

query_user ¶

query_user(
    *,
    where: Filter | list[Filter] | str | None = None,
    cohort: int | CohortDefinition | None = None,
    properties: list[str] | None = None,
    sort_by: str | None = None,
    sort_order: Literal["ascending", "descending"] = "descending",
    limit: int | None = 1,
    search: str | None = None,
    distinct_id: str | None = None,
    distinct_ids: list[str] | None = None,
    group_id: str | None = None,
    as_of: str | int | None = None,
    mode: Literal["profiles", "aggregate"] = "aggregate",
    aggregate: Literal[
        "count", "extremes", "percentile", "numeric_summary"
    ] = "count",
    aggregate_property: str | None = None,
    percentile: float | None = None,
    segment_by: list[int] | None = None,
    parallel: bool = False,
    workers: int = 5,
    include_all_users: bool = False,
) -> UserQueryResult

Query user profiles from Mixpanel's Engage API.

Provides a high-level interface to Mixpanel's Engage API for querying user profiles with typed filters, cohort membership, sorting, and pagination. Results are returned as a structured UserQueryResult with lazy DataFrame conversion.

PARAMETER	DESCRIPTION
`where`	Filter profiles by property values. Accepts a single `Filter`, a list of `Filter` objects (AND-combined), a raw selector string, or `None`. TYPE: `Filter \| list[Filter] \| str \| None` DEFAULT: `None`
`cohort`	Filter by cohort membership. An `int` for a saved cohort ID, or a `CohortDefinition` for an inline cohort definition. TYPE: `int \| CohortDefinition \| None` DEFAULT: `None`
`properties`	Output properties to include in results. TYPE: `list[str] \| None` DEFAULT: `None`
`sort_by`	Property name to sort results by. TYPE: `str \| None` DEFAULT: `None`
`sort_order`	Sort direction (`"ascending"` or `"descending"`). TYPE: `Literal['ascending', 'descending']` DEFAULT: `'descending'`
`limit`	Maximum profiles to return. Defaults to `1` for quick exploration. Use `None` to fetch all matching profiles. TYPE: `int \| None` DEFAULT: `1`
`search`	Full-text search term applied to profile properties. TYPE: `str \| None` DEFAULT: `None`
`distinct_id`	Look up a single user by distinct ID. TYPE: `str \| None` DEFAULT: `None`
`distinct_ids`	Batch look up multiple users by distinct IDs. TYPE: `list[str] \| None` DEFAULT: `None`
`group_id`	Query group profiles instead of user profiles. TYPE: `str \| None` DEFAULT: `None`
`as_of`	Point-in-time query. An ISO date string (`YYYY-MM-DD`) is converted to a Unix timestamp; an `int` is passed through directly. TYPE: `str \| int \| None` DEFAULT: `None`
`mode`	Output mode (`"profiles"` or `"aggregate"`). TYPE: `Literal['profiles', 'aggregate']` DEFAULT: `'aggregate'`
`aggregate`	Aggregation function for aggregate mode. One of `"count"` (profile count), `"extremes"` (min/max), `"percentile"` (Nth percentile), or `"numeric_summary"` (count/mean/var/sum_of_squares). TYPE: `Literal['count', 'extremes', 'percentile', 'numeric_summary']` DEFAULT: `'count'`
`aggregate_property`	Property to aggregate on (required for non-count aggregations). TYPE: `str \| None` DEFAULT: `None`
`percentile`	Percentile value (0-100 exclusive). Required when `aggregate="percentile"`. TYPE: `float \| None` DEFAULT: `None`
`segment_by`	Cohort IDs for segmented aggregation. TYPE: `list[int] \| None` DEFAULT: `None`
`parallel`	Whether to enable concurrent page fetching. TYPE: `bool` DEFAULT: `False`
`workers`	Maximum concurrent workers for parallel fetching. TYPE: `int` DEFAULT: `5`
`include_all_users`	Include non-members in cohort query results. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`UserQueryResult`	`UserQueryResult` with profiles, total count, DataFrame,
`UserQueryResult`	and execution metadata.

RAISES	DESCRIPTION
`BookmarkValidationError`	If any validation rule fails.
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`RateLimitError`	API rate limit exceeded (429).
`APIError`	Other API communication errors.

Example

ws = Workspace()

# Quick peek at one profile
result = ws.query_user()
print(result.df)

# Filter premium users, sorted by LTV
result = ws.query_user(
    where=Filter.equals("plan", "premium"),
    sort_by="ltv",
    sort_order="descending",
    limit=100,
)
print(f"Total premium users: {result.total}")
print(result.df.head())

# Batch lookup specific users
result = ws.query_user(
    distinct_ids=["user_001", "user_002"],
    limit=None,
)

Source code in src/mixpanel_headless/workspace.py

def query_user(
    self,
    *,
    where: Filter | list[Filter] | str | None = None,
    cohort: int | CohortDefinition | None = None,
    properties: list[str] | None = None,
    sort_by: str | None = None,
    sort_order: Literal["ascending", "descending"] = "descending",
    limit: int | None = 1,
    search: str | None = None,
    distinct_id: str | None = None,
    distinct_ids: list[str] | None = None,
    group_id: str | None = None,
    as_of: str | int | None = None,
    mode: Literal["profiles", "aggregate"] = "aggregate",
    aggregate: Literal[
        "count", "extremes", "percentile", "numeric_summary"
    ] = "count",
    aggregate_property: str | None = None,
    percentile: float | None = None,
    segment_by: list[int] | None = None,
    parallel: bool = False,
    workers: int = 5,
    include_all_users: bool = False,
) -> UserQueryResult:
    """Query user profiles from Mixpanel's Engage API.

    Provides a high-level interface to Mixpanel's Engage API for
    querying user profiles with typed filters, cohort membership,
    sorting, and pagination. Results are returned as a structured
    ``UserQueryResult`` with lazy DataFrame conversion.

    Args:
        where: Filter profiles by property values. Accepts a single
            ``Filter``, a list of ``Filter`` objects (AND-combined),
            a raw selector string, or ``None``.
        cohort: Filter by cohort membership. An ``int`` for a saved
            cohort ID, or a ``CohortDefinition`` for an inline
            cohort definition.
        properties: Output properties to include in results.
        sort_by: Property name to sort results by.
        sort_order: Sort direction (``"ascending"`` or ``"descending"``).
        limit: Maximum profiles to return. Defaults to ``1`` for
            quick exploration. Use ``None`` to fetch all matching
            profiles.
        search: Full-text search term applied to profile properties.
        distinct_id: Look up a single user by distinct ID.
        distinct_ids: Batch look up multiple users by distinct IDs.
        group_id: Query group profiles instead of user profiles.
        as_of: Point-in-time query. An ISO date string (``YYYY-MM-DD``)
            is converted to a Unix timestamp; an ``int`` is passed
            through directly.
        mode: Output mode (``"profiles"`` or ``"aggregate"``).
        aggregate: Aggregation function for aggregate mode. One of
            ``"count"`` (profile count), ``"extremes"`` (min/max),
            ``"percentile"`` (Nth percentile), or
            ``"numeric_summary"`` (count/mean/var/sum_of_squares).
        aggregate_property: Property to aggregate on (required for
            non-count aggregations).
        percentile: Percentile value (0-100 exclusive). Required
            when ``aggregate="percentile"``.
        segment_by: Cohort IDs for segmented aggregation.
        parallel: Whether to enable concurrent page fetching.
        workers: Maximum concurrent workers for parallel fetching.
        include_all_users: Include non-members in cohort query results.

    Returns:
        ``UserQueryResult`` with profiles, total count, DataFrame,
        and execution metadata.

    Raises:
        BookmarkValidationError: If any validation rule fails.
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        RateLimitError: API rate limit exceeded (429).
        APIError: Other API communication errors.

    Example:
        ```python
        ws = Workspace()

        # Quick peek at one profile
        result = ws.query_user()
        print(result.df)

        # Filter premium users, sorted by LTV
        result = ws.query_user(
            where=Filter.equals("plan", "premium"),
            sort_by="ltv",
            sort_order="descending",
            limit=100,
        )
        print(f"Total premium users: {result.total}")
        print(result.df.head())

        # Batch lookup specific users
        result = ws.query_user(
            distinct_ids=["user_001", "user_002"],
            limit=None,
        )
        ```
    """
    params = self._resolve_and_build_user_params(
        where=where,
        cohort=cohort,
        properties=properties,
        sort_by=sort_by,
        sort_order=sort_order,
        limit=limit,
        search=search,
        distinct_id=distinct_id,
        distinct_ids=distinct_ids,
        group_id=group_id,
        as_of=as_of,
        mode=mode,
        aggregate=aggregate,
        aggregate_property=aggregate_property,
        percentile=percentile,
        segment_by=segment_by,
        parallel=parallel,
        workers=workers,
        include_all_users=include_all_users,
    )

    return self.run_user_params(
        params, limit=limit, parallel=parallel, workers=workers
    )

build_user_params ¶

build_user_params(
    *,
    where: Filter | list[Filter] | str | None = None,
    cohort: int | CohortDefinition | None = None,
    properties: list[str] | None = None,
    sort_by: str | None = None,
    sort_order: Literal["ascending", "descending"] = "descending",
    search: str | None = None,
    distinct_id: str | None = None,
    distinct_ids: list[str] | None = None,
    group_id: str | None = None,
    as_of: str | int | None = None,
    mode: Literal["profiles", "aggregate"] = "aggregate",
    aggregate: Literal[
        "count", "extremes", "percentile", "numeric_summary"
    ] = "count",
    aggregate_property: str | None = None,
    percentile: float | None = None,
    segment_by: list[int] | None = None,
    limit: int | None = 1,
    parallel: bool = False,
    workers: int = 5,
    include_all_users: bool = False,
) -> dict[str, Any]

Build engage API params without executing a query.

Validates arguments and constructs the params dict that would be sent to the Engage API, without actually making an API call. Useful for debugging, testing, and inspecting the generated params before execution.

PARAMETER	DESCRIPTION
`where`	Filter profiles by property values. Accepts a single `Filter`, a list of `Filter` objects (AND-combined), a raw selector string, or `None`. TYPE: `Filter \| list[Filter] \| str \| None` DEFAULT: `None`
`cohort`	Filter by cohort membership. An `int` for a saved cohort ID, or a `CohortDefinition` for an inline cohort definition. TYPE: `int \| CohortDefinition \| None` DEFAULT: `None`
`properties`	Output properties to include in results. TYPE: `list[str] \| None` DEFAULT: `None`
`sort_by`	Property name to sort results by. TYPE: `str \| None` DEFAULT: `None`
`sort_order`	Sort direction (`"ascending"` or `"descending"`). TYPE: `Literal['ascending', 'descending']` DEFAULT: `'descending'`
`search`	Full-text search term applied to profile properties. TYPE: `str \| None` DEFAULT: `None`
`distinct_id`	Look up a single user by distinct ID. TYPE: `str \| None` DEFAULT: `None`
`distinct_ids`	Batch look up multiple users by distinct IDs. TYPE: `list[str] \| None` DEFAULT: `None`
`group_id`	Query group profiles instead of user profiles. TYPE: `str \| None` DEFAULT: `None`
`as_of`	Point-in-time query. An ISO date string (`YYYY-MM-DD`) is converted to a Unix timestamp; an `int` is passed through directly. TYPE: `str \| int \| None` DEFAULT: `None`
`mode`	Output mode (`"profiles"` or `"aggregate"`). TYPE: `Literal['profiles', 'aggregate']` DEFAULT: `'aggregate'`
`aggregate`	Aggregation function for aggregate mode. One of `"count"` (profile count), `"extremes"` (min/max), `"percentile"` (Nth percentile), or `"numeric_summary"` (count/mean/var/sum_of_squares). TYPE: `Literal['count', 'extremes', 'percentile', 'numeric_summary']` DEFAULT: `'count'`
`aggregate_property`	Property to aggregate on (required for non-count aggregations). TYPE: `str \| None` DEFAULT: `None`
`percentile`	Percentile value (0-100 exclusive). Required when `aggregate="percentile"`. TYPE: `float \| None` DEFAULT: `None`
`segment_by`	Cohort IDs for segmented aggregation. TYPE: `list[int] \| None` DEFAULT: `None`
`limit`	Maximum profiles to return. Defaults to `1`. Used for argument-level validation (U3); not included in the returned params dict. TYPE: `int \| None` DEFAULT: `1`
`parallel`	Whether to enable concurrent page fetching. Accepted for signature compatibility with `query_user()` but has no effect on the returned params dict. TYPE: `bool` DEFAULT: `False`
`workers`	Maximum concurrent workers for parallel fetching. Accepted for signature compatibility with `query_user()` but has no effect on the returned params dict. TYPE: `int` DEFAULT: `5`
`include_all_users`	Include non-members in cohort query results. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`dict[str, Any]`	Engage API params dict. Does not include pagination params
`dict[str, Any]`	(`page`, `session_id`) or `limit`, which are added at
`dict[str, Any]`	execution time by `query_user()`.

RAISES	DESCRIPTION
`BookmarkValidationError`	If any validation rule fails at either the argument level (U1-U28) or the param level (UP1-UP4).

Example

ws = Workspace()
params = ws.build_user_params(
    where=Filter.equals("plan", "premium"),
    sort_by="ltv",
)
print(params)
# {"where": 'properties["plan"] == "premium"',
#  "sort_key": 'properties["ltv"]',
#  "sort_order": "descending"}

Source code in src/mixpanel_headless/workspace.py

def build_user_params(
    self,
    *,
    where: Filter | list[Filter] | str | None = None,
    cohort: int | CohortDefinition | None = None,
    properties: list[str] | None = None,
    sort_by: str | None = None,
    sort_order: Literal["ascending", "descending"] = "descending",
    search: str | None = None,
    distinct_id: str | None = None,
    distinct_ids: list[str] | None = None,
    group_id: str | None = None,
    as_of: str | int | None = None,
    mode: Literal["profiles", "aggregate"] = "aggregate",
    aggregate: Literal[
        "count", "extremes", "percentile", "numeric_summary"
    ] = "count",
    aggregate_property: str | None = None,
    percentile: float | None = None,
    segment_by: list[int] | None = None,
    limit: int | None = 1,
    parallel: bool = False,
    workers: int = 5,
    include_all_users: bool = False,
) -> dict[str, Any]:
    """Build engage API params without executing a query.

    Validates arguments and constructs the params dict that would be
    sent to the Engage API, without actually making an API call.
    Useful for debugging, testing, and inspecting the generated
    params before execution.

    Args:
        where: Filter profiles by property values. Accepts a single
            ``Filter``, a list of ``Filter`` objects (AND-combined),
            a raw selector string, or ``None``.
        cohort: Filter by cohort membership. An ``int`` for a saved
            cohort ID, or a ``CohortDefinition`` for an inline
            cohort definition.
        properties: Output properties to include in results.
        sort_by: Property name to sort results by.
        sort_order: Sort direction (``"ascending"`` or ``"descending"``).
        search: Full-text search term applied to profile properties.
        distinct_id: Look up a single user by distinct ID.
        distinct_ids: Batch look up multiple users by distinct IDs.
        group_id: Query group profiles instead of user profiles.
        as_of: Point-in-time query. An ISO date string (``YYYY-MM-DD``)
            is converted to a Unix timestamp; an ``int`` is passed
            through directly.
        mode: Output mode (``"profiles"`` or ``"aggregate"``).
        aggregate: Aggregation function for aggregate mode. One of
            ``"count"`` (profile count), ``"extremes"`` (min/max),
            ``"percentile"`` (Nth percentile), or
            ``"numeric_summary"`` (count/mean/var/sum_of_squares).
        aggregate_property: Property to aggregate on (required for
            non-count aggregations).
        percentile: Percentile value (0-100 exclusive). Required
            when ``aggregate="percentile"``.
        segment_by: Cohort IDs for segmented aggregation.
        limit: Maximum profiles to return. Defaults to ``1``. Used
            for argument-level validation (U3); not included in the
            returned params dict.
        parallel: Whether to enable concurrent page fetching.
            Accepted for signature compatibility with ``query_user()``
            but has no effect on the returned params dict.
        workers: Maximum concurrent workers for parallel fetching.
            Accepted for signature compatibility with ``query_user()``
            but has no effect on the returned params dict.
        include_all_users: Include non-members in cohort query results.

    Returns:
        Engage API params dict. Does not include pagination params
        (``page``, ``session_id``) or ``limit``, which are added at
        execution time by ``query_user()``.

    Raises:
        BookmarkValidationError: If any validation rule fails at
            either the argument level (U1-U28) or the param level
            (UP1-UP4).

    Example:
        ```python
        ws = Workspace()
        params = ws.build_user_params(
            where=Filter.equals("plan", "premium"),
            sort_by="ltv",
        )
        print(params)
        # {"where": 'properties["plan"] == "premium"',
        #  "sort_key": 'properties["ltv"]',
        #  "sort_order": "descending"}
        ```
    """
    return self._resolve_and_build_user_params(
        where=where,
        cohort=cohort,
        properties=properties,
        sort_by=sort_by,
        sort_order=sort_order,
        search=search,
        distinct_id=distinct_id,
        distinct_ids=distinct_ids,
        group_id=group_id,
        as_of=as_of,
        mode=mode,
        aggregate=aggregate,
        aggregate_property=aggregate_property,
        percentile=percentile,
        segment_by=segment_by,
        limit=limit,
        parallel=parallel,
        workers=workers,
        include_all_users=include_all_users,
    )

run_user_params ¶

run_user_params(
    params: dict[str, Any],
    *,
    limit: int | None = 1,
    parallel: bool = False,
    workers: int = 5,
) -> UserQueryResult

Run pre-built Engage API params against the Mixpanel API.

The execution half of :meth:build_user_params. The mode is read from the params: a dict that carries an aggregate action key runs as an aggregate query, any other dict runs as a profiles query. limit, parallel and workers are execution settings that :meth:build_user_params does not store, so they are passed here with the same defaults as :meth:query_user.

PARAMETER	DESCRIPTION
`params`	Engage API params dict, normally from :meth:`build_user_params`. TYPE: `dict[str, Any]`
`limit`	Maximum profiles to return in profiles mode. `None` fetches all matching profiles. Ignored in aggregate mode. Default: `1`. TYPE: `int \| None` DEFAULT: `1`
`parallel`	Fetch profile pages concurrently. Ignored when `limit` is `1` or in aggregate mode. Default: `False`. TYPE: `bool` DEFAULT: `False`
`workers`	Maximum concurrent workers for parallel fetching. Default: `5`. TYPE: `int` DEFAULT: `5`

RETURNS	DESCRIPTION
`UserQueryResult`	`UserQueryResult` with profiles or aggregate data, total
`UserQueryResult`	count, DataFrame, and execution metadata.

RAISES	DESCRIPTION
`AuthenticationError`	Invalid credentials (401).
`RateLimitError`	API rate limit exceeded (429).
`APIError`	Other API communication errors.

Example

params = ws.build_user_params(
    mode="profiles", where=Filter.equals("plan", "premium")
)
params["output_properties"] = json.dumps(["$email", "ltv"])
result = ws.run_user_params(params, limit=500, parallel=True)
print(result.df.head())

Source code in src/mixpanel_headless/workspace.py

def run_user_params(
    self,
    params: dict[str, Any],
    *,
    limit: int | None = 1,
    parallel: bool = False,
    workers: int = 5,
) -> UserQueryResult:
    """Run pre-built Engage API params against the Mixpanel API.

    The execution half of :meth:`build_user_params`. The mode is read
    from the params: a dict that carries an aggregate ``action`` key
    runs as an aggregate query, any other dict runs as a profiles
    query. ``limit``, ``parallel`` and ``workers`` are execution
    settings that :meth:`build_user_params` does not store, so they
    are passed here with the same defaults as :meth:`query_user`.

    Args:
        params: Engage API params dict, normally from
            :meth:`build_user_params`.
        limit: Maximum profiles to return in profiles mode. ``None``
            fetches all matching profiles. Ignored in aggregate mode.
            Default: ``1``.
        parallel: Fetch profile pages concurrently. Ignored when
            ``limit`` is ``1`` or in aggregate mode. Default: ``False``.
        workers: Maximum concurrent workers for parallel fetching.
            Default: ``5``.

    Returns:
        ``UserQueryResult`` with profiles or aggregate data, total
        count, DataFrame, and execution metadata.

    Raises:
        AuthenticationError: Invalid credentials (401).
        RateLimitError: API rate limit exceeded (429).
        APIError: Other API communication errors.

    Example:
        ```python
        params = ws.build_user_params(
            mode="profiles", where=Filter.equals("plan", "premium")
        )
        params["output_properties"] = json.dumps(["$email", "ltv"])
        result = ws.run_user_params(params, limit=500, parallel=True)
        print(result.df.head())
        ```
    """
    if "action" in params:
        aggregate_data, total, computed_at, meta = self._execute_user_aggregate(
            params
        )
        return UserQueryResult(
            computed_at=computed_at,
            total=total,
            profiles=[],
            params=params,
            meta=meta,
            mode="aggregate",
            aggregate_data=aggregate_data,
        )

    # Profiles mode — choose sequential or parallel
    if parallel and limit != 1:
        profiles, total, computed_at, meta = self._execute_user_query_parallel(
            params, limit, workers
        )
    else:
        if parallel and limit == 1:
            logger.debug("parallel=True ignored: limit=1 uses sequential path")
        profiles, total, computed_at, meta = self._execute_user_query_sequential(
            params, limit
        )

    return UserQueryResult(
        computed_at=computed_at,
        total=total,
        profiles=profiles,
        params=params,
        meta=meta,
        mode="profiles",
        aggregate_data=None,
    )

segmentation ¶

segmentation(
    event: str,
    *,
    from_date: str,
    to_date: str,
    on: str | None = None,
    unit: Literal["day", "week", "month"] = "day",
    where: str | None = None,
) -> SegmentationResult

Run a segmentation query against Mixpanel API.

PARAMETER	DESCRIPTION
`event`	Event name to query. TYPE: `str`
`from_date`	Start date (YYYY-MM-DD). TYPE: `str`
`to_date`	End date (YYYY-MM-DD). TYPE: `str`
`on`	Optional property to segment by. TYPE: `str \| None` DEFAULT: `None`
`unit`	Time unit for aggregation. TYPE: `Literal['day', 'week', 'month']` DEFAULT: `'day'`
`where`	Optional WHERE clause. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`SegmentationResult`	SegmentationResult with time-series data.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def segmentation(
    self,
    event: str,
    *,
    from_date: str,
    to_date: str,
    on: str | None = None,
    unit: Literal["day", "week", "month"] = "day",
    where: str | None = None,
) -> SegmentationResult:
    """Run a segmentation query against Mixpanel API.

    Args:
        event: Event name to query.
        from_date: Start date (YYYY-MM-DD).
        to_date: End date (YYYY-MM-DD).
        on: Optional property to segment by.
        unit: Time unit for aggregation.
        where: Optional WHERE clause.

    Returns:
        SegmentationResult with time-series data.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._live_query_service.segmentation(
        event=event,
        from_date=from_date,
        to_date=to_date,
        on=on,
        unit=unit,
        where=where,
    )

funnel ¶

funnel(
    funnel_id: int,
    *,
    from_date: str,
    to_date: str,
    unit: str | None = None,
    on: str | None = None,
) -> FunnelResult

Run a funnel analysis query.

PARAMETER	DESCRIPTION
`funnel_id`	ID of saved funnel. TYPE: `int`
`from_date`	Start date (YYYY-MM-DD). TYPE: `str`
`to_date`	End date (YYYY-MM-DD). TYPE: `str`
`unit`	Optional time unit. TYPE: `str \| None` DEFAULT: `None`
`on`	Optional property to segment by. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`FunnelResult`	FunnelResult with step conversion rates.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def funnel(
    self,
    funnel_id: int,
    *,
    from_date: str,
    to_date: str,
    unit: str | None = None,
    on: str | None = None,
) -> FunnelResult:
    """Run a funnel analysis query.

    Args:
        funnel_id: ID of saved funnel.
        from_date: Start date (YYYY-MM-DD).
        to_date: End date (YYYY-MM-DD).
        unit: Optional time unit.
        on: Optional property to segment by.

    Returns:
        FunnelResult with step conversion rates.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._live_query_service.funnel(
        funnel_id=funnel_id,
        from_date=from_date,
        to_date=to_date,
        unit=unit,
        on=on,
    )

retention ¶

retention(
    *,
    born_event: str,
    return_event: str,
    from_date: str,
    to_date: str,
    born_where: str | None = None,
    return_where: str | None = None,
    interval: int = 1,
    interval_count: int = 10,
    unit: Literal["day", "week", "month"] = "day",
) -> RetentionResult

Run a retention analysis query.

PARAMETER	DESCRIPTION
`born_event`	Event that defines cohort entry. TYPE: `str`
`return_event`	Event that defines return. TYPE: `str`
`from_date`	Start date (YYYY-MM-DD). TYPE: `str`
`to_date`	End date (YYYY-MM-DD). TYPE: `str`
`born_where`	Optional filter for born event. TYPE: `str \| None` DEFAULT: `None`
`return_where`	Optional filter for return event. TYPE: `str \| None` DEFAULT: `None`
`interval`	Retention interval. TYPE: `int` DEFAULT: `1`
`interval_count`	Number of intervals. TYPE: `int` DEFAULT: `10`
`unit`	Time unit. TYPE: `Literal['day', 'week', 'month']` DEFAULT: `'day'`

RETURNS	DESCRIPTION
`RetentionResult`	RetentionResult with cohort retention data.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def retention(
    self,
    *,
    born_event: str,
    return_event: str,
    from_date: str,
    to_date: str,
    born_where: str | None = None,
    return_where: str | None = None,
    interval: int = 1,
    interval_count: int = 10,
    unit: Literal["day", "week", "month"] = "day",
) -> RetentionResult:
    """Run a retention analysis query.

    Args:
        born_event: Event that defines cohort entry.
        return_event: Event that defines return.
        from_date: Start date (YYYY-MM-DD).
        to_date: End date (YYYY-MM-DD).
        born_where: Optional filter for born event.
        return_where: Optional filter for return event.
        interval: Retention interval.
        interval_count: Number of intervals.
        unit: Time unit.

    Returns:
        RetentionResult with cohort retention data.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._live_query_service.retention(
        born_event=born_event,
        return_event=return_event,
        from_date=from_date,
        to_date=to_date,
        born_where=born_where,
        return_where=return_where,
        interval=interval,
        interval_count=interval_count,
        unit=unit,
    )

event_counts ¶

event_counts(
    events: list[str],
    *,
    from_date: str,
    to_date: str,
    type: Literal["general", "unique", "average"] = "general",
    unit: Literal["day", "week", "month"] = "day",
) -> EventCountsResult

Get event counts for multiple events.

PARAMETER	DESCRIPTION
`events`	List of event names. TYPE: `list[str]`
`from_date`	Start date (YYYY-MM-DD). TYPE: `str`
`to_date`	End date (YYYY-MM-DD). TYPE: `str`
`type`	Counting method. TYPE: `Literal['general', 'unique', 'average']` DEFAULT: `'general'`
`unit`	Time unit. TYPE: `Literal['day', 'week', 'month']` DEFAULT: `'day'`

RETURNS	DESCRIPTION
`EventCountsResult`	EventCountsResult with time-series per event.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def event_counts(
    self,
    events: list[str],
    *,
    from_date: str,
    to_date: str,
    type: Literal["general", "unique", "average"] = "general",
    unit: Literal["day", "week", "month"] = "day",
) -> EventCountsResult:
    """Get event counts for multiple events.

    Args:
        events: List of event names.
        from_date: Start date (YYYY-MM-DD).
        to_date: End date (YYYY-MM-DD).
        type: Counting method.
        unit: Time unit.

    Returns:
        EventCountsResult with time-series per event.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._live_query_service.event_counts(
        events=events,
        from_date=from_date,
        to_date=to_date,
        type=type,
        unit=unit,
    )

property_counts ¶

property_counts(
    event: str,
    property_name: str,
    *,
    from_date: str,
    to_date: str,
    type: Literal["general", "unique", "average"] = "general",
    unit: Literal["day", "week", "month"] = "day",
    values: list[str] | None = None,
    limit: int | None = None,
) -> PropertyCountsResult

Get event counts broken down by property values.

PARAMETER	DESCRIPTION
`event`	Event name. TYPE: `str`
`property_name`	Property to break down by. TYPE: `str`
`from_date`	Start date (YYYY-MM-DD). TYPE: `str`
`to_date`	End date (YYYY-MM-DD). TYPE: `str`
`type`	Counting method. TYPE: `Literal['general', 'unique', 'average']` DEFAULT: `'general'`
`unit`	Time unit. TYPE: `Literal['day', 'week', 'month']` DEFAULT: `'day'`
`values`	Optional list of property values to include. TYPE: `list[str] \| None` DEFAULT: `None`
`limit`	Maximum number of property values. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`PropertyCountsResult`	PropertyCountsResult with time-series per property value.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def property_counts(
    self,
    event: str,
    property_name: str,
    *,
    from_date: str,
    to_date: str,
    type: Literal["general", "unique", "average"] = "general",
    unit: Literal["day", "week", "month"] = "day",
    values: list[str] | None = None,
    limit: int | None = None,
) -> PropertyCountsResult:
    """Get event counts broken down by property values.

    Args:
        event: Event name.
        property_name: Property to break down by.
        from_date: Start date (YYYY-MM-DD).
        to_date: End date (YYYY-MM-DD).
        type: Counting method.
        unit: Time unit.
        values: Optional list of property values to include.
        limit: Maximum number of property values.

    Returns:
        PropertyCountsResult with time-series per property value.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._live_query_service.property_counts(
        event=event,
        property_name=property_name,
        from_date=from_date,
        to_date=to_date,
        type=type,
        unit=unit,
        values=values,
        limit=limit,
    )

activity_feed ¶

activity_feed(
    distinct_ids: list[str],
    *,
    from_date: str | None = None,
    to_date: str | None = None,
    limit: int | None = None,
    include_events: list[str] | None = None,
    exclude_events: list[str] | None = None,
    sentinel_event: dict[str, Any] | None = None,
    paging_window: int | None = None,
    search: str | None = None,
    search_properties: list[dict[str, Any]] | None = None,
    use_custom_events: bool = False,
) -> ActivityFeedResult

Get activity feed for specific users.

Returns a user's events sorted chronologically (oldest-first within a page). When limit is set, the most recent events come first; use the sentinel_event cursor (carried on the result) to page backward to older events. Backed by the stream/bookmark endpoint; also filterable by event name or full-text search.

PARAMETER	DESCRIPTION
`distinct_ids`	List of user identifiers. TYPE: `list[str]`
`from_date`	Optional start date filter (`YYYY-MM-DD`). When both dates are omitted, defaults to the last 30 days. TYPE: `str \| None` DEFAULT: `None`
`to_date`	Optional end date filter (`YYYY-MM-DD`). TYPE: `str \| None` DEFAULT: `None`
`limit`	Optional max events to return (server ceiling 15000). TYPE: `int \| None` DEFAULT: `None`
`include_events`	Optional event names to include; mutually exclusive with `exclude_events`. TYPE: `list[str] \| None` DEFAULT: `None`
`exclude_events`	Optional event names to exclude; mutually exclusive with `include_events`. TYPE: `list[str] \| None` DEFAULT: `None`
`sentinel_event`	Optional pagination cursor from a prior result's `sentinel_event`; pass it back to fetch the next page. TYPE: `dict[str, Any] \| None` DEFAULT: `None`
`paging_window`	Optional days (<= 30) bounding each page's scan window. TYPE: `int \| None` DEFAULT: `None`
`search`	Optional full-text search string applied to events. TYPE: `str \| None` DEFAULT: `None`
`search_properties`	Optional property descriptors to restrict the `search` to (each a `{"value", "resourceType"}` dict). TYPE: `list[dict[str, Any]] \| None` DEFAULT: `None`
`use_custom_events`	When `True`, label matching custom events in raw results. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`ActivityFeedResult`	ActivityFeedResult with user events plus a `sentinel_event` cursor
`ActivityFeedResult`	(`None` when there are no further pages).

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.
`QueryError`	If both `include_events` and `exclude_events` are given.

Example

page = ws.activity_feed(
    ["u1"], from_date="2026-05-01", to_date="2026-06-01"
)
while page.sentinel_event:
    page = ws.activity_feed(
        ["u1"],
        from_date="2026-05-01",
        to_date="2026-06-01",
        sentinel_event=page.sentinel_event,
    )

Source code in src/mixpanel_headless/workspace.py

def activity_feed(
    self,
    distinct_ids: list[str],
    *,
    from_date: str | None = None,
    to_date: str | None = None,
    limit: int | None = None,
    include_events: list[str] | None = None,
    exclude_events: list[str] | None = None,
    sentinel_event: dict[str, Any] | None = None,
    paging_window: int | None = None,
    search: str | None = None,
    search_properties: list[dict[str, Any]] | None = None,
    use_custom_events: bool = False,
) -> ActivityFeedResult:
    """Get activity feed for specific users.

    Returns a user's events sorted chronologically (oldest-first within a
    page). When ``limit`` is set, the most recent events come first; use the
    ``sentinel_event`` cursor (carried on the result) to page backward to
    older events. Backed by the stream/bookmark endpoint; also filterable by
    event name or full-text search.

    Args:
        distinct_ids: List of user identifiers.
        from_date: Optional start date filter (``YYYY-MM-DD``). When both
            dates are omitted, defaults to the last 30 days.
        to_date: Optional end date filter (``YYYY-MM-DD``).
        limit: Optional max events to return (server ceiling 15000).
        include_events: Optional event names to include; mutually exclusive
            with ``exclude_events``.
        exclude_events: Optional event names to exclude; mutually exclusive
            with ``include_events``.
        sentinel_event: Optional pagination cursor from a prior result's
            ``sentinel_event``; pass it back to fetch the next page.
        paging_window: Optional days (<= 30) bounding each page's scan window.
        search: Optional full-text search string applied to events.
        search_properties: Optional property descriptors to restrict the
            ``search`` to (each a ``{"value", "resourceType"}`` dict).
        use_custom_events: When ``True``, label matching custom events in
            raw results.

    Returns:
        ActivityFeedResult with user events plus a ``sentinel_event`` cursor
        (``None`` when there are no further pages).

    Raises:
        ConfigError: If API credentials not available.
        QueryError: If both ``include_events`` and ``exclude_events`` are
            given.

    Example:
        ```python
        page = ws.activity_feed(
            ["u1"], from_date="2026-05-01", to_date="2026-06-01"
        )
        while page.sentinel_event:
            page = ws.activity_feed(
                ["u1"],
                from_date="2026-05-01",
                to_date="2026-06-01",
                sentinel_event=page.sentinel_event,
            )
        ```
    """
    return self._live_query_service.activity_feed(
        distinct_ids=distinct_ids,
        from_date=from_date,
        to_date=to_date,
        limit=limit,
        include_events=include_events,
        exclude_events=exclude_events,
        sentinel_event=sentinel_event,
        paging_window=paging_window,
        search=search,
        search_properties=search_properties,
        use_custom_events=use_custom_events,
    )

query_saved_report ¶

query_saved_report(
    bookmark_id: int,
    *,
    bookmark_type: Literal[
        "insights", "funnels", "retention", "flows"
    ] = "insights",
    from_date: str | None = None,
    to_date: str | None = None,
) -> SavedReportResult

Query a saved report by bookmark type.

Routes to the appropriate Mixpanel API endpoint based on bookmark_type and returns the normalized result.

PARAMETER	DESCRIPTION
`bookmark_id`	ID of saved report (from list_bookmarks or Mixpanel URL). TYPE: `int`
`bookmark_type`	Type of bookmark to query. Determines which API endpoint is called. Defaults to 'insights'. TYPE: `Literal['insights', 'funnels', 'retention', 'flows']` DEFAULT: `'insights'`
`from_date`	Start date (YYYY-MM-DD). Required for funnels, optional otherwise. TYPE: `str \| None` DEFAULT: `None`
`to_date`	End date (YYYY-MM-DD). Required for funnels, optional otherwise. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`SavedReportResult`	SavedReportResult with report data and report_type property.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.
`QueryError`	If bookmark_id is invalid or report not found.

Source code in src/mixpanel_headless/workspace.py

def query_saved_report(
    self,
    bookmark_id: int,
    *,
    bookmark_type: Literal[
        "insights", "funnels", "retention", "flows"
    ] = "insights",
    from_date: str | None = None,
    to_date: str | None = None,
) -> SavedReportResult:
    """Query a saved report by bookmark type.

    Routes to the appropriate Mixpanel API endpoint based on bookmark_type
    and returns the normalized result.

    Args:
        bookmark_id: ID of saved report (from list_bookmarks or Mixpanel URL).
        bookmark_type: Type of bookmark to query. Determines which API endpoint
            is called. Defaults to 'insights'.
        from_date: Start date (YYYY-MM-DD). Required for funnels, optional otherwise.
        to_date: End date (YYYY-MM-DD). Required for funnels, optional otherwise.

    Returns:
        SavedReportResult with report data and report_type property.

    Raises:
        ConfigError: If API credentials not available.
        QueryError: If bookmark_id is invalid or report not found.
    """
    return self._live_query_service.query_saved_report(
        bookmark_id=bookmark_id,
        bookmark_type=bookmark_type,
        from_date=from_date,
        to_date=to_date,
    )

query_saved_flows ¶

query_saved_flows(bookmark_id: int) -> FlowsResult

Query a saved Flows report.

Executes a saved Flows report by its bookmark ID, returning step data, breakdowns, and conversion rates.

PARAMETER	DESCRIPTION
`bookmark_id`	ID of saved flows report (from list_bookmarks or Mixpanel URL). TYPE: `int`

RETURNS	DESCRIPTION
`FlowsResult`	FlowsResult with steps, breakdowns, and conversion rate.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.
`QueryError`	If bookmark_id is invalid or report not found.

Source code in src/mixpanel_headless/workspace.py

def query_saved_flows(self, bookmark_id: int) -> FlowsResult:
    """Query a saved Flows report.

    Executes a saved Flows report by its bookmark ID, returning
    step data, breakdowns, and conversion rates.

    Args:
        bookmark_id: ID of saved flows report (from list_bookmarks or Mixpanel URL).

    Returns:
        FlowsResult with steps, breakdowns, and conversion rate.

    Raises:
        ConfigError: If API credentials not available.
        QueryError: If bookmark_id is invalid or report not found.
    """
    return self._live_query_service.query_saved_flows(bookmark_id=bookmark_id)

frequency ¶

frequency(
    *,
    from_date: str,
    to_date: str,
    unit: Literal["day", "week", "month"] = "day",
    addiction_unit: Literal["hour", "day"] = "hour",
    event: str | None = None,
    where: str | None = None,
) -> FrequencyResult

Analyze event frequency distribution.

PARAMETER	DESCRIPTION
`from_date`	Start date (YYYY-MM-DD). TYPE: `str`
`to_date`	End date (YYYY-MM-DD). TYPE: `str`
`unit`	Overall time unit. TYPE: `Literal['day', 'week', 'month']` DEFAULT: `'day'`
`addiction_unit`	Measurement granularity. TYPE: `Literal['hour', 'day']` DEFAULT: `'hour'`
`event`	Optional event filter. TYPE: `str \| None` DEFAULT: `None`
`where`	Optional WHERE clause. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`FrequencyResult`	FrequencyResult with frequency distribution.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def frequency(
    self,
    *,
    from_date: str,
    to_date: str,
    unit: Literal["day", "week", "month"] = "day",
    addiction_unit: Literal["hour", "day"] = "hour",
    event: str | None = None,
    where: str | None = None,
) -> FrequencyResult:
    """Analyze event frequency distribution.

    Args:
        from_date: Start date (YYYY-MM-DD).
        to_date: End date (YYYY-MM-DD).
        unit: Overall time unit.
        addiction_unit: Measurement granularity.
        event: Optional event filter.
        where: Optional WHERE clause.

    Returns:
        FrequencyResult with frequency distribution.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._live_query_service.frequency(
        from_date=from_date,
        to_date=to_date,
        unit=unit,
        addiction_unit=addiction_unit,
        event=event,
        where=where,
    )

segmentation_numeric ¶

segmentation_numeric(
    event: str,
    *,
    from_date: str,
    to_date: str,
    on: str,
    unit: Literal["hour", "day"] = "day",
    where: str | None = None,
    type: Literal["general", "unique", "average"] = "general",
) -> NumericBucketResult

Bucket events by numeric property ranges.

PARAMETER	DESCRIPTION
`event`	Event name. TYPE: `str`
`from_date`	Start date. TYPE: `str`
`to_date`	End date. TYPE: `str`
`on`	Numeric property expression. TYPE: `str`
`unit`	Time unit. TYPE: `Literal['hour', 'day']` DEFAULT: `'day'`
`where`	Optional filter. TYPE: `str \| None` DEFAULT: `None`
`type`	Counting method. TYPE: `Literal['general', 'unique', 'average']` DEFAULT: `'general'`

RETURNS	DESCRIPTION
`NumericBucketResult`	NumericBucketResult with bucketed data.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def segmentation_numeric(
    self,
    event: str,
    *,
    from_date: str,
    to_date: str,
    on: str,
    unit: Literal["hour", "day"] = "day",
    where: str | None = None,
    type: Literal["general", "unique", "average"] = "general",
) -> NumericBucketResult:
    """Bucket events by numeric property ranges.

    Args:
        event: Event name.
        from_date: Start date.
        to_date: End date.
        on: Numeric property expression.
        unit: Time unit.
        where: Optional filter.
        type: Counting method.

    Returns:
        NumericBucketResult with bucketed data.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._live_query_service.segmentation_numeric(
        event=event,
        from_date=from_date,
        to_date=to_date,
        on=on,
        unit=unit,
        where=where,
        type=type,
    )

segmentation_sum ¶

segmentation_sum(
    event: str,
    *,
    from_date: str,
    to_date: str,
    on: str,
    unit: Literal["hour", "day"] = "day",
    where: str | None = None,
) -> NumericSumResult

Calculate sum of numeric property over time.

PARAMETER	DESCRIPTION
`event`	Event name. TYPE: `str`
`from_date`	Start date. TYPE: `str`
`to_date`	End date. TYPE: `str`
`on`	Numeric property expression. TYPE: `str`
`unit`	Time unit. TYPE: `Literal['hour', 'day']` DEFAULT: `'day'`
`where`	Optional filter. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`NumericSumResult`	NumericSumResult with sum values per period.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def segmentation_sum(
    self,
    event: str,
    *,
    from_date: str,
    to_date: str,
    on: str,
    unit: Literal["hour", "day"] = "day",
    where: str | None = None,
) -> NumericSumResult:
    """Calculate sum of numeric property over time.

    Args:
        event: Event name.
        from_date: Start date.
        to_date: End date.
        on: Numeric property expression.
        unit: Time unit.
        where: Optional filter.

    Returns:
        NumericSumResult with sum values per period.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._live_query_service.segmentation_sum(
        event=event,
        from_date=from_date,
        to_date=to_date,
        on=on,
        unit=unit,
        where=where,
    )

segmentation_average ¶

segmentation_average(
    event: str,
    *,
    from_date: str,
    to_date: str,
    on: str,
    unit: Literal["hour", "day"] = "day",
    where: str | None = None,
) -> NumericAverageResult

Calculate average of numeric property over time.

PARAMETER	DESCRIPTION
`event`	Event name. TYPE: `str`
`from_date`	Start date. TYPE: `str`
`to_date`	End date. TYPE: `str`
`on`	Numeric property expression. TYPE: `str`
`unit`	Time unit. TYPE: `Literal['hour', 'day']` DEFAULT: `'day'`
`where`	Optional filter. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`NumericAverageResult`	NumericAverageResult with average values per period.

RAISES	DESCRIPTION
`ConfigError`	If API credentials not available.

Source code in src/mixpanel_headless/workspace.py

def segmentation_average(
    self,
    event: str,
    *,
    from_date: str,
    to_date: str,
    on: str,
    unit: Literal["hour", "day"] = "day",
    where: str | None = None,
) -> NumericAverageResult:
    """Calculate average of numeric property over time.

    Args:
        event: Event name.
        from_date: Start date.
        to_date: End date.
        on: Numeric property expression.
        unit: Time unit.
        where: Optional filter.

    Returns:
        NumericAverageResult with average values per period.

    Raises:
        ConfigError: If API credentials not available.
    """
    return self._live_query_service.segmentation_average(
        event=event,
        from_date=from_date,
        to_date=to_date,
        on=on,
        unit=unit,
        where=where,
    )

list_dashboards ¶

list_dashboards(*, ids: list[int] | None = None) -> list[Dashboard]

List dashboards for the current project/workspace.

Retrieves all dashboards visible to the authenticated user, optionally filtered by specific IDs.

PARAMETER	DESCRIPTION
`ids`	Optional list of dashboard IDs to filter by. TYPE: `list[int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[Dashboard]`	List of `Dashboard` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dashboards = ws.list_dashboards()
for d in dashboards:
    print(f"{d.title} (id={d.id})")

Source code in src/mixpanel_headless/workspace.py

def list_dashboards(self, *, ids: list[int] | None = None) -> list[Dashboard]:
    """List dashboards for the current project/workspace.

    Retrieves all dashboards visible to the authenticated user,
    optionally filtered by specific IDs.

    Args:
        ids: Optional list of dashboard IDs to filter by.

    Returns:
        List of ``Dashboard`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dashboards = ws.list_dashboards()
        for d in dashboards:
            print(f"{d.title} (id={d.id})")
        ```
    """
    client = self._require_api_client()
    raw = client.list_dashboards(ids=ids)
    return validate_response_models(Dashboard, raw, endpoint="list_dashboards")

create_dashboard ¶

create_dashboard(params: CreateDashboardParams) -> Dashboard

Create a new dashboard.

PARAMETER	DESCRIPTION
`params`	Dashboard creation parameters. TYPE: `CreateDashboardParams`

RETURNS	DESCRIPTION
`Dashboard`	The newly created `Dashboard`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid parameters (400, 422).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dashboard = ws.create_dashboard(
    CreateDashboardParams(title="Q1 Metrics")
)

Source code in src/mixpanel_headless/workspace.py

def create_dashboard(self, params: CreateDashboardParams) -> Dashboard:
    """Create a new dashboard.

    Args:
        params: Dashboard creation parameters.

    Returns:
        The newly created ``Dashboard``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid parameters (400, 422).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dashboard = ws.create_dashboard(
            CreateDashboardParams(title="Q1 Metrics")
        )
        ```
    """
    client = self._require_api_client()
    raw = client.create_dashboard(params.model_dump(exclude_none=True))
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for create_dashboard",
        )
    return validate_response_model(Dashboard, raw, endpoint="create_dashboard")

get_dashboard ¶

get_dashboard(dashboard_id: int) -> Dashboard

Get a single dashboard by ID.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`

RETURNS	DESCRIPTION
`Dashboard`	The `Dashboard` object.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dashboard = ws.get_dashboard(12345)

Source code in src/mixpanel_headless/workspace.py

def get_dashboard(self, dashboard_id: int) -> Dashboard:
    """Get a single dashboard by ID.

    Args:
        dashboard_id: Dashboard identifier.

    Returns:
        The ``Dashboard`` object.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dashboard = ws.get_dashboard(12345)
        ```
    """
    client = self._require_api_client()
    raw = client.get_dashboard(dashboard_id)
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for get_dashboard",
        )
    return validate_response_model(Dashboard, raw, endpoint="get_dashboard")

update_dashboard ¶

update_dashboard(dashboard_id: int, params: UpdateDashboardParams) -> Dashboard

Update an existing dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`
`params`	Fields to update. TYPE: `UpdateDashboardParams`

RETURNS	DESCRIPTION
`Dashboard`	The updated `Dashboard`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard not found or invalid params (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
updated = ws.update_dashboard(
    12345, UpdateDashboardParams(title="New Title")
)

Source code in src/mixpanel_headless/workspace.py

def update_dashboard(
    self, dashboard_id: int, params: UpdateDashboardParams
) -> Dashboard:
    """Update an existing dashboard.

    Args:
        dashboard_id: Dashboard identifier.
        params: Fields to update.

    Returns:
        The updated ``Dashboard``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard not found or invalid params (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        updated = ws.update_dashboard(
            12345, UpdateDashboardParams(title="New Title")
        )
        ```
    """
    client = self._require_api_client()
    raw = client.update_dashboard(
        dashboard_id, params.model_dump(exclude_none=True)
    )
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for update_dashboard",
        )
    return validate_response_model(Dashboard, raw, endpoint="update_dashboard")

delete_dashboard ¶

delete_dashboard(dashboard_id: int) -> None

Delete a dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_dashboard(12345)

Source code in src/mixpanel_headless/workspace.py

def delete_dashboard(self, dashboard_id: int) -> None:
    """Delete a dashboard.

    Args:
        dashboard_id: Dashboard identifier.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_dashboard(12345)
        ```
    """
    client = self._require_api_client()
    client.delete_dashboard(dashboard_id)

bulk_delete_dashboards ¶

bulk_delete_dashboards(ids: list[int]) -> None

Delete multiple dashboards.

PARAMETER	DESCRIPTION
`ids`	List of dashboard IDs to delete. TYPE: `list[int]`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	One or more IDs not found (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.bulk_delete_dashboards([1, 2, 3])

Source code in src/mixpanel_headless/workspace.py

def bulk_delete_dashboards(self, ids: list[int]) -> None:
    """Delete multiple dashboards.

    Args:
        ids: List of dashboard IDs to delete.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: One or more IDs not found (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.bulk_delete_dashboards([1, 2, 3])
        ```
    """
    client = self._require_api_client()
    client.bulk_delete_dashboards(ids)

favorite_dashboard ¶

favorite_dashboard(dashboard_id: int) -> None

Favorite a dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.favorite_dashboard(12345)

Source code in src/mixpanel_headless/workspace.py

def favorite_dashboard(self, dashboard_id: int) -> None:
    """Favorite a dashboard.

    Args:
        dashboard_id: Dashboard identifier.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.favorite_dashboard(12345)
        ```
    """
    client = self._require_api_client()
    client.favorite_dashboard(dashboard_id)

unfavorite_dashboard ¶

unfavorite_dashboard(dashboard_id: int) -> None

Unfavorite a dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.unfavorite_dashboard(12345)

Source code in src/mixpanel_headless/workspace.py

def unfavorite_dashboard(self, dashboard_id: int) -> None:
    """Unfavorite a dashboard.

    Args:
        dashboard_id: Dashboard identifier.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.unfavorite_dashboard(12345)
        ```
    """
    client = self._require_api_client()
    client.unfavorite_dashboard(dashboard_id)

pin_dashboard ¶

pin_dashboard(dashboard_id: int) -> None

Pin a dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.pin_dashboard(12345)

Source code in src/mixpanel_headless/workspace.py

def pin_dashboard(self, dashboard_id: int) -> None:
    """Pin a dashboard.

    Args:
        dashboard_id: Dashboard identifier.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.pin_dashboard(12345)
        ```
    """
    client = self._require_api_client()
    client.pin_dashboard(dashboard_id)

unpin_dashboard ¶

unpin_dashboard(dashboard_id: int) -> None

Unpin a dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.unpin_dashboard(12345)

Source code in src/mixpanel_headless/workspace.py

def unpin_dashboard(self, dashboard_id: int) -> None:
    """Unpin a dashboard.

    Args:
        dashboard_id: Dashboard identifier.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.unpin_dashboard(12345)
        ```
    """
    client = self._require_api_client()
    client.unpin_dashboard(dashboard_id)

add_report_to_dashboard ¶

add_report_to_dashboard(dashboard_id: int, bookmark_id: int) -> Dashboard

Add a report to a dashboard.

Clones the specified bookmark onto the dashboard. The cloned report appears as a new card in the dashboard layout.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`
`bookmark_id`	Bookmark/report identifier to add. TYPE: `int`

RETURNS	DESCRIPTION
`Dashboard`	The updated `Dashboard`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard or bookmark not found (404).
`ServerError`	Server-side errors (5xx).
`MixpanelHeadlessError`	If the API response is not a valid dashboard dict.

Example

ws = Workspace()
updated = ws.add_report_to_dashboard(12345, 42)

Source code in src/mixpanel_headless/workspace.py

def add_report_to_dashboard(self, dashboard_id: int, bookmark_id: int) -> Dashboard:
    """Add a report to a dashboard.

    Clones the specified bookmark onto the dashboard. The cloned report
    appears as a new card in the dashboard layout.

    Args:
        dashboard_id: Dashboard identifier.
        bookmark_id: Bookmark/report identifier to add.

    Returns:
        The updated ``Dashboard``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard or bookmark not found (404).
        ServerError: Server-side errors (5xx).
        MixpanelHeadlessError: If the API response is not a valid dashboard dict.

    Example:
        ```python
        ws = Workspace()
        updated = ws.add_report_to_dashboard(12345, 42)
        ```
    """
    client = self._require_api_client()
    raw = client.add_report_to_dashboard(dashboard_id, bookmark_id)
    if not isinstance(raw, dict) or "id" not in raw:
        raise MixpanelHeadlessError(
            "Unexpected response from add_report_to_dashboard: "
            f"expected dashboard dict with 'id', got {raw!r}",
        )
    return validate_response_model(
        Dashboard, raw, endpoint="add_report_to_dashboard"
    )

remove_report_from_dashboard ¶

remove_report_from_dashboard(dashboard_id: int, bookmark_id: int) -> Dashboard

Remove a report from a dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`
`bookmark_id`	Bookmark/report identifier to remove. TYPE: `int`

RETURNS	DESCRIPTION
`Dashboard`	The updated `Dashboard`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard or bookmark not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
updated = ws.remove_report_from_dashboard(12345, 42)

Source code in src/mixpanel_headless/workspace.py

def remove_report_from_dashboard(
    self, dashboard_id: int, bookmark_id: int
) -> Dashboard:
    """Remove a report from a dashboard.

    Args:
        dashboard_id: Dashboard identifier.
        bookmark_id: Bookmark/report identifier to remove.

    Returns:
        The updated ``Dashboard``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard or bookmark not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        updated = ws.remove_report_from_dashboard(12345, 42)
        ```
    """
    client = self._require_api_client()
    raw = client.remove_report_from_dashboard(dashboard_id, bookmark_id)
    return validate_response_model(
        Dashboard, raw, endpoint="remove_report_from_dashboard"
    )

list_blueprint_templates ¶

list_blueprint_templates(
    *, include_reports: bool = False
) -> list[BlueprintTemplate]

List available dashboard blueprint templates.

PARAMETER	DESCRIPTION
`include_reports`	Whether to include report details. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`list[BlueprintTemplate]`	List of `BlueprintTemplate` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
templates = ws.list_blueprint_templates()

Source code in src/mixpanel_headless/workspace.py

def list_blueprint_templates(
    self, *, include_reports: bool = False
) -> list[BlueprintTemplate]:
    """List available dashboard blueprint templates.

    Args:
        include_reports: Whether to include report details.

    Returns:
        List of ``BlueprintTemplate`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        templates = ws.list_blueprint_templates()
        ```
    """
    client = self._require_api_client()
    raw = client.list_blueprint_templates(include_reports=include_reports)
    return validate_response_models(
        BlueprintTemplate, raw, endpoint="list_blueprint_templates"
    )

create_blueprint ¶

create_blueprint(template_type: str) -> Dashboard

Create a dashboard from a blueprint template.

PARAMETER	DESCRIPTION
`template_type`	Blueprint template type identifier. TYPE: `str`

RETURNS	DESCRIPTION
`Dashboard`	The newly created `Dashboard`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid template type (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dashboard = ws.create_blueprint("onboarding")

Source code in src/mixpanel_headless/workspace.py

def create_blueprint(self, template_type: str) -> Dashboard:
    """Create a dashboard from a blueprint template.

    Args:
        template_type: Blueprint template type identifier.

    Returns:
        The newly created ``Dashboard``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid template type (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dashboard = ws.create_blueprint("onboarding")
        ```
    """
    client = self._require_api_client()
    raw = client.create_blueprint(template_type)
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for create_blueprint",
        )
    return validate_response_model(Dashboard, raw, endpoint="create_blueprint")

get_blueprint_config ¶

get_blueprint_config(dashboard_id: int) -> BlueprintConfig

Get the blueprint configuration for a dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`

RETURNS	DESCRIPTION
`BlueprintConfig`	`BlueprintConfig` with template variables.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
config = ws.get_blueprint_config(12345)

Source code in src/mixpanel_headless/workspace.py

def get_blueprint_config(self, dashboard_id: int) -> BlueprintConfig:
    """Get the blueprint configuration for a dashboard.

    Args:
        dashboard_id: Dashboard identifier.

    Returns:
        ``BlueprintConfig`` with template variables.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        config = ws.get_blueprint_config(12345)
        ```
    """
    client = self._require_api_client()
    raw = client.get_blueprint_config(dashboard_id)
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for get_blueprint_config",
        )
    return validate_response_model(
        BlueprintConfig, raw, endpoint="get_blueprint_config"
    )

update_blueprint_cohorts ¶

update_blueprint_cohorts(cohorts: list[dict[str, Any]]) -> None

Update cohorts for blueprint configuration.

PARAMETER	DESCRIPTION
`cohorts`	List of cohort configuration dicts. TYPE: `list[dict[str, Any]]`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid cohort configuration (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.update_blueprint_cohorts([{"id": 1, "name": "Test"}])

Source code in src/mixpanel_headless/workspace.py

def update_blueprint_cohorts(self, cohorts: list[dict[str, Any]]) -> None:
    """Update cohorts for blueprint configuration.

    Args:
        cohorts: List of cohort configuration dicts.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid cohort configuration (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.update_blueprint_cohorts([{"id": 1, "name": "Test"}])
        ```
    """
    client = self._require_api_client()
    client.update_blueprint_cohorts(cohorts)

finalize_blueprint ¶

finalize_blueprint(params: BlueprintFinishParams) -> Dashboard

Finalize a blueprint dashboard with cards.

PARAMETER	DESCRIPTION
`params`	Blueprint finalization parameters. TYPE: `BlueprintFinishParams`

RETURNS	DESCRIPTION
`Dashboard`	The finalized `Dashboard`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid parameters (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dashboard = ws.finalize_blueprint(
    BlueprintFinishParams(
        dashboard_id=1,
        cards=[BlueprintCard(card_type="report", bookmark_id=42)],
    )
)

Source code in src/mixpanel_headless/workspace.py

def finalize_blueprint(self, params: BlueprintFinishParams) -> Dashboard:
    """Finalize a blueprint dashboard with cards.

    Args:
        params: Blueprint finalization parameters.

    Returns:
        The finalized ``Dashboard``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid parameters (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dashboard = ws.finalize_blueprint(
            BlueprintFinishParams(
                dashboard_id=1,
                cards=[BlueprintCard(card_type="report", bookmark_id=42)],
            )
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True, by_alias=True)
    raw = client.finalize_blueprint(body)
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for finalize_blueprint",
        )
    return validate_response_model(Dashboard, raw, endpoint="finalize_blueprint")

create_rca_dashboard ¶

create_rca_dashboard(params: CreateRcaDashboardParams) -> Dashboard

Create an RCA (Root Cause Analysis) dashboard.

PARAMETER	DESCRIPTION
`params`	RCA dashboard parameters. TYPE: `CreateRcaDashboardParams`

RETURNS	DESCRIPTION
`Dashboard`	The newly created `Dashboard`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid parameters (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dashboard = ws.create_rca_dashboard(
    CreateRcaDashboardParams(
        rca_source_id=42,
        rca_source_data=RcaSourceData(source_type="anomaly"),
    )
)

Source code in src/mixpanel_headless/workspace.py

def create_rca_dashboard(self, params: CreateRcaDashboardParams) -> Dashboard:
    """Create an RCA (Root Cause Analysis) dashboard.

    Args:
        params: RCA dashboard parameters.

    Returns:
        The newly created ``Dashboard``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid parameters (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dashboard = ws.create_rca_dashboard(
            CreateRcaDashboardParams(
                rca_source_id=42,
                rca_source_data=RcaSourceData(source_type="anomaly"),
            )
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True, by_alias=True)
    raw = client.create_rca_dashboard(body)
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for create_rca_dashboard",
        )
    return validate_response_model(Dashboard, raw, endpoint="create_rca_dashboard")

get_bookmark_dashboard_ids ¶

get_bookmark_dashboard_ids(bookmark_id: int) -> list[int]

Get dashboard IDs containing a bookmark/report.

PARAMETER	DESCRIPTION
`bookmark_id`	Bookmark identifier. TYPE: `int`

RETURNS	DESCRIPTION
`list[int]`	List of dashboard IDs.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Bookmark not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dash_ids = ws.get_bookmark_dashboard_ids(42)

Source code in src/mixpanel_headless/workspace.py

def get_bookmark_dashboard_ids(self, bookmark_id: int) -> list[int]:
    """Get dashboard IDs containing a bookmark/report.

    Args:
        bookmark_id: Bookmark identifier.

    Returns:
        List of dashboard IDs.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Bookmark not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dash_ids = ws.get_bookmark_dashboard_ids(42)
        ```
    """
    client = self._require_api_client()
    return client.get_bookmark_dashboard_ids(bookmark_id)

get_dashboard_erf ¶

get_dashboard_erf(dashboard_id: int) -> dict[str, Any]

Get ERF data for a dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`

RETURNS	DESCRIPTION
`dict[str, Any]`	Dict with ERF metrics data.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
erf = ws.get_dashboard_erf(12345)

Source code in src/mixpanel_headless/workspace.py

def get_dashboard_erf(self, dashboard_id: int) -> dict[str, Any]:
    """Get ERF data for a dashboard.

    Args:
        dashboard_id: Dashboard identifier.

    Returns:
        Dict with ERF metrics data.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        erf = ws.get_dashboard_erf(12345)
        ```
    """
    client = self._require_api_client()
    return client.get_dashboard_erf(dashboard_id)

update_report_link ¶

update_report_link(
    dashboard_id: int, report_link_id: int, params: UpdateReportLinkParams
) -> None

Update a report link on a dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`
`report_link_id`	Report link identifier. TYPE: `int`
`params`	Update parameters. TYPE: `UpdateReportLinkParams`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard or link not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.update_report_link(
    12345, 42, UpdateReportLinkParams(link_type="embedded")
)

Source code in src/mixpanel_headless/workspace.py

def update_report_link(
    self,
    dashboard_id: int,
    report_link_id: int,
    params: UpdateReportLinkParams,
) -> None:
    """Update a report link on a dashboard.

    Args:
        dashboard_id: Dashboard identifier.
        report_link_id: Report link identifier.
        params: Update parameters.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard or link not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.update_report_link(
            12345, 42, UpdateReportLinkParams(link_type="embedded")
        )
        ```
    """
    client = self._require_api_client()
    client.update_report_link(
        dashboard_id,
        report_link_id,
        params.model_dump(by_alias=True, exclude_none=True),
    )

update_text_card ¶

update_text_card(
    dashboard_id: int, text_card_id: int, params: UpdateTextCardParams
) -> None

Update a text card on a dashboard.

PARAMETER	DESCRIPTION
`dashboard_id`	Dashboard identifier. TYPE: `int`
`text_card_id`	Text card identifier. TYPE: `int`
`params`	Update parameters. TYPE: `UpdateTextCardParams`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Dashboard or text card not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.update_text_card(
    12345, 99, UpdateTextCardParams(markdown="# Hello")
)

Source code in src/mixpanel_headless/workspace.py

def update_text_card(
    self,
    dashboard_id: int,
    text_card_id: int,
    params: UpdateTextCardParams,
) -> None:
    """Update a text card on a dashboard.

    Args:
        dashboard_id: Dashboard identifier.
        text_card_id: Text card identifier.
        params: Update parameters.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Dashboard or text card not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.update_text_card(
            12345, 99, UpdateTextCardParams(markdown="# Hello")
        )
        ```
    """
    client = self._require_api_client()
    client.update_text_card(
        dashboard_id,
        text_card_id,
        params.model_dump(exclude_none=True),
    )

list_bookmarks_v2 ¶

list_bookmarks_v2(
    *, bookmark_type: BookmarkType | None = None, ids: list[int] | None = None
) -> list[Bookmark]

List bookmarks/reports via the App API v2 endpoint.

PARAMETER	DESCRIPTION
`bookmark_type`	Optional report type filter (e.g., `"funnels"`). TYPE: `BookmarkType \| None` DEFAULT: `None`
`ids`	Optional list of bookmark IDs to filter by. TYPE: `list[int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[Bookmark]`	List of `Bookmark` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
reports = ws.list_bookmarks_v2(bookmark_type="funnels")
for r in reports:
    print(f"{r.name} ({r.bookmark_type})")

Source code in src/mixpanel_headless/workspace.py

def list_bookmarks_v2(
    self,
    *,
    bookmark_type: BookmarkType | None = None,
    ids: list[int] | None = None,
) -> list[Bookmark]:
    """List bookmarks/reports via the App API v2 endpoint.

    Args:
        bookmark_type: Optional report type filter (e.g., ``"funnels"``).
        ids: Optional list of bookmark IDs to filter by.

    Returns:
        List of ``Bookmark`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        reports = ws.list_bookmarks_v2(bookmark_type="funnels")
        for r in reports:
            print(f"{r.name} ({r.bookmark_type})")
        ```
    """
    client = self._require_api_client()
    raw = client.list_bookmarks_v2(bookmark_type=bookmark_type, ids=ids)
    return validate_response_models(Bookmark, raw, endpoint="list_bookmarks_v2")

create_bookmark ¶

create_bookmark(params: CreateBookmarkParams) -> Bookmark

Create a new bookmark (saved report).

PARAMETER	DESCRIPTION
`params`	Bookmark creation parameters. `dashboard_id` is required by the Mixpanel v2 API. TYPE: `CreateBookmarkParams`

RETURNS	DESCRIPTION
`Bookmark`	The newly created `Bookmark`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`MixpanelHeadlessError`	If `params.dashboard_id` is `None` (required by the Mixpanel v2 API).
`BookmarkValidationError`	If `params.params` fails client-side schema validation (mirrors Mixpanel's canonical Pydantic schema; raised before the API call).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid parameters (400, 422).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dashboard = ws.create_dashboard(
    CreateDashboardParams(title="My Dashboard")
)
report = ws.create_bookmark(CreateBookmarkParams(
    name="Signup Funnel",
    bookmark_type="funnels",
    params={"events": [{"event": "Signup"}]},
    dashboard_id=dashboard.id,
))

Source code in src/mixpanel_headless/workspace.py

def create_bookmark(self, params: CreateBookmarkParams) -> Bookmark:
    """Create a new bookmark (saved report).

    Args:
        params: Bookmark creation parameters.  ``dashboard_id``
            is required by the Mixpanel v2 API.

    Returns:
        The newly created ``Bookmark``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        MixpanelHeadlessError: If ``params.dashboard_id`` is ``None``
            (required by the Mixpanel v2 API).
        BookmarkValidationError: If ``params.params`` fails
            client-side schema validation (mirrors Mixpanel's
            canonical Pydantic schema; raised before the API call).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid parameters (400, 422).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dashboard = ws.create_dashboard(
            CreateDashboardParams(title="My Dashboard")
        )
        report = ws.create_bookmark(CreateBookmarkParams(
            name="Signup Funnel",
            bookmark_type="funnels",
            params={"events": [{"event": "Signup"}]},
            dashboard_id=dashboard.id,
        ))
        ```
    """
    if params.dashboard_id is None:
        raise MixpanelHeadlessError(
            "dashboard_id is required when creating a bookmark. "
            "The Mixpanel v2 API requires every bookmark to be "
            "associated with a dashboard. Create a dashboard first "
            "with create_dashboard(), then pass its ID here.",
        )

    # Full Pydantic-schema validation against the canonical mirror
    # of Mixpanel's bookmark schema — catches malformed shapes
    # client-side before they're persisted with garbage that only
    # surfaces later at chart-render time.
    schema_errors = self._validate_bookmark_params_schema(
        params.params, params.bookmark_type
    )
    if any(e.severity == "error" for e in schema_errors):
        raise BookmarkValidationError(schema_errors)
    for w in (e for e in schema_errors if e.severity == "warning"):
        logger.warning(
            "create_bookmark validation warning: %s [%s]",
            w.message,
            w.code,
        )

    client = self._require_api_client()
    raw = client.create_bookmark(
        params.model_dump(by_alias=True, exclude_none=True)
    )
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for create_bookmark",
        )
    bookmark = validate_response_model(Bookmark, raw, endpoint="create_bookmark")

    # The v2 create endpoint associates the bookmark with the
    # dashboard in the database, but does NOT add it to the
    # dashboard's visual layout — that requires a separate
    # PATCH call.
    self.add_report_to_dashboard(params.dashboard_id, bookmark.id)

    return bookmark

get_bookmark ¶

get_bookmark(bookmark_id: int) -> Bookmark

Get a single bookmark by ID.

PARAMETER	DESCRIPTION
`bookmark_id`	Bookmark identifier. TYPE: `int`

RETURNS	DESCRIPTION
`Bookmark`	The `Bookmark` object.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Bookmark not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
report = ws.get_bookmark(12345)

Source code in src/mixpanel_headless/workspace.py

def get_bookmark(self, bookmark_id: int) -> Bookmark:
    """Get a single bookmark by ID.

    Args:
        bookmark_id: Bookmark identifier.

    Returns:
        The ``Bookmark`` object.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Bookmark not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        report = ws.get_bookmark(12345)
        ```
    """
    client = self._require_api_client()
    raw = client.get_bookmark(bookmark_id)
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for get_bookmark",
        )
    return validate_response_model(Bookmark, raw, endpoint="get_bookmark")

update_bookmark ¶

update_bookmark(bookmark_id: int, params: UpdateBookmarkParams) -> Bookmark

Update an existing bookmark.

PARAMETER	DESCRIPTION
`bookmark_id`	Bookmark identifier. TYPE: `int`
`params`	Fields to update. TYPE: `UpdateBookmarkParams`

RETURNS	DESCRIPTION
`Bookmark`	The updated `Bookmark`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`BookmarkValidationError`	If `params.params` (when supplied) fails partial-mode client-side schema validation (mirrors Mixpanel's canonical schema for the keys that ARE present; raised before the API call).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Bookmark not found or invalid params (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
updated = ws.update_bookmark(
    12345, UpdateBookmarkParams(name="Renamed")
)

Source code in src/mixpanel_headless/workspace.py

def update_bookmark(
    self, bookmark_id: int, params: UpdateBookmarkParams
) -> Bookmark:
    """Update an existing bookmark.

    Args:
        bookmark_id: Bookmark identifier.
        params: Fields to update.

    Returns:
        The updated ``Bookmark``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        BookmarkValidationError: If ``params.params`` (when supplied)
            fails partial-mode client-side schema validation
            (mirrors Mixpanel's canonical schema for the keys that
            ARE present; raised before the API call).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Bookmark not found or invalid params (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        updated = ws.update_bookmark(
            12345, UpdateBookmarkParams(name="Renamed")
        )
        ```
    """
    # Partial-aware Pydantic validation: each present top-level key
    # in ``params.params`` is checked against its canonical sub-model.
    # Missing top-level keys are intentional (partial updates) and
    # not flagged. Catches the same malformations the create-path
    # catches on the keys that ARE present (chartType typos,
    # missing colSortAttrs, extra segmentation field, etc.).
    if params.params is not None:
        schema_errors = self._validate_bookmark_params_schema(
            params.params, bookmark_type=None, partial=True
        )
        if any(e.severity == "error" for e in schema_errors):
            raise BookmarkValidationError(schema_errors)
        for w in (e for e in schema_errors if e.severity == "warning"):
            logger.warning(
                "update_bookmark validation warning: %s [%s]",
                w.message,
                w.code,
            )

    client = self._require_api_client()
    raw = client.update_bookmark(bookmark_id, params.model_dump(exclude_none=True))
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for update_bookmark",
        )
    return validate_response_model(Bookmark, raw, endpoint="update_bookmark")

delete_bookmark ¶

delete_bookmark(bookmark_id: int) -> None

Delete a bookmark.

PARAMETER	DESCRIPTION
`bookmark_id`	Bookmark identifier. TYPE: `int`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Bookmark not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_bookmark(12345)

Source code in src/mixpanel_headless/workspace.py

def delete_bookmark(self, bookmark_id: int) -> None:
    """Delete a bookmark.

    Args:
        bookmark_id: Bookmark identifier.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Bookmark not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_bookmark(12345)
        ```
    """
    client = self._require_api_client()
    client.delete_bookmark(bookmark_id)

bulk_delete_bookmarks ¶

bulk_delete_bookmarks(ids: list[int]) -> None

Delete multiple bookmarks.

PARAMETER	DESCRIPTION
`ids`	List of bookmark IDs to delete. TYPE: `list[int]`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	One or more IDs not found (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.bulk_delete_bookmarks([1, 2, 3])

Source code in src/mixpanel_headless/workspace.py

def bulk_delete_bookmarks(self, ids: list[int]) -> None:
    """Delete multiple bookmarks.

    Args:
        ids: List of bookmark IDs to delete.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: One or more IDs not found (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.bulk_delete_bookmarks([1, 2, 3])
        ```
    """
    client = self._require_api_client()
    client.bulk_delete_bookmarks(ids)

bulk_update_bookmarks ¶

bulk_update_bookmarks(entries: list[BulkUpdateBookmarkEntry]) -> None

Update multiple bookmarks.

PARAMETER	DESCRIPTION
`entries`	List of bookmark update entries. TYPE: `list[BulkUpdateBookmarkEntry]`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid entries or IDs not found (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.bulk_update_bookmarks([
    BulkUpdateBookmarkEntry(id=1, name="Renamed"),
])

Source code in src/mixpanel_headless/workspace.py

def bulk_update_bookmarks(self, entries: list[BulkUpdateBookmarkEntry]) -> None:
    """Update multiple bookmarks.

    Args:
        entries: List of bookmark update entries.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid entries or IDs not found (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.bulk_update_bookmarks([
            BulkUpdateBookmarkEntry(id=1, name="Renamed"),
        ])
        ```
    """
    client = self._require_api_client()
    client.bulk_update_bookmarks([e.model_dump(exclude_none=True) for e in entries])

bookmark_linked_dashboard_ids ¶

bookmark_linked_dashboard_ids(bookmark_id: int) -> list[int]

Get dashboard IDs linked to a bookmark.

PARAMETER	DESCRIPTION
`bookmark_id`	Bookmark identifier. TYPE: `int`

RETURNS	DESCRIPTION
`list[int]`	List of dashboard IDs.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Bookmark not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dash_ids = ws.bookmark_linked_dashboard_ids(42)

Source code in src/mixpanel_headless/workspace.py

def bookmark_linked_dashboard_ids(self, bookmark_id: int) -> list[int]:
    """Get dashboard IDs linked to a bookmark.

    Args:
        bookmark_id: Bookmark identifier.

    Returns:
        List of dashboard IDs.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Bookmark not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dash_ids = ws.bookmark_linked_dashboard_ids(42)
        ```
    """
    client = self._require_api_client()
    return client.bookmark_linked_dashboard_ids(bookmark_id)

get_bookmark_history ¶

get_bookmark_history(
    bookmark_id: int, *, cursor: str | None = None, page_size: int | None = None
) -> BookmarkHistoryResponse

Get the change history for a bookmark.

PARAMETER	DESCRIPTION
`bookmark_id`	Bookmark identifier. TYPE: `int`
`cursor`	Opaque pagination cursor. TYPE: `str \| None` DEFAULT: `None`
`page_size`	Maximum entries per page. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`BookmarkHistoryResponse`	`BookmarkHistoryResponse` with results and pagination.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Bookmark not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
history = ws.get_bookmark_history(12345, page_size=10)

Source code in src/mixpanel_headless/workspace.py

def get_bookmark_history(
    self,
    bookmark_id: int,
    *,
    cursor: str | None = None,
    page_size: int | None = None,
) -> BookmarkHistoryResponse:
    """Get the change history for a bookmark.

    Args:
        bookmark_id: Bookmark identifier.
        cursor: Opaque pagination cursor.
        page_size: Maximum entries per page.

    Returns:
        ``BookmarkHistoryResponse`` with results and pagination.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Bookmark not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        history = ws.get_bookmark_history(12345, page_size=10)
        ```
    """
    client = self._require_api_client()
    raw = client.get_bookmark_history(
        bookmark_id, cursor=cursor, page_size=page_size
    )
    return validate_response_model(
        BookmarkHistoryResponse, raw, endpoint="get_bookmark_history"
    )

list_cohorts_full ¶

list_cohorts_full(
    *, data_group_id: str | None = None, ids: list[int] | None = None
) -> list[Cohort]

List cohorts via the App API (full detail).

Unlike cohorts() which uses the discovery endpoint, this method uses the App API and returns full Cohort objects with all metadata.

PARAMETER	DESCRIPTION
`data_group_id`	Optional data group filter. TYPE: `str \| None` DEFAULT: `None`
`ids`	Optional list of cohort IDs to filter by. TYPE: `list[int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[Cohort]`	List of `Cohort` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
cohorts = ws.list_cohorts_full()
for c in cohorts:
    print(f"{c.name} ({c.count} users)")

Source code in src/mixpanel_headless/workspace.py

def list_cohorts_full(
    self,
    *,
    data_group_id: str | None = None,
    ids: list[int] | None = None,
) -> list[Cohort]:
    """List cohorts via the App API (full detail).

    Unlike ``cohorts()`` which uses the discovery endpoint, this method
    uses the App API and returns full ``Cohort`` objects with all metadata.

    Args:
        data_group_id: Optional data group filter.
        ids: Optional list of cohort IDs to filter by.

    Returns:
        List of ``Cohort`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        cohorts = ws.list_cohorts_full()
        for c in cohorts:
            print(f"{c.name} ({c.count} users)")
        ```
    """
    client = self._require_api_client()
    raw = client.list_cohorts_app(data_group_id=data_group_id, ids=ids)
    return validate_response_models(Cohort, raw, endpoint="list_cohorts_full")

get_cohort ¶

get_cohort(cohort_id: int) -> Cohort

Get a single cohort by ID via the App API.

PARAMETER	DESCRIPTION
`cohort_id`	Cohort identifier. TYPE: `int`

RETURNS	DESCRIPTION
`Cohort`	The `Cohort` object.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Cohort not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
cohort = ws.get_cohort(12345)

Source code in src/mixpanel_headless/workspace.py

def get_cohort(self, cohort_id: int) -> Cohort:
    """Get a single cohort by ID via the App API.

    Args:
        cohort_id: Cohort identifier.

    Returns:
        The ``Cohort`` object.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Cohort not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        cohort = ws.get_cohort(12345)
        ```
    """
    client = self._require_api_client()
    raw = client.get_cohort(cohort_id)
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for get_cohort",
        )
    return validate_response_model(Cohort, raw, endpoint="get_cohort")

create_cohort ¶

create_cohort(params: CreateCohortParams) -> Cohort

Create a new cohort.

PARAMETER	DESCRIPTION
`params`	Cohort creation parameters. TYPE: `CreateCohortParams`

RETURNS	DESCRIPTION
`Cohort`	The newly created `Cohort`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid parameters (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
cohort = ws.create_cohort(
    CreateCohortParams(name="Power Users")
)

Source code in src/mixpanel_headless/workspace.py

def create_cohort(self, params: CreateCohortParams) -> Cohort:
    """Create a new cohort.

    Args:
        params: Cohort creation parameters.

    Returns:
        The newly created ``Cohort``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid parameters (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        cohort = ws.create_cohort(
            CreateCohortParams(name="Power Users")
        )
        ```
    """
    client = self._require_api_client()
    raw = client.create_cohort(params.model_dump(exclude_none=True))
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for create_cohort",
        )
    return validate_response_model(Cohort, raw, endpoint="create_cohort")

update_cohort ¶

update_cohort(cohort_id: int, params: UpdateCohortParams) -> Cohort

Update an existing cohort.

PARAMETER	DESCRIPTION
`cohort_id`	Cohort identifier. TYPE: `int`
`params`	Fields to update. TYPE: `UpdateCohortParams`

RETURNS	DESCRIPTION
`Cohort`	The updated `Cohort`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Cohort not found or invalid params (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
updated = ws.update_cohort(
    12345, UpdateCohortParams(name="Renamed")
)

Source code in src/mixpanel_headless/workspace.py

def update_cohort(self, cohort_id: int, params: UpdateCohortParams) -> Cohort:
    """Update an existing cohort.

    Args:
        cohort_id: Cohort identifier.
        params: Fields to update.

    Returns:
        The updated ``Cohort``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Cohort not found or invalid params (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        updated = ws.update_cohort(
            12345, UpdateCohortParams(name="Renamed")
        )
        ```
    """
    client = self._require_api_client()
    raw = client.update_cohort(cohort_id, params.model_dump(exclude_none=True))
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for update_cohort",
        )
    return validate_response_model(Cohort, raw, endpoint="update_cohort")

delete_cohort ¶

delete_cohort(cohort_id: int) -> None

Delete a cohort.

PARAMETER	DESCRIPTION
`cohort_id`	Cohort identifier. TYPE: `int`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Cohort not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_cohort(12345)

Source code in src/mixpanel_headless/workspace.py

def delete_cohort(self, cohort_id: int) -> None:
    """Delete a cohort.

    Args:
        cohort_id: Cohort identifier.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Cohort not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_cohort(12345)
        ```
    """
    client = self._require_api_client()
    client.delete_cohort(cohort_id)

bulk_delete_cohorts ¶

bulk_delete_cohorts(ids: list[int]) -> None

Delete multiple cohorts.

PARAMETER	DESCRIPTION
`ids`	List of cohort IDs to delete. TYPE: `list[int]`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	One or more IDs not found (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.bulk_delete_cohorts([1, 2, 3])

Source code in src/mixpanel_headless/workspace.py

def bulk_delete_cohorts(self, ids: list[int]) -> None:
    """Delete multiple cohorts.

    Args:
        ids: List of cohort IDs to delete.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: One or more IDs not found (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.bulk_delete_cohorts([1, 2, 3])
        ```
    """
    client = self._require_api_client()
    client.bulk_delete_cohorts(ids)

bulk_update_cohorts ¶

bulk_update_cohorts(entries: list[BulkUpdateCohortEntry]) -> None

Update multiple cohorts.

PARAMETER	DESCRIPTION
`entries`	List of cohort update entries. TYPE: `list[BulkUpdateCohortEntry]`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid entries or IDs not found (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.bulk_update_cohorts([
    BulkUpdateCohortEntry(id=1, name="Renamed"),
])

Source code in src/mixpanel_headless/workspace.py

def bulk_update_cohorts(self, entries: list[BulkUpdateCohortEntry]) -> None:
    """Update multiple cohorts.

    Args:
        entries: List of cohort update entries.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid entries or IDs not found (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.bulk_update_cohorts([
            BulkUpdateCohortEntry(id=1, name="Renamed"),
        ])
        ```
    """
    client = self._require_api_client()
    client.bulk_update_cohorts([e.model_dump(exclude_none=True) for e in entries])

list_feature_flags ¶

list_feature_flags(*, include_archived: bool = False) -> list[FeatureFlag]

List feature flags for the current project/workspace.

PARAMETER	DESCRIPTION
`include_archived`	When True, include archived flags. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`list[FeatureFlag]`	List of `FeatureFlag` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
flags = ws.list_feature_flags()
for f in flags:
    print(f"{f.name} ({f.key})")

Source code in src/mixpanel_headless/workspace.py

def list_feature_flags(
    self, *, include_archived: bool = False
) -> list[FeatureFlag]:
    """List feature flags for the current project/workspace.

    Args:
        include_archived: When True, include archived flags.

    Returns:
        List of ``FeatureFlag`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        flags = ws.list_feature_flags()
        for f in flags:
            print(f"{f.name} ({f.key})")
        ```
    """
    client = self._require_api_client()
    raw = client.list_feature_flags(include_archived=include_archived)
    return validate_response_models(FeatureFlag, raw, endpoint="list_feature_flags")

create_feature_flag ¶

create_feature_flag(params: CreateFeatureFlagParams) -> FeatureFlag

Create a new feature flag.

PARAMETER	DESCRIPTION
`params`	Flag creation parameters. TYPE: `CreateFeatureFlagParams`

RETURNS	DESCRIPTION
`FeatureFlag`	The newly created `FeatureFlag`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Duplicate key or invalid parameters (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
flag = ws.create_feature_flag(
    CreateFeatureFlagParams(name="Dark Mode", key="dark_mode")
)

Source code in src/mixpanel_headless/workspace.py

def create_feature_flag(self, params: CreateFeatureFlagParams) -> FeatureFlag:
    """Create a new feature flag.

    Args:
        params: Flag creation parameters.

    Returns:
        The newly created ``FeatureFlag``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Duplicate key or invalid parameters (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        flag = ws.create_feature_flag(
            CreateFeatureFlagParams(name="Dark Mode", key="dark_mode")
        )
        ```
    """
    client = self._require_api_client()
    raw = client.create_feature_flag(params.model_dump(exclude_none=True))
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for create_feature_flag",
        )
    return validate_response_model(FeatureFlag, raw, endpoint="create_feature_flag")

get_feature_flag ¶

get_feature_flag(flag_id: str) -> FeatureFlag

Get a single feature flag by ID.

PARAMETER	DESCRIPTION
`flag_id`	Feature flag UUID. TYPE: `str`

RETURNS	DESCRIPTION
`FeatureFlag`	The `FeatureFlag` object.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Flag not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
flag = ws.get_feature_flag("abc-123-uuid")

Source code in src/mixpanel_headless/workspace.py

def get_feature_flag(self, flag_id: str) -> FeatureFlag:
    """Get a single feature flag by ID.

    Args:
        flag_id: Feature flag UUID.

    Returns:
        The ``FeatureFlag`` object.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Flag not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        flag = ws.get_feature_flag("abc-123-uuid")
        ```
    """
    client = self._require_api_client()
    raw = client.get_feature_flag(flag_id)
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for get_feature_flag",
        )
    return validate_response_model(FeatureFlag, raw, endpoint="get_feature_flag")

update_feature_flag ¶

update_feature_flag(
    flag_id: str, params: UpdateFeatureFlagParams
) -> FeatureFlag

Update a feature flag (full replacement, PUT semantics).

PARAMETER	DESCRIPTION
`flag_id`	Feature flag UUID. TYPE: `str`
`params`	Complete flag configuration. TYPE: `UpdateFeatureFlagParams`

RETURNS	DESCRIPTION
`FeatureFlag`	The updated `FeatureFlag`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Flag not found or invalid params (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
updated = ws.update_feature_flag(
    "abc-123", UpdateFeatureFlagParams(
        name="X", key="x",
        status=FeatureFlagStatus.ENABLED,
        ruleset={"variants": []},
    )
)

Source code in src/mixpanel_headless/workspace.py

def update_feature_flag(
    self, flag_id: str, params: UpdateFeatureFlagParams
) -> FeatureFlag:
    """Update a feature flag (full replacement, PUT semantics).

    Args:
        flag_id: Feature flag UUID.
        params: Complete flag configuration.

    Returns:
        The updated ``FeatureFlag``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Flag not found or invalid params (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        updated = ws.update_feature_flag(
            "abc-123", UpdateFeatureFlagParams(
                name="X", key="x",
                status=FeatureFlagStatus.ENABLED,
                ruleset={"variants": []},
            )
        )
        ```
    """
    client = self._require_api_client()
    raw = client.update_feature_flag(flag_id, params.model_dump(exclude_none=True))
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for update_feature_flag",
        )
    return validate_response_model(FeatureFlag, raw, endpoint="update_feature_flag")

delete_feature_flag ¶

delete_feature_flag(flag_id: str) -> None

Delete a feature flag.

PARAMETER	DESCRIPTION
`flag_id`	Feature flag UUID. TYPE: `str`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Flag not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_feature_flag("abc-123-uuid")

Source code in src/mixpanel_headless/workspace.py

def delete_feature_flag(self, flag_id: str) -> None:
    """Delete a feature flag.

    Args:
        flag_id: Feature flag UUID.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Flag not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_feature_flag("abc-123-uuid")
        ```
    """
    client = self._require_api_client()
    client.delete_feature_flag(flag_id)

archive_feature_flag ¶

archive_feature_flag(flag_id: str) -> None

Archive a feature flag (soft-delete).

PARAMETER	DESCRIPTION
`flag_id`	Feature flag UUID. TYPE: `str`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Flag not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.archive_feature_flag("abc-123-uuid")

Source code in src/mixpanel_headless/workspace.py

def archive_feature_flag(self, flag_id: str) -> None:
    """Archive a feature flag (soft-delete).

    Args:
        flag_id: Feature flag UUID.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Flag not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.archive_feature_flag("abc-123-uuid")
        ```
    """
    client = self._require_api_client()
    client.archive_feature_flag(flag_id)

restore_feature_flag ¶

restore_feature_flag(flag_id: str) -> FeatureFlag

Restore an archived feature flag.

PARAMETER	DESCRIPTION
`flag_id`	Feature flag UUID. TYPE: `str`

RETURNS	DESCRIPTION
`FeatureFlag`	The restored `FeatureFlag`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Flag not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
restored = ws.restore_feature_flag("abc-123-uuid")

Source code in src/mixpanel_headless/workspace.py

def restore_feature_flag(self, flag_id: str) -> FeatureFlag:
    """Restore an archived feature flag.

    Args:
        flag_id: Feature flag UUID.

    Returns:
        The restored ``FeatureFlag``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Flag not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        restored = ws.restore_feature_flag("abc-123-uuid")
        ```
    """
    client = self._require_api_client()
    raw = client.restore_feature_flag(flag_id)
    return validate_response_model(
        FeatureFlag, raw, endpoint="restore_feature_flag"
    )

duplicate_feature_flag ¶

duplicate_feature_flag(flag_id: str) -> FeatureFlag

Duplicate a feature flag.

PARAMETER	DESCRIPTION
`flag_id`	Feature flag UUID. TYPE: `str`

RETURNS	DESCRIPTION
`FeatureFlag`	The newly created duplicate `FeatureFlag`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Flag not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dup = ws.duplicate_feature_flag("abc-123-uuid")

Source code in src/mixpanel_headless/workspace.py

def duplicate_feature_flag(self, flag_id: str) -> FeatureFlag:
    """Duplicate a feature flag.

    Args:
        flag_id: Feature flag UUID.

    Returns:
        The newly created duplicate ``FeatureFlag``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Flag not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dup = ws.duplicate_feature_flag("abc-123-uuid")
        ```
    """
    client = self._require_api_client()
    raw = client.duplicate_feature_flag(flag_id)
    return validate_response_model(
        FeatureFlag, raw, endpoint="duplicate_feature_flag"
    )

set_flag_test_users ¶

set_flag_test_users(flag_id: str, params: SetTestUsersParams) -> None

Set test user variant overrides for a feature flag.

PARAMETER	DESCRIPTION
`flag_id`	Feature flag UUID. TYPE: `str`
`params`	Test user mapping. TYPE: `SetTestUsersParams`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Flag not found (404) or invalid payload (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.set_flag_test_users(
    "abc-123",
    SetTestUsersParams(users={"on": "user-1"}),
)

Source code in src/mixpanel_headless/workspace.py

def set_flag_test_users(self, flag_id: str, params: SetTestUsersParams) -> None:
    """Set test user variant overrides for a feature flag.

    Args:
        flag_id: Feature flag UUID.
        params: Test user mapping.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Flag not found (404) or invalid payload (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.set_flag_test_users(
            "abc-123",
            SetTestUsersParams(users={"on": "user-1"}),
        )
        ```
    """
    client = self._require_api_client()
    client.set_flag_test_users(flag_id, params.model_dump())

get_flag_history ¶

get_flag_history(
    flag_id: str, *, page: str | None = None, page_size: int | None = None
) -> FlagHistoryResponse

Get paginated change history for a feature flag.

PARAMETER	DESCRIPTION
`flag_id`	Feature flag UUID. TYPE: `str`
`page`	Pagination cursor. TYPE: `str \| None` DEFAULT: `None`
`page_size`	Results per page. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`FlagHistoryResponse`	`FlagHistoryResponse` with events and count.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Flag not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
history = ws.get_flag_history("abc-123", page_size=50)

Source code in src/mixpanel_headless/workspace.py

def get_flag_history(
    self,
    flag_id: str,
    *,
    page: str | None = None,
    page_size: int | None = None,
) -> FlagHistoryResponse:
    """Get paginated change history for a feature flag.

    Args:
        flag_id: Feature flag UUID.
        page: Pagination cursor.
        page_size: Results per page.

    Returns:
        ``FlagHistoryResponse`` with events and count.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Flag not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        history = ws.get_flag_history("abc-123", page_size=50)
        ```
    """
    client = self._require_api_client()
    query_params: dict[str, str] = {}
    if page is not None:
        query_params["page"] = page
    if page_size is not None:
        query_params["page_size"] = str(page_size)
    raw = client.get_flag_history(
        flag_id, params=query_params if query_params else None
    )
    return validate_response_model(
        FlagHistoryResponse, raw, endpoint="get_flag_history"
    )

get_flag_limits ¶

get_flag_limits() -> FlagLimitsResponse

Get account-level feature flag limits and usage.

RETURNS	DESCRIPTION
`FlagLimitsResponse`	`FlagLimitsResponse` with limit, usage, trial, and contract status.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
limits = ws.get_flag_limits()
print(f"{limits.current_usage}/{limits.limit}")

Source code in src/mixpanel_headless/workspace.py

def get_flag_limits(self) -> FlagLimitsResponse:
    """Get account-level feature flag limits and usage.

    Returns:
        ``FlagLimitsResponse`` with limit, usage, trial, and contract status.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        limits = ws.get_flag_limits()
        print(f"{limits.current_usage}/{limits.limit}")
        ```
    """
    client = self._require_api_client()
    raw = client.get_flag_limits()
    return validate_response_model(
        FlagLimitsResponse, raw, endpoint="get_flag_limits"
    )

list_experiments ¶

list_experiments(*, include_archived: bool = False) -> list[Experiment]

List experiments for the current project.

PARAMETER	DESCRIPTION
`include_archived`	When True, include archived experiments. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`list[Experiment]`	List of `Experiment` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
experiments = ws.list_experiments()
for e in experiments:
    print(f"{e.name} (status={e.status})")

Source code in src/mixpanel_headless/workspace.py

def list_experiments(self, *, include_archived: bool = False) -> list[Experiment]:
    """List experiments for the current project.

    Args:
        include_archived: When True, include archived experiments.

    Returns:
        List of ``Experiment`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        experiments = ws.list_experiments()
        for e in experiments:
            print(f"{e.name} (status={e.status})")
        ```
    """
    client = self._require_api_client()
    raw = client.list_experiments(include_archived=include_archived)
    return validate_response_models(Experiment, raw, endpoint="list_experiments")

create_experiment ¶

create_experiment(params: CreateExperimentParams) -> Experiment

Create a new experiment in Draft status.

PARAMETER	DESCRIPTION
`params`	Experiment creation parameters. TYPE: `CreateExperimentParams`

RETURNS	DESCRIPTION
`Experiment`	The newly created `Experiment`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid parameters (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
exp = ws.create_experiment(
    CreateExperimentParams(name="Checkout Flow Test")
)

Source code in src/mixpanel_headless/workspace.py

def create_experiment(self, params: CreateExperimentParams) -> Experiment:
    """Create a new experiment in Draft status.

    Args:
        params: Experiment creation parameters.

    Returns:
        The newly created ``Experiment``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid parameters (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        exp = ws.create_experiment(
            CreateExperimentParams(name="Checkout Flow Test")
        )
        ```
    """
    client = self._require_api_client()
    raw = client.create_experiment(params.model_dump(exclude_none=True))
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for create_experiment",
        )
    return validate_response_model(Experiment, raw, endpoint="create_experiment")

get_experiment ¶

get_experiment(experiment_id: str) -> Experiment

Get a single experiment by ID.

PARAMETER	DESCRIPTION
`experiment_id`	Experiment UUID. TYPE: `str`

RETURNS	DESCRIPTION
`Experiment`	The `Experiment` object.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Experiment not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
exp = ws.get_experiment("xyz-456-uuid")

Source code in src/mixpanel_headless/workspace.py

def get_experiment(self, experiment_id: str) -> Experiment:
    """Get a single experiment by ID.

    Args:
        experiment_id: Experiment UUID.

    Returns:
        The ``Experiment`` object.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Experiment not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        exp = ws.get_experiment("xyz-456-uuid")
        ```
    """
    client = self._require_api_client()
    raw = client.get_experiment(experiment_id)
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for get_experiment",
        )
    return validate_response_model(Experiment, raw, endpoint="get_experiment")

update_experiment ¶

update_experiment(
    experiment_id: str, params: UpdateExperimentParams
) -> Experiment

Update an experiment (PATCH semantics).

PARAMETER	DESCRIPTION
`experiment_id`	Experiment UUID. TYPE: `str`
`params`	Fields to update. TYPE: `UpdateExperimentParams`

RETURNS	DESCRIPTION
`Experiment`	The updated `Experiment`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Experiment not found or invalid params (400, 404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
updated = ws.update_experiment(
    "xyz-456", UpdateExperimentParams(description="Updated")
)

Source code in src/mixpanel_headless/workspace.py

def update_experiment(
    self, experiment_id: str, params: UpdateExperimentParams
) -> Experiment:
    """Update an experiment (PATCH semantics).

    Args:
        experiment_id: Experiment UUID.
        params: Fields to update.

    Returns:
        The updated ``Experiment``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Experiment not found or invalid params (400, 404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        updated = ws.update_experiment(
            "xyz-456", UpdateExperimentParams(description="Updated")
        )
        ```
    """
    client = self._require_api_client()
    raw = client.update_experiment(
        experiment_id, params.model_dump(exclude_none=True)
    )
    if raw is None:
        raise MixpanelHeadlessError(
            "API returned empty response for update_experiment",
        )
    return validate_response_model(Experiment, raw, endpoint="update_experiment")

delete_experiment ¶

delete_experiment(experiment_id: str) -> None

Delete an experiment.

PARAMETER	DESCRIPTION
`experiment_id`	Experiment UUID. TYPE: `str`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Experiment not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_experiment("xyz-456-uuid")

Source code in src/mixpanel_headless/workspace.py

def delete_experiment(self, experiment_id: str) -> None:
    """Delete an experiment.

    Args:
        experiment_id: Experiment UUID.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Experiment not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_experiment("xyz-456-uuid")
        ```
    """
    client = self._require_api_client()
    client.delete_experiment(experiment_id)

launch_experiment ¶

launch_experiment(experiment_id: str) -> Experiment

Launch an experiment (Draft → Active).

PARAMETER	DESCRIPTION
`experiment_id`	Experiment UUID. TYPE: `str`

RETURNS	DESCRIPTION
`Experiment`	The launched `Experiment` with updated status.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid state transition (400) or not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
launched = ws.launch_experiment("xyz-456-uuid")

Source code in src/mixpanel_headless/workspace.py

def launch_experiment(self, experiment_id: str) -> Experiment:
    """Launch an experiment (Draft → Active).

    Args:
        experiment_id: Experiment UUID.

    Returns:
        The launched ``Experiment`` with updated status.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid state transition (400) or not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        launched = ws.launch_experiment("xyz-456-uuid")
        ```
    """
    client = self._require_api_client()
    raw = client.launch_experiment(experiment_id)
    return validate_response_model(Experiment, raw, endpoint="launch_experiment")

conclude_experiment ¶

conclude_experiment(
    experiment_id: str, *, params: ExperimentConcludeParams | None = None
) -> Experiment

Conclude an experiment (Active → Concluded).

Always sends a JSON body (empty {} if no params).

PARAMETER	DESCRIPTION
`experiment_id`	Experiment UUID. TYPE: `str`
`params`	Optional conclude parameters (e.g. end date override). TYPE: `ExperimentConcludeParams \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Experiment`	The concluded `Experiment`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid state transition (400) or not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
concluded = ws.conclude_experiment("xyz-456-uuid")

Source code in src/mixpanel_headless/workspace.py

def conclude_experiment(
    self,
    experiment_id: str,
    *,
    params: ExperimentConcludeParams | None = None,
) -> Experiment:
    """Conclude an experiment (Active → Concluded).

    Always sends a JSON body (empty ``{}`` if no params).

    Args:
        experiment_id: Experiment UUID.
        params: Optional conclude parameters (e.g. end date override).

    Returns:
        The concluded ``Experiment``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid state transition (400) or not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        concluded = ws.conclude_experiment("xyz-456-uuid")
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True) if params else {}
    raw = client.conclude_experiment(experiment_id, body)
    return validate_response_model(Experiment, raw, endpoint="conclude_experiment")

decide_experiment ¶

decide_experiment(
    experiment_id: str, params: ExperimentDecideParams
) -> Experiment

Record the experiment decision (Concluded → Success/Fail).

PARAMETER	DESCRIPTION
`experiment_id`	Experiment UUID. TYPE: `str`
`params`	Decision parameters (success, variant, message). TYPE: `ExperimentDecideParams`

RETURNS	DESCRIPTION
`Experiment`	The decided `Experiment` with terminal status.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid state transition (400) or not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
decided = ws.decide_experiment(
    "xyz-456",
    ExperimentDecideParams(success=True, variant="simplified"),
)

Source code in src/mixpanel_headless/workspace.py

def decide_experiment(
    self, experiment_id: str, params: ExperimentDecideParams
) -> Experiment:
    """Record the experiment decision (Concluded → Success/Fail).

    Args:
        experiment_id: Experiment UUID.
        params: Decision parameters (success, variant, message).

    Returns:
        The decided ``Experiment`` with terminal status.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid state transition (400) or not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        decided = ws.decide_experiment(
            "xyz-456",
            ExperimentDecideParams(success=True, variant="simplified"),
        )
        ```
    """
    client = self._require_api_client()
    raw = client.decide_experiment(
        experiment_id, params.model_dump(exclude_none=True)
    )
    return validate_response_model(Experiment, raw, endpoint="decide_experiment")

archive_experiment ¶

archive_experiment(experiment_id: str) -> None

Archive an experiment.

PARAMETER	DESCRIPTION
`experiment_id`	Experiment UUID. TYPE: `str`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Experiment not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.archive_experiment("xyz-456-uuid")

Source code in src/mixpanel_headless/workspace.py

def archive_experiment(self, experiment_id: str) -> None:
    """Archive an experiment.

    Args:
        experiment_id: Experiment UUID.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Experiment not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.archive_experiment("xyz-456-uuid")
        ```
    """
    client = self._require_api_client()
    client.archive_experiment(experiment_id)

restore_experiment ¶

restore_experiment(experiment_id: str) -> Experiment

Restore an archived experiment.

PARAMETER	DESCRIPTION
`experiment_id`	Experiment UUID. TYPE: `str`

RETURNS	DESCRIPTION
`Experiment`	The restored `Experiment`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Experiment not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
restored = ws.restore_experiment("xyz-456-uuid")

Source code in src/mixpanel_headless/workspace.py

def restore_experiment(self, experiment_id: str) -> Experiment:
    """Restore an archived experiment.

    Args:
        experiment_id: Experiment UUID.

    Returns:
        The restored ``Experiment``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Experiment not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        restored = ws.restore_experiment("xyz-456-uuid")
        ```
    """
    client = self._require_api_client()
    raw = client.restore_experiment(experiment_id)
    return validate_response_model(Experiment, raw, endpoint="restore_experiment")

duplicate_experiment ¶

duplicate_experiment(
    experiment_id: str, params: DuplicateExperimentParams
) -> Experiment

Duplicate an experiment.

A name is required because the Mixpanel API returns an empty response body when duplicating without one.

PARAMETER	DESCRIPTION
`experiment_id`	Experiment UUID. TYPE: `str`
`params`	Duplication parameters (`name` is required). TYPE: `DuplicateExperimentParams`

RETURNS	DESCRIPTION
`Experiment`	The newly created duplicate `Experiment`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Experiment not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
dup = ws.duplicate_experiment(
    "xyz-456-uuid",
    DuplicateExperimentParams(name="Copy"),
)

Source code in src/mixpanel_headless/workspace.py

def duplicate_experiment(
    self,
    experiment_id: str,
    params: DuplicateExperimentParams,
) -> Experiment:
    """Duplicate an experiment.

    A name is required because the Mixpanel API returns an empty
    response body when duplicating without one.

    Args:
        experiment_id: Experiment UUID.
        params: Duplication parameters (``name`` is required).

    Returns:
        The newly created duplicate ``Experiment``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Experiment not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        dup = ws.duplicate_experiment(
            "xyz-456-uuid",
            DuplicateExperimentParams(name="Copy"),
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.duplicate_experiment(experiment_id, body)
    return validate_response_model(Experiment, raw, endpoint="duplicate_experiment")

list_erf_experiments ¶

list_erf_experiments() -> list[dict[str, Any]]

List experiments in ERF (Experiment Results Framework) format.

RETURNS	DESCRIPTION
`list[dict[str, Any]]`	List of experiment dicts in ERF format.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
erf = ws.list_erf_experiments()

Source code in src/mixpanel_headless/workspace.py

def list_erf_experiments(self) -> list[dict[str, Any]]:
    """List experiments in ERF (Experiment Results Framework) format.

    Returns:
        List of experiment dicts in ERF format.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        erf = ws.list_erf_experiments()
        ```
    """
    client = self._require_api_client()
    return client.list_erf_experiments()

list_alerts ¶

list_alerts(
    *, bookmark_id: int | None = None, skip_user_filter: bool | None = None
) -> list[CustomAlert]

List custom alerts for the current project.

PARAMETER	DESCRIPTION
`bookmark_id`	Filter alerts by linked bookmark ID. TYPE: `int \| None` DEFAULT: `None`
`skip_user_filter`	If True, list alerts for all users. TYPE: `bool \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[CustomAlert]`	List of `CustomAlert` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
alerts = ws.list_alerts()
for alert in alerts:
    print(f"{alert.name} (paused={alert.paused})")

Source code in src/mixpanel_headless/workspace.py

def list_alerts(
    self,
    *,
    bookmark_id: int | None = None,
    skip_user_filter: bool | None = None,
) -> list[CustomAlert]:
    """List custom alerts for the current project.

    Args:
        bookmark_id: Filter alerts by linked bookmark ID.
        skip_user_filter: If True, list alerts for all users.

    Returns:
        List of ``CustomAlert`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        alerts = ws.list_alerts()
        for alert in alerts:
            print(f"{alert.name} (paused={alert.paused})")
        ```
    """
    client = self._require_api_client()
    raw_list = client.list_alerts(
        bookmark_id=bookmark_id, skip_user_filter=skip_user_filter
    )
    return validate_response_models(CustomAlert, raw_list, endpoint="list_alerts")

create_alert ¶

create_alert(params: CreateAlertParams) -> CustomAlert

Create a new custom alert.

PARAMETER	DESCRIPTION
`params`	Alert creation parameters (bookmark_id, name, condition, frequency, paused, and subscriptions are required). TYPE: `CreateAlertParams`

RETURNS	DESCRIPTION
`CustomAlert`	The created `CustomAlert`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
alert = ws.create_alert(
    CreateAlertParams(
        bookmark_id=123,
        name="Daily signups drop",
        condition={"operator": "less_than", "value": 100},
        frequency=86400,
        paused=False,
        subscriptions=[{"type": "email", "value": "team@co.com"}],
    )
)

Source code in src/mixpanel_headless/workspace.py

def create_alert(self, params: CreateAlertParams) -> CustomAlert:
    """Create a new custom alert.

    Args:
        params: Alert creation parameters (bookmark_id, name, condition,
            frequency, paused, and subscriptions are required).

    Returns:
        The created ``CustomAlert``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        alert = ws.create_alert(
            CreateAlertParams(
                bookmark_id=123,
                name="Daily signups drop",
                condition={"operator": "less_than", "value": 100},
                frequency=86400,
                paused=False,
                subscriptions=[{"type": "email", "value": "team@co.com"}],
            )
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.create_alert(body)
    return validate_response_model(CustomAlert, raw, endpoint="create_alert")

get_alert ¶

get_alert(alert_id: int) -> CustomAlert

Get a single custom alert by ID.

PARAMETER	DESCRIPTION
`alert_id`	Alert ID (integer). TYPE: `int`

RETURNS	DESCRIPTION
`CustomAlert`	The `CustomAlert` object.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Alert not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
alert = ws.get_alert(42)
print(alert.name)

Source code in src/mixpanel_headless/workspace.py

def get_alert(self, alert_id: int) -> CustomAlert:
    """Get a single custom alert by ID.

    Args:
        alert_id: Alert ID (integer).

    Returns:
        The ``CustomAlert`` object.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Alert not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        alert = ws.get_alert(42)
        print(alert.name)
        ```
    """
    client = self._require_api_client()
    raw = client.get_alert(alert_id)
    return validate_response_model(CustomAlert, raw, endpoint="get_alert")

update_alert ¶

update_alert(alert_id: int, params: UpdateAlertParams) -> CustomAlert

Update a custom alert (PATCH semantics).

PARAMETER	DESCRIPTION
`alert_id`	Alert ID (integer). TYPE: `int`
`params`	Fields to update. TYPE: `UpdateAlertParams`

RETURNS	DESCRIPTION
`CustomAlert`	The updated `CustomAlert`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Alert not found (404) or validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
alert = ws.update_alert(
    42, UpdateAlertParams(name="Renamed alert")
)

Source code in src/mixpanel_headless/workspace.py

def update_alert(self, alert_id: int, params: UpdateAlertParams) -> CustomAlert:
    """Update a custom alert (PATCH semantics).

    Args:
        alert_id: Alert ID (integer).
        params: Fields to update.

    Returns:
        The updated ``CustomAlert``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Alert not found (404) or validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        alert = ws.update_alert(
            42, UpdateAlertParams(name="Renamed alert")
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.update_alert(alert_id, body)
    return validate_response_model(CustomAlert, raw, endpoint="update_alert")

delete_alert ¶

delete_alert(alert_id: int) -> None

Delete a custom alert.

PARAMETER	DESCRIPTION
`alert_id`	Alert ID (integer). TYPE: `int`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Alert not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_alert(42)

Source code in src/mixpanel_headless/workspace.py

def delete_alert(self, alert_id: int) -> None:
    """Delete a custom alert.

    Args:
        alert_id: Alert ID (integer).

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Alert not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_alert(42)
        ```
    """
    client = self._require_api_client()
    client.delete_alert(alert_id)

bulk_delete_alerts ¶

bulk_delete_alerts(ids: list[int]) -> None

Bulk-delete custom alerts.

PARAMETER	DESCRIPTION
`ids`	List of alert IDs to delete. TYPE: `list[int]`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.bulk_delete_alerts([1, 2, 3])

Source code in src/mixpanel_headless/workspace.py

def bulk_delete_alerts(self, ids: list[int]) -> None:
    """Bulk-delete custom alerts.

    Args:
        ids: List of alert IDs to delete.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.bulk_delete_alerts([1, 2, 3])
        ```
    """
    client = self._require_api_client()
    client.bulk_delete_alerts(ids)

get_alert_count ¶

get_alert_count(*, alert_type: str | None = None) -> AlertCount

Get alert count and limits.

PARAMETER	DESCRIPTION
`alert_type`	Optional filter by alert type. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`AlertCount`	`AlertCount` with count, limit, and is_below_limit.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
count = ws.get_alert_count()
if count.is_below_limit:
    print(f"{count.anomaly_alerts_count}/{count.alert_limit}")

Source code in src/mixpanel_headless/workspace.py

def get_alert_count(self, *, alert_type: str | None = None) -> AlertCount:
    """Get alert count and limits.

    Args:
        alert_type: Optional filter by alert type.

    Returns:
        ``AlertCount`` with count, limit, and is_below_limit.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        count = ws.get_alert_count()
        if count.is_below_limit:
            print(f"{count.anomaly_alerts_count}/{count.alert_limit}")
        ```
    """
    client = self._require_api_client()
    raw = client.get_alert_count(alert_type=alert_type)
    return validate_response_model(AlertCount, raw, endpoint="get_alert_count")

get_alert_history ¶

get_alert_history(
    alert_id: int,
    *,
    page_size: int | None = None,
    next_cursor: str | None = None,
    previous_cursor: str | None = None,
) -> AlertHistoryResponse

Get alert trigger history (paginated).

PARAMETER	DESCRIPTION
`alert_id`	Alert ID (integer). TYPE: `int`
`page_size`	Number of results per page. TYPE: `int \| None` DEFAULT: `None`
`next_cursor`	Cursor for the next page. TYPE: `str \| None` DEFAULT: `None`
`previous_cursor`	Cursor for the previous page. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`AlertHistoryResponse`	`AlertHistoryResponse` with results and pagination metadata.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Alert not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
history = ws.get_alert_history(42, page_size=10)
for entry in history.results:
    print(entry)

Source code in src/mixpanel_headless/workspace.py

def get_alert_history(
    self,
    alert_id: int,
    *,
    page_size: int | None = None,
    next_cursor: str | None = None,
    previous_cursor: str | None = None,
) -> AlertHistoryResponse:
    """Get alert trigger history (paginated).

    Args:
        alert_id: Alert ID (integer).
        page_size: Number of results per page.
        next_cursor: Cursor for the next page.
        previous_cursor: Cursor for the previous page.

    Returns:
        ``AlertHistoryResponse`` with results and pagination metadata.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Alert not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        history = ws.get_alert_history(42, page_size=10)
        for entry in history.results:
            print(entry)
        ```
    """
    client = self._require_api_client()
    raw = client.get_alert_history(
        alert_id,
        page_size=page_size,
        next_cursor=next_cursor,
        previous_cursor=previous_cursor,
    )
    return validate_response_model(
        AlertHistoryResponse, raw, endpoint="get_alert_history"
    )

test_alert ¶

test_alert(params: CreateAlertParams) -> dict[str, Any]

Send a test alert notification.

PARAMETER	DESCRIPTION
`params`	Alert parameters for the test (same shape as create). TYPE: `CreateAlertParams`

RETURNS	DESCRIPTION
`dict[str, Any]`	Dictionary with test result status (opaque response).

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
result = ws.test_alert(
    CreateAlertParams(
        bookmark_id=123, name="Test",
        condition={}, frequency=86400,
        paused=False, subscriptions=[],
    )
)

Source code in src/mixpanel_headless/workspace.py

def test_alert(self, params: CreateAlertParams) -> dict[str, Any]:
    """Send a test alert notification.

    Args:
        params: Alert parameters for the test (same shape as create).

    Returns:
        Dictionary with test result status (opaque response).

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        result = ws.test_alert(
            CreateAlertParams(
                bookmark_id=123, name="Test",
                condition={}, frequency=86400,
                paused=False, subscriptions=[],
            )
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    return client.test_alert(body)

get_alert_screenshot_url ¶

get_alert_screenshot_url(gcs_key: str) -> AlertScreenshotResponse

Get a signed URL for an alert screenshot.

PARAMETER	DESCRIPTION
`gcs_key`	GCS object key for the screenshot. TYPE: `str`

RETURNS	DESCRIPTION
`AlertScreenshotResponse`	`AlertScreenshotResponse` with the signed URL.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Screenshot not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
resp = ws.get_alert_screenshot_url("screenshots/abc.png")
print(resp.signed_url)

Source code in src/mixpanel_headless/workspace.py

def get_alert_screenshot_url(self, gcs_key: str) -> AlertScreenshotResponse:
    """Get a signed URL for an alert screenshot.

    Args:
        gcs_key: GCS object key for the screenshot.

    Returns:
        ``AlertScreenshotResponse`` with the signed URL.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Screenshot not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        resp = ws.get_alert_screenshot_url("screenshots/abc.png")
        print(resp.signed_url)
        ```
    """
    client = self._require_api_client()
    raw = client.get_alert_screenshot_url(gcs_key)
    return validate_response_model(
        AlertScreenshotResponse, raw, endpoint="get_alert_screenshot_url"
    )

validate_alerts_for_bookmark ¶

validate_alerts_for_bookmark(
    params: ValidateAlertsForBookmarkParams,
) -> ValidateAlertsForBookmarkResponse

Validate alerts against a bookmark configuration.

PARAMETER	DESCRIPTION
`params`	Validation parameters (alert_ids, bookmark_type, bookmark_params are required). TYPE: `ValidateAlertsForBookmarkParams`

RETURNS	DESCRIPTION
`ValidateAlertsForBookmarkResponse`	`ValidateAlertsForBookmarkResponse` with per-alert validations
`ValidateAlertsForBookmarkResponse`	and invalid count.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
resp = ws.validate_alerts_for_bookmark(
    ValidateAlertsForBookmarkParams(
        alert_ids=[1, 2],
        bookmark_type="insights",
        bookmark_params={"event": "Signup"},
    )
)
if resp.invalid_count > 0:
    for v in resp.alert_validations:
        if not v.valid:
            print(f"{v.alert_name}: {v.reason}")

Source code in src/mixpanel_headless/workspace.py

def validate_alerts_for_bookmark(
    self, params: ValidateAlertsForBookmarkParams
) -> ValidateAlertsForBookmarkResponse:
    """Validate alerts against a bookmark configuration.

    Args:
        params: Validation parameters (alert_ids, bookmark_type,
            bookmark_params are required).

    Returns:
        ``ValidateAlertsForBookmarkResponse`` with per-alert validations
        and invalid count.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        resp = ws.validate_alerts_for_bookmark(
            ValidateAlertsForBookmarkParams(
                alert_ids=[1, 2],
                bookmark_type="insights",
                bookmark_params={"event": "Signup"},
            )
        )
        if resp.invalid_count > 0:
            for v in resp.alert_validations:
                if not v.valid:
                    print(f"{v.alert_name}: {v.reason}")
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.validate_alerts_for_bookmark(body)
    return validate_response_model(
        ValidateAlertsForBookmarkResponse,
        raw,
        endpoint="validate_alerts_for_bookmark",
    )

list_annotations ¶

list_annotations(
    *,
    from_date: str | None = None,
    to_date: str | None = None,
    tags: list[int] | None = None,
) -> list[Annotation]

List timeline annotations for the project.

PARAMETER	DESCRIPTION
`from_date`	Start date filter (ISO format, e.g. `"2026-01-01"`). TYPE: `str \| None` DEFAULT: `None`
`to_date`	End date filter (ISO format, e.g. `"2026-03-31"`). TYPE: `str \| None` DEFAULT: `None`
`tags`	Tag IDs to filter by. TYPE: `list[int] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[Annotation]`	List of `Annotation` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
annotations = ws.list_annotations(from_date="2026-01-01")
for ann in annotations:
    print(f"{ann.date}: {ann.description}")

Source code in src/mixpanel_headless/workspace.py

def list_annotations(
    self,
    *,
    from_date: str | None = None,
    to_date: str | None = None,
    tags: list[int] | None = None,
) -> list[Annotation]:
    """List timeline annotations for the project.

    Args:
        from_date: Start date filter (ISO format, e.g. ``"2026-01-01"``).
        to_date: End date filter (ISO format, e.g. ``"2026-03-31"``).
        tags: Tag IDs to filter by.

    Returns:
        List of ``Annotation`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        annotations = ws.list_annotations(from_date="2026-01-01")
        for ann in annotations:
            print(f"{ann.date}: {ann.description}")
        ```
    """
    client = self._require_api_client()
    raw_list = client.list_annotations(
        from_date=from_date, to_date=to_date, tags=tags
    )
    return validate_response_models(
        Annotation, raw_list, endpoint="list_annotations"
    )

create_annotation ¶

create_annotation(params: CreateAnnotationParams) -> Annotation

Create a new timeline annotation.

PARAMETER	DESCRIPTION
`params`	Annotation creation parameters (date, description required). TYPE: `CreateAnnotationParams`

RETURNS	DESCRIPTION
`Annotation`	The created `Annotation`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ann = ws.create_annotation(
    CreateAnnotationParams(
        date="2026-03-31", description="v2.5 release"
    )
)

Source code in src/mixpanel_headless/workspace.py

def create_annotation(self, params: CreateAnnotationParams) -> Annotation:
    """Create a new timeline annotation.

    Args:
        params: Annotation creation parameters (date, description required).

    Returns:
        The created ``Annotation``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ann = ws.create_annotation(
            CreateAnnotationParams(
                date="2026-03-31", description="v2.5 release"
            )
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.create_annotation(body)
    return validate_response_model(Annotation, raw, endpoint="create_annotation")

get_annotation ¶

get_annotation(annotation_id: int) -> Annotation

Get a single annotation by ID.

PARAMETER	DESCRIPTION
`annotation_id`	Annotation ID. TYPE: `int`

RETURNS	DESCRIPTION
`Annotation`	The `Annotation` object.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Annotation not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ann = ws.get_annotation(42)
print(ann.description)

Source code in src/mixpanel_headless/workspace.py

def get_annotation(self, annotation_id: int) -> Annotation:
    """Get a single annotation by ID.

    Args:
        annotation_id: Annotation ID.

    Returns:
        The ``Annotation`` object.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Annotation not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ann = ws.get_annotation(42)
        print(ann.description)
        ```
    """
    client = self._require_api_client()
    raw = client.get_annotation(annotation_id)
    return validate_response_model(Annotation, raw, endpoint="get_annotation")

update_annotation ¶

update_annotation(
    annotation_id: int, params: UpdateAnnotationParams
) -> Annotation

Update an annotation (PATCH semantics).

PARAMETER	DESCRIPTION
`annotation_id`	Annotation ID. TYPE: `int`
`params`	Fields to update (description, tags). TYPE: `UpdateAnnotationParams`

RETURNS	DESCRIPTION
`Annotation`	The updated `Annotation`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Annotation not found (404) or validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ann = ws.update_annotation(
    42, UpdateAnnotationParams(description="Updated text")
)

Source code in src/mixpanel_headless/workspace.py

def update_annotation(
    self, annotation_id: int, params: UpdateAnnotationParams
) -> Annotation:
    """Update an annotation (PATCH semantics).

    Args:
        annotation_id: Annotation ID.
        params: Fields to update (description, tags).

    Returns:
        The updated ``Annotation``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Annotation not found (404) or validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ann = ws.update_annotation(
            42, UpdateAnnotationParams(description="Updated text")
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.update_annotation(annotation_id, body)
    return validate_response_model(Annotation, raw, endpoint="update_annotation")

delete_annotation ¶

delete_annotation(annotation_id: int) -> None

Delete an annotation.

PARAMETER	DESCRIPTION
`annotation_id`	Annotation ID. TYPE: `int`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Annotation not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_annotation(42)

Source code in src/mixpanel_headless/workspace.py

def delete_annotation(self, annotation_id: int) -> None:
    """Delete an annotation.

    Args:
        annotation_id: Annotation ID.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Annotation not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_annotation(42)
        ```
    """
    client = self._require_api_client()
    client.delete_annotation(annotation_id)

list_annotation_tags ¶

list_annotation_tags() -> list[AnnotationTag]

List annotation tags for the project.

RETURNS	DESCRIPTION
`list[AnnotationTag]`	List of `AnnotationTag` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
tags = ws.list_annotation_tags()
for tag in tags:
    print(tag.name)

Source code in src/mixpanel_headless/workspace.py

def list_annotation_tags(self) -> list[AnnotationTag]:
    """List annotation tags for the project.

    Returns:
        List of ``AnnotationTag`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        tags = ws.list_annotation_tags()
        for tag in tags:
            print(tag.name)
        ```
    """
    client = self._require_api_client()
    raw_list = client.list_annotation_tags()
    return validate_response_models(
        AnnotationTag, raw_list, endpoint="list_annotation_tags"
    )

create_annotation_tag ¶

create_annotation_tag(params: CreateAnnotationTagParams) -> AnnotationTag

Create a new annotation tag.

PARAMETER	DESCRIPTION
`params`	Tag creation parameters (name required). TYPE: `CreateAnnotationTagParams`

RETURNS	DESCRIPTION
`AnnotationTag`	The created `AnnotationTag`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
tag = ws.create_annotation_tag(
    CreateAnnotationTagParams(name="releases")
)

Source code in src/mixpanel_headless/workspace.py

def create_annotation_tag(self, params: CreateAnnotationTagParams) -> AnnotationTag:
    """Create a new annotation tag.

    Args:
        params: Tag creation parameters (name required).

    Returns:
        The created ``AnnotationTag``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        tag = ws.create_annotation_tag(
            CreateAnnotationTagParams(name="releases")
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.create_annotation_tag(body)
    return validate_response_model(
        AnnotationTag, raw, endpoint="create_annotation_tag"
    )

list_webhooks ¶

list_webhooks() -> list[ProjectWebhook]

List all webhooks for the current project.

RETURNS	DESCRIPTION
`list[ProjectWebhook]`	List of `ProjectWebhook` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
webhooks = ws.list_webhooks()
for wh in webhooks:
    print(f"{wh.name} -> {wh.url}")

Source code in src/mixpanel_headless/workspace.py

def list_webhooks(self) -> list[ProjectWebhook]:
    """List all webhooks for the current project.

    Returns:
        List of ``ProjectWebhook`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        webhooks = ws.list_webhooks()
        for wh in webhooks:
            print(f"{wh.name} -> {wh.url}")
        ```
    """
    client = self._require_api_client()
    raw_list = client.list_webhooks()
    return validate_response_models(
        ProjectWebhook, raw_list, endpoint="list_webhooks"
    )

create_webhook ¶

create_webhook(params: CreateWebhookParams) -> WebhookMutationResult

Create a new webhook.

PARAMETER	DESCRIPTION
`params`	Webhook creation parameters. TYPE: `CreateWebhookParams`

RETURNS	DESCRIPTION
`WebhookMutationResult`	`WebhookMutationResult` with the new webhook's id and name.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
result = ws.create_webhook(
    CreateWebhookParams(name="Pipeline", url="https://example.com/hook")
)
print(result.id)

Source code in src/mixpanel_headless/workspace.py

def create_webhook(self, params: CreateWebhookParams) -> WebhookMutationResult:
    """Create a new webhook.

    Args:
        params: Webhook creation parameters.

    Returns:
        ``WebhookMutationResult`` with the new webhook's id and name.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        result = ws.create_webhook(
            CreateWebhookParams(name="Pipeline", url="https://example.com/hook")
        )
        print(result.id)
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.create_webhook(body)
    return validate_response_model(
        WebhookMutationResult, raw, endpoint="create_webhook"
    )

update_webhook ¶

update_webhook(
    webhook_id: str, params: UpdateWebhookParams
) -> WebhookMutationResult

Update an existing webhook.

PARAMETER	DESCRIPTION
`webhook_id`	Webhook UUID string. TYPE: `str`
`params`	Fields to update (PATCH semantics). TYPE: `UpdateWebhookParams`

RETURNS	DESCRIPTION
`WebhookMutationResult`	`WebhookMutationResult` with the updated webhook's id and name.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Webhook not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
result = ws.update_webhook(
    "wh-uuid-123",
    UpdateWebhookParams(name="Renamed Hook"),
)

Source code in src/mixpanel_headless/workspace.py

def update_webhook(
    self, webhook_id: str, params: UpdateWebhookParams
) -> WebhookMutationResult:
    """Update an existing webhook.

    Args:
        webhook_id: Webhook UUID string.
        params: Fields to update (PATCH semantics).

    Returns:
        ``WebhookMutationResult`` with the updated webhook's id and name.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Webhook not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        result = ws.update_webhook(
            "wh-uuid-123",
            UpdateWebhookParams(name="Renamed Hook"),
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.update_webhook(webhook_id, body)
    return validate_response_model(
        WebhookMutationResult, raw, endpoint="update_webhook"
    )

delete_webhook ¶

delete_webhook(webhook_id: str) -> None

Delete a webhook.

PARAMETER	DESCRIPTION
`webhook_id`	Webhook UUID string. TYPE: `str`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Webhook not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_webhook("wh-uuid-123")

Source code in src/mixpanel_headless/workspace.py

def delete_webhook(self, webhook_id: str) -> None:
    """Delete a webhook.

    Args:
        webhook_id: Webhook UUID string.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Webhook not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_webhook("wh-uuid-123")
        ```
    """
    client = self._require_api_client()
    client.delete_webhook(webhook_id)

test_webhook ¶

test_webhook(params: WebhookTestParams) -> WebhookTestResult

Test webhook connectivity.

PARAMETER	DESCRIPTION
`params`	Webhook test parameters (url is required). TYPE: `WebhookTestParams`

RETURNS	DESCRIPTION
`WebhookTestResult`	`WebhookTestResult` with success, status_code, and message.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	API error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
result = ws.test_webhook(
    WebhookTestParams(url="https://example.com/hook")
)
if result.success:
    print("Webhook is reachable")

Source code in src/mixpanel_headless/workspace.py

def test_webhook(self, params: WebhookTestParams) -> WebhookTestResult:
    """Test webhook connectivity.

    Args:
        params: Webhook test parameters (url is required).

    Returns:
        ``WebhookTestResult`` with success, status_code, and message.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: API error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        result = ws.test_webhook(
            WebhookTestParams(url="https://example.com/hook")
        )
        if result.success:
            print("Webhook is reachable")
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.test_webhook(body)
    return validate_response_model(WebhookTestResult, raw, endpoint="test_webhook")

get_event_definitions ¶

get_event_definitions(*, names: list[str]) -> list[EventDefinition]

Get event definitions from Lexicon by name.

Retrieves metadata (description, tags, visibility, etc.) for the specified events from the Mixpanel Lexicon.

PARAMETER	DESCRIPTION
`names`	List of event names to look up. TYPE: `list[str]`

RETURNS	DESCRIPTION
`list[EventDefinition]`	List of `EventDefinition` objects for the requested events.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
defs = ws.get_event_definitions(names=["Signup", "Login"])
for d in defs:
    print(f"{d.name}: {d.description}")

Source code in src/mixpanel_headless/workspace.py

def get_event_definitions(self, *, names: list[str]) -> list[EventDefinition]:
    """Get event definitions from Lexicon by name.

    Retrieves metadata (description, tags, visibility, etc.) for the
    specified events from the Mixpanel Lexicon.

    Args:
        names: List of event names to look up.

    Returns:
        List of ``EventDefinition`` objects for the requested events.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        defs = ws.get_event_definitions(names=["Signup", "Login"])
        for d in defs:
            print(f"{d.name}: {d.description}")
        ```
    """
    client = self._require_api_client()
    raw_list = client.get_event_definitions(names)
    return validate_response_models(
        EventDefinition, raw_list, endpoint="get_event_definitions"
    )

update_event_definition ¶

update_event_definition(
    event_name: str, params: UpdateEventDefinitionParams
) -> EventDefinition

Update an event definition in Lexicon.

PARAMETER	DESCRIPTION
`event_name`	Name of the event to update. TYPE: `str`
`params`	Fields to update (hidden, dropped, merged, verified, tags, display_name, description). TYPE: `UpdateEventDefinitionParams`

RETURNS	DESCRIPTION
`EventDefinition`	The updated `EventDefinition`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Event not found (404) or validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
definition = ws.update_event_definition(
    "Signup",
    UpdateEventDefinitionParams(description="User signed up"),
)

Source code in src/mixpanel_headless/workspace.py

def update_event_definition(
    self, event_name: str, params: UpdateEventDefinitionParams
) -> EventDefinition:
    """Update an event definition in Lexicon.

    Args:
        event_name: Name of the event to update.
        params: Fields to update (hidden, dropped, merged,
            verified, tags, display_name, description).

    Returns:
        The updated ``EventDefinition``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Event not found (404) or validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        definition = ws.update_event_definition(
            "Signup",
            UpdateEventDefinitionParams(description="User signed up"),
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True, by_alias=True)
    raw = client.update_event_definition(event_name, body)
    return validate_response_model(
        EventDefinition, raw, endpoint="update_event_definition"
    )

delete_event_definition ¶

delete_event_definition(event_name: str) -> None

Delete an event definition from Lexicon.

PARAMETER	DESCRIPTION
`event_name`	Name of the event to delete. TYPE: `str`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Event not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_event_definition("OldEvent")

Source code in src/mixpanel_headless/workspace.py

def delete_event_definition(self, event_name: str) -> None:
    """Delete an event definition from Lexicon.

    Args:
        event_name: Name of the event to delete.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Event not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_event_definition("OldEvent")
        ```
    """
    client = self._require_api_client()
    client.delete_event_definition(event_name)

bulk_update_event_definitions ¶

bulk_update_event_definitions(
    params: BulkUpdateEventsParams,
) -> list[EventDefinition]

Bulk-update event definitions in Lexicon.

PARAMETER	DESCRIPTION
`params`	Bulk update parameters containing a list of event updates (name + fields to change). TYPE: `BulkUpdateEventsParams`

RETURNS	DESCRIPTION
`list[EventDefinition]`	List of updated `EventDefinition` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
defs = ws.bulk_update_event_definitions(
    BulkUpdateEventsParams(events=[
        {"name": "Signup", "description": "User signed up"},
        {"name": "Login", "hidden": True},
    ])
)

Source code in src/mixpanel_headless/workspace.py

def bulk_update_event_definitions(
    self, params: BulkUpdateEventsParams
) -> list[EventDefinition]:
    """Bulk-update event definitions in Lexicon.

    Args:
        params: Bulk update parameters containing a list of event
            updates (name + fields to change).

    Returns:
        List of updated ``EventDefinition`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        defs = ws.bulk_update_event_definitions(
            BulkUpdateEventsParams(events=[
                {"name": "Signup", "description": "User signed up"},
                {"name": "Login", "hidden": True},
            ])
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True, by_alias=True)
    raw_list = client.bulk_update_event_definitions(body)
    return validate_response_models(
        EventDefinition, raw_list, endpoint="bulk_update_event_definitions"
    )

get_property_definitions ¶

get_property_definitions(
    *, names: list[str], resource_type: str | None = None
) -> list[PropertyDefinition]

Get property definitions from Lexicon by name.

Retrieves metadata (description, tags, visibility, etc.) for the specified properties from the Mixpanel Lexicon.

PARAMETER	DESCRIPTION
`names`	List of property names to look up. TYPE: `list[str]`
`resource_type`	Optional resource type filter (e.g. `"event"`, `"user"`, `"groupprofile"`). TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[PropertyDefinition]`	List of `PropertyDefinition` objects for the requested properties.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
defs = ws.get_property_definitions(
    names=["plan_type", "country"],
    resource_type="event",
)
for d in defs:
    print(f"{d.name}: {d.description}")

Source code in src/mixpanel_headless/workspace.py

def get_property_definitions(
    self,
    *,
    names: list[str],
    resource_type: str | None = None,
) -> list[PropertyDefinition]:
    """Get property definitions from Lexicon by name.

    Retrieves metadata (description, tags, visibility, etc.) for the
    specified properties from the Mixpanel Lexicon.

    Args:
        names: List of property names to look up.
        resource_type: Optional resource type filter (e.g. ``"event"``,
            ``"user"``, ``"groupprofile"``).

    Returns:
        List of ``PropertyDefinition`` objects for the requested properties.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        defs = ws.get_property_definitions(
            names=["plan_type", "country"],
            resource_type="event",
        )
        for d in defs:
            print(f"{d.name}: {d.description}")
        ```
    """
    client = self._require_api_client()
    raw_list = client.get_property_definitions(names, resource_type=resource_type)
    return validate_response_models(
        PropertyDefinition, raw_list, endpoint="get_property_definitions"
    )

update_property_definition ¶

update_property_definition(
    property_name: str, params: UpdatePropertyDefinitionParams
) -> PropertyDefinition

Update a property definition in Lexicon.

PARAMETER	DESCRIPTION
`property_name`	Name of the property to update. TYPE: `str`
`params`	Fields to update (hidden, dropped, merged, sensitive, display_name, description, example_value, resource_type). TYPE: `UpdatePropertyDefinitionParams`

RETURNS	DESCRIPTION
`PropertyDefinition`	The updated `PropertyDefinition`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Property not found (404) or validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
definition = ws.update_property_definition(
    "plan_type",
    UpdatePropertyDefinitionParams(description="User plan tier"),
)

Source code in src/mixpanel_headless/workspace.py

def update_property_definition(
    self, property_name: str, params: UpdatePropertyDefinitionParams
) -> PropertyDefinition:
    """Update a property definition in Lexicon.

    Args:
        property_name: Name of the property to update.
        params: Fields to update (hidden, dropped, merged, sensitive,
            display_name, description, example_value, resource_type).

    Returns:
        The updated ``PropertyDefinition``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Property not found (404) or validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        definition = ws.update_property_definition(
            "plan_type",
            UpdatePropertyDefinitionParams(description="User plan tier"),
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True, by_alias=True)
    raw = client.update_property_definition(property_name, body)
    return validate_response_model(
        PropertyDefinition, raw, endpoint="update_property_definition"
    )

bulk_update_property_definitions ¶

bulk_update_property_definitions(
    params: BulkUpdatePropertiesParams,
) -> list[PropertyDefinition]

Bulk-update property definitions in Lexicon.

PARAMETER	DESCRIPTION
`params`	Bulk update parameters containing a list of property updates (name + fields to change). TYPE: `BulkUpdatePropertiesParams`

RETURNS	DESCRIPTION
`list[PropertyDefinition]`	List of updated `PropertyDefinition` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
defs = ws.bulk_update_property_definitions(
    BulkUpdatePropertiesParams(properties=[
        BulkPropertyUpdate(
            name="plan_type",
            resource_type="User",
            display_name="Plan Type",
        ),
        BulkPropertyUpdate(
            name="$city",
            resource_type="Event",
            example_value="San Francisco",
        ),
    ])
)

Source code in src/mixpanel_headless/workspace.py

def bulk_update_property_definitions(
    self, params: BulkUpdatePropertiesParams
) -> list[PropertyDefinition]:
    """Bulk-update property definitions in Lexicon.

    Args:
        params: Bulk update parameters containing a list of property
            updates (name + fields to change).

    Returns:
        List of updated ``PropertyDefinition`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        defs = ws.bulk_update_property_definitions(
            BulkUpdatePropertiesParams(properties=[
                BulkPropertyUpdate(
                    name="plan_type",
                    resource_type="User",
                    display_name="Plan Type",
                ),
                BulkPropertyUpdate(
                    name="$city",
                    resource_type="Event",
                    example_value="San Francisco",
                ),
            ])
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True, by_alias=True)
    raw_list = client.bulk_update_property_definitions(body)
    return validate_response_models(
        PropertyDefinition, raw_list, endpoint="bulk_update_property_definitions"
    )

list_lexicon_tags ¶

list_lexicon_tags() -> list[LexiconTag]

List all Lexicon tags.

RETURNS	DESCRIPTION
`list[LexiconTag]`	List of `LexiconTag` objects with `id` and `name` fields.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
tags = ws.list_lexicon_tags()
for tag in tags:
    print(tag.name)

Note

The list endpoint may return plain tag name strings without IDs. In that case, id is set to 0 as a sentinel value. Do not pass this sentinel to update_lexicon_tag() — use name-based operations (e.g. delete_lexicon_tag(tag.name)) for tags obtained from this method.

Source code in src/mixpanel_headless/workspace.py

def list_lexicon_tags(self) -> list[LexiconTag]:
    """List all Lexicon tags.

    Returns:
        List of ``LexiconTag`` objects with ``id`` and ``name`` fields.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        tags = ws.list_lexicon_tags()
        for tag in tags:
            print(tag.name)
        ```

    Note:
        The list endpoint may return plain tag name strings without IDs.
        In that case, ``id`` is set to ``0`` as a sentinel value. Do not
        pass this sentinel to ``update_lexicon_tag()`` — use name-based
        operations (e.g. ``delete_lexicon_tag(tag.name)``) for tags
        obtained from this method.
    """
    client = self._require_api_client()
    raw_list = client.list_lexicon_tags()
    result: list[LexiconTag] = []
    for x in raw_list:
        if isinstance(x, str):
            # List endpoint returns plain tag name strings (no id);
            # id=0 is a sentinel — see docstring Note.
            result.append(LexiconTag(id=0, name=x))
        else:
            result.append(
                validate_response_model(LexiconTag, x, endpoint="list_lexicon_tags")
            )
    return result

create_lexicon_tag ¶

create_lexicon_tag(params: CreateTagParams) -> LexiconTag

Create a new Lexicon tag.

PARAMETER	DESCRIPTION
`params`	Tag creation parameters (name is required). TYPE: `CreateTagParams`

RETURNS	DESCRIPTION
`LexiconTag`	The created `LexiconTag`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400) or tag already exists.
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
tag = ws.create_lexicon_tag(CreateTagParams(name="core-events"))

Source code in src/mixpanel_headless/workspace.py

def create_lexicon_tag(self, params: CreateTagParams) -> LexiconTag:
    """Create a new Lexicon tag.

    Args:
        params: Tag creation parameters (name is required).

    Returns:
        The created ``LexiconTag``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400) or tag already exists.
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        tag = ws.create_lexicon_tag(CreateTagParams(name="core-events"))
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.create_lexicon_tag(body)
    return validate_response_model(LexiconTag, raw, endpoint="create_lexicon_tag")

update_lexicon_tag ¶

update_lexicon_tag(tag_id: int, params: UpdateTagParams) -> LexiconTag

Update a Lexicon tag.

PARAMETER	DESCRIPTION
`tag_id`	Tag ID (integer). TYPE: `int`
`params`	Fields to update (e.g. name). TYPE: `UpdateTagParams`

RETURNS	DESCRIPTION
`LexiconTag`	The updated `LexiconTag`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Tag not found (404) or validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
tag = ws.update_lexicon_tag(
    5, UpdateTagParams(name="renamed-tag")
)

Source code in src/mixpanel_headless/workspace.py

def update_lexicon_tag(self, tag_id: int, params: UpdateTagParams) -> LexiconTag:
    """Update a Lexicon tag.

    Args:
        tag_id: Tag ID (integer).
        params: Fields to update (e.g. name).

    Returns:
        The updated ``LexiconTag``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Tag not found (404) or validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        tag = ws.update_lexicon_tag(
            5, UpdateTagParams(name="renamed-tag")
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.update_lexicon_tag(tag_id, body)
    return validate_response_model(LexiconTag, raw, endpoint="update_lexicon_tag")

delete_lexicon_tag ¶

delete_lexicon_tag(tag_name: str) -> None

Delete a Lexicon tag by name.

PARAMETER	DESCRIPTION
`tag_name`	Name of the tag to delete. TYPE: `str`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Tag not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_lexicon_tag("deprecated-tag")

Source code in src/mixpanel_headless/workspace.py

def delete_lexicon_tag(self, tag_name: str) -> None:
    """Delete a Lexicon tag by name.

    Args:
        tag_name: Name of the tag to delete.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Tag not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_lexicon_tag("deprecated-tag")
        ```
    """
    client = self._require_api_client()
    client.delete_lexicon_tag(tag_name)

get_tracking_metadata ¶

get_tracking_metadata(event_name: str) -> dict[str, Any]

Get tracking metadata for an event.

Retrieves information about how an event is being tracked (sources, SDKs, volume, etc.).

PARAMETER	DESCRIPTION
`event_name`	Name of the event. TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	Raw tracking metadata dictionary.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Event not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
metadata = ws.get_tracking_metadata("Signup")
print(metadata)

Source code in src/mixpanel_headless/workspace.py

def get_tracking_metadata(self, event_name: str) -> dict[str, Any]:
    """Get tracking metadata for an event.

    Retrieves information about how an event is being tracked
    (sources, SDKs, volume, etc.).

    Args:
        event_name: Name of the event.

    Returns:
        Raw tracking metadata dictionary.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Event not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        metadata = ws.get_tracking_metadata("Signup")
        print(metadata)
        ```
    """
    client = self._require_api_client()
    return client.get_tracking_metadata(event_name)

get_event_history ¶

get_event_history(event_name: str) -> list[dict[str, Any]]

Get change history for an event definition.

PARAMETER	DESCRIPTION
`event_name`	Name of the event. TYPE: `str`

RETURNS	DESCRIPTION
`list[dict[str, Any]]`	List of history entries (raw dictionaries) showing changes
`list[dict[str, Any]]`	to the event definition over time.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Event not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
history = ws.get_event_history("Signup")
for entry in history:
    print(f"{entry['timestamp']}: {entry['action']}")

Source code in src/mixpanel_headless/workspace.py

def get_event_history(self, event_name: str) -> list[dict[str, Any]]:
    """Get change history for an event definition.

    Args:
        event_name: Name of the event.

    Returns:
        List of history entries (raw dictionaries) showing changes
        to the event definition over time.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Event not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        history = ws.get_event_history("Signup")
        for entry in history:
            print(f"{entry['timestamp']}: {entry['action']}")
        ```
    """
    client = self._require_api_client()
    return client.get_event_history(event_name)

get_property_history ¶

get_property_history(
    property_name: str, entity_type: str
) -> list[dict[str, Any]]

Get change history for a property definition.

PARAMETER	DESCRIPTION
`property_name`	Name of the property. TYPE: `str`
`entity_type`	Entity type (e.g. `"event"`, `"user"`, `"group"`). TYPE: `str`

RETURNS	DESCRIPTION
`list[dict[str, Any]]`	List of history entries (raw dictionaries) showing changes
`list[dict[str, Any]]`	to the property definition over time.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Property not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
history = ws.get_property_history("plan_type", "event")
for entry in history:
    print(f"{entry['timestamp']}: {entry['action']}")

Source code in src/mixpanel_headless/workspace.py

def get_property_history(
    self, property_name: str, entity_type: str
) -> list[dict[str, Any]]:
    """Get change history for a property definition.

    Args:
        property_name: Name of the property.
        entity_type: Entity type (e.g. ``"event"``, ``"user"``,
            ``"group"``).

    Returns:
        List of history entries (raw dictionaries) showing changes
        to the property definition over time.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Property not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        history = ws.get_property_history("plan_type", "event")
        for entry in history:
            print(f"{entry['timestamp']}: {entry['action']}")
        ```
    """
    client = self._require_api_client()
    return client.get_property_history(property_name, entity_type)

export_lexicon ¶

export_lexicon(*, export_types: list[str] | None = None) -> dict[str, Any]

Export Lexicon data definitions.

Exports event and property definitions from Lexicon, optionally filtered by type.

PARAMETER	DESCRIPTION
`export_types`	Optional list of types to export (e.g. `["All Events and Properties", "All User Profile Properties"]`). TYPE: `list[str] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`dict[str, Any]`	Raw export dictionary containing the exported definitions.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
export = ws.export_lexicon(
    export_types=["All Events and Properties"]
)
print(len(export.get("events", [])))

Source code in src/mixpanel_headless/workspace.py

def export_lexicon(
    self, *, export_types: list[str] | None = None
) -> dict[str, Any]:
    """Export Lexicon data definitions.

    Exports event and property definitions from Lexicon, optionally
    filtered by type.

    Args:
        export_types: Optional list of types to export (e.g.
            ``["All Events and Properties", "All User Profile Properties"]``).

    Returns:
        Raw export dictionary containing the exported definitions.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        export = ws.export_lexicon(
            export_types=["All Events and Properties"]
        )
        print(len(export.get("events", [])))
        ```
    """
    client = self._require_api_client()
    return client.export_lexicon(export_types=export_types)

list_drop_filters ¶

list_drop_filters() -> list[DropFilter]

List all drop filters.

RETURNS	DESCRIPTION
`list[DropFilter]`	List of `DropFilter` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
filters = ws.list_drop_filters()
for f in filters:
    print(f"{f.event_name}: active={f.active}")

Source code in src/mixpanel_headless/workspace.py

def list_drop_filters(self) -> list[DropFilter]:
    """List all drop filters.

    Returns:
        List of ``DropFilter`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        filters = ws.list_drop_filters()
        for f in filters:
            print(f"{f.event_name}: active={f.active}")
        ```
    """
    client = self._require_api_client()
    raw_list = client.list_drop_filters()
    return validate_response_models(
        DropFilter, raw_list, endpoint="list_drop_filters"
    )

create_drop_filter ¶

create_drop_filter(params: CreateDropFilterParams) -> list[DropFilter]

Create a new drop filter.

PARAMETER	DESCRIPTION
`params`	Drop filter creation parameters. TYPE: `CreateDropFilterParams`

RETURNS	DESCRIPTION
`list[DropFilter]`	Full list of `DropFilter` objects after creation.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
filters = ws.create_drop_filter(
    CreateDropFilterParams(
        event_name="Debug Event",
        filters={"property": "env", "value": "test"},
    )
)

Source code in src/mixpanel_headless/workspace.py

def create_drop_filter(self, params: CreateDropFilterParams) -> list[DropFilter]:
    """Create a new drop filter.

    Args:
        params: Drop filter creation parameters.

    Returns:
        Full list of ``DropFilter`` objects after creation.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        filters = ws.create_drop_filter(
            CreateDropFilterParams(
                event_name="Debug Event",
                filters={"property": "env", "value": "test"},
            )
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw_list = client.create_drop_filter(body)
    return validate_response_models(
        DropFilter, raw_list, endpoint="create_drop_filter"
    )

update_drop_filter ¶

update_drop_filter(params: UpdateDropFilterParams) -> list[DropFilter]

Update a drop filter.

PARAMETER	DESCRIPTION
`params`	Drop filter update parameters (must include the filter ID). TYPE: `UpdateDropFilterParams`

RETURNS	DESCRIPTION
`list[DropFilter]`	Full list of `DropFilter` objects after update.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Filter not found (404) or validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
filters = ws.update_drop_filter(
    UpdateDropFilterParams(
        id=42, event_name="Debug Event v2"
    )
)

Source code in src/mixpanel_headless/workspace.py

def update_drop_filter(self, params: UpdateDropFilterParams) -> list[DropFilter]:
    """Update a drop filter.

    Args:
        params: Drop filter update parameters (must include the filter ID).

    Returns:
        Full list of ``DropFilter`` objects after update.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Filter not found (404) or validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        filters = ws.update_drop_filter(
            UpdateDropFilterParams(
                id=42, event_name="Debug Event v2"
            )
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw_list = client.update_drop_filter(body)
    return validate_response_models(
        DropFilter, raw_list, endpoint="update_drop_filter"
    )

delete_drop_filter ¶

delete_drop_filter(drop_filter_id: int) -> list[DropFilter]

Delete a drop filter.

PARAMETER	DESCRIPTION
`drop_filter_id`	Drop filter ID (integer). TYPE: `int`

RETURNS	DESCRIPTION
`list[DropFilter]`	Full list of remaining `DropFilter` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Filter not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
remaining = ws.delete_drop_filter(42)

Source code in src/mixpanel_headless/workspace.py

def delete_drop_filter(self, drop_filter_id: int) -> list[DropFilter]:
    """Delete a drop filter.

    Args:
        drop_filter_id: Drop filter ID (integer).

    Returns:
        Full list of remaining ``DropFilter`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Filter not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        remaining = ws.delete_drop_filter(42)
        ```
    """
    client = self._require_api_client()
    raw_list = client.delete_drop_filter(drop_filter_id)
    return validate_response_models(
        DropFilter, raw_list, endpoint="delete_drop_filter"
    )

get_drop_filter_limits ¶

get_drop_filter_limits() -> DropFilterLimitsResponse

Get drop filter usage limits.

RETURNS	DESCRIPTION
`DropFilterLimitsResponse`	`DropFilterLimitsResponse` with the maximum allowed
`DropFilterLimitsResponse`	drop filters for the project.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
limits = ws.get_drop_filter_limits()
print(f"Drop filter limit: {limits.filter_limit}")

Source code in src/mixpanel_headless/workspace.py

def get_drop_filter_limits(self) -> DropFilterLimitsResponse:
    """Get drop filter usage limits.

    Returns:
        ``DropFilterLimitsResponse`` with the maximum allowed
        drop filters for the project.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        limits = ws.get_drop_filter_limits()
        print(f"Drop filter limit: {limits.filter_limit}")
        ```
    """
    client = self._require_api_client()
    raw = client.get_drop_filter_limits()
    return validate_response_model(
        DropFilterLimitsResponse, raw, endpoint="get_drop_filter_limits"
    )

list_custom_properties ¶

list_custom_properties() -> list[CustomProperty]

List all custom properties.

RETURNS	DESCRIPTION
`list[CustomProperty]`	List of `CustomProperty` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Server-side data corruption (e.g. invalid `displayFormula` on a custom property).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
props = ws.list_custom_properties()
for p in props:
    print(f"{p.name}: {p.display_formula}")

Source code in src/mixpanel_headless/workspace.py

def list_custom_properties(self) -> list[CustomProperty]:
    """List all custom properties.

    Returns:
        List of ``CustomProperty`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Server-side data corruption (e.g. invalid
            ``displayFormula`` on a custom property).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        props = ws.list_custom_properties()
        for p in props:
            print(f"{p.name}: {p.display_formula}")
        ```
    """
    client = self._require_api_client()
    try:
        raw_list = client.list_custom_properties()
    except QueryError as exc:
        # Detect server-side data corruption: the API fails to serialize
        # when a custom property has an invalid displayFormula.
        details = exc.details if isinstance(exc.details, dict) else {}
        body = details.get("response_body", {}) if isinstance(details, dict) else {}
        if isinstance(body, dict) and body.get("field") == "displayFormula":
            raise QueryError(
                "list_custom_properties() failed: the project contains a "
                "custom property with an invalid displayFormula "
                "(server-side data corruption). Use "
                "get_custom_property(id) to retrieve individual "
                "properties, or contact Mixpanel support.",
                status_code=exc.status_code,
                response_body=exc.response_body,
                request_method=exc.request_method,
                request_url=exc.request_url,
                request_params=exc.request_params,
            ) from exc
        raise
    return validate_response_models(
        CustomProperty, raw_list, endpoint="list_custom_properties"
    )

create_custom_property ¶

create_custom_property(params: CreateCustomPropertyParams) -> CustomProperty

Create a new custom property.

PARAMETER	DESCRIPTION
`params`	Custom property creation parameters (name, display_formula or behavior, resource_type are required). TYPE: `CreateCustomPropertyParams`

RETURNS	DESCRIPTION
`CustomProperty`	The created `CustomProperty`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
prop = ws.create_custom_property(
    CreateCustomPropertyParams(
        name="Full Name",
        display_formula='concat(properties["first"], " ", properties["last"])',
        composed_properties={"first": ComposedPropertyValue(resource_type="event"), "last": ComposedPropertyValue(resource_type="event")},
        resource_type="event",
    )
)

Source code in src/mixpanel_headless/workspace.py

def create_custom_property(
    self, params: CreateCustomPropertyParams
) -> CustomProperty:
    """Create a new custom property.

    Args:
        params: Custom property creation parameters (name,
            display_formula or behavior, resource_type are required).

    Returns:
        The created ``CustomProperty``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        prop = ws.create_custom_property(
            CreateCustomPropertyParams(
                name="Full Name",
                display_formula='concat(properties["first"], " ", properties["last"])',
                composed_properties={"first": ComposedPropertyValue(resource_type="event"), "last": ComposedPropertyValue(resource_type="event")},
                resource_type="event",
            )
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True, by_alias=True, mode="json")
    raw = client.create_custom_property(body)
    return validate_response_model(
        CustomProperty, raw, endpoint="create_custom_property"
    )

get_custom_property ¶

get_custom_property(property_id: str) -> CustomProperty

Get a custom property by ID.

PARAMETER	DESCRIPTION
`property_id`	Custom property ID (string). TYPE: `str`

RETURNS	DESCRIPTION
`CustomProperty`	The `CustomProperty` object.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Property not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
prop = ws.get_custom_property("abc123")
print(prop.name)

Source code in src/mixpanel_headless/workspace.py

def get_custom_property(self, property_id: str) -> CustomProperty:
    """Get a custom property by ID.

    Args:
        property_id: Custom property ID (string).

    Returns:
        The ``CustomProperty`` object.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Property not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        prop = ws.get_custom_property("abc123")
        print(prop.name)
        ```
    """
    client = self._require_api_client()
    raw = client.get_custom_property(property_id)
    return validate_response_model(
        CustomProperty, raw, endpoint="get_custom_property"
    )

update_custom_property ¶

update_custom_property(
    property_id: str, params: UpdateCustomPropertyParams
) -> CustomProperty

Update a custom property.

PARAMETER	DESCRIPTION
`property_id`	Custom property ID (string). TYPE: `str`
`params`	Fields to update. TYPE: `UpdateCustomPropertyParams`

RETURNS	DESCRIPTION
`CustomProperty`	The updated `CustomProperty`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Property not found (404) or validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
prop = ws.update_custom_property(
    "abc123",
    UpdateCustomPropertyParams(name="Renamed Property"),
)

Source code in src/mixpanel_headless/workspace.py

def update_custom_property(
    self, property_id: str, params: UpdateCustomPropertyParams
) -> CustomProperty:
    """Update a custom property.

    Args:
        property_id: Custom property ID (string).
        params: Fields to update.

    Returns:
        The updated ``CustomProperty``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Property not found (404) or validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        prop = ws.update_custom_property(
            "abc123",
            UpdateCustomPropertyParams(name="Renamed Property"),
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True, by_alias=True)
    raw = client.update_custom_property(property_id, body)
    return validate_response_model(
        CustomProperty, raw, endpoint="update_custom_property"
    )

delete_custom_property ¶

delete_custom_property(property_id: str) -> None

Delete a custom property.

PARAMETER	DESCRIPTION
`property_id`	Custom property ID (string). TYPE: `str`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Property not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_custom_property("abc123")

Source code in src/mixpanel_headless/workspace.py

def delete_custom_property(self, property_id: str) -> None:
    """Delete a custom property.

    Args:
        property_id: Custom property ID (string).

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Property not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_custom_property("abc123")
        ```
    """
    client = self._require_api_client()
    client.delete_custom_property(property_id)

validate_custom_property ¶

validate_custom_property(params: CreateCustomPropertyParams) -> dict[str, Any]

Validate a custom property definition without creating it.

PARAMETER	DESCRIPTION
`params`	Custom property parameters to validate. TYPE: `CreateCustomPropertyParams`

RETURNS	DESCRIPTION
`dict[str, Any]`	Validation result as a raw dictionary.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
result = ws.validate_custom_property(
    CreateCustomPropertyParams(
        name="Full Name",
        display_formula='concat(properties["first"], " ", properties["last"])',
        composed_properties={"first": ComposedPropertyValue(resource_type="event"), "last": ComposedPropertyValue(resource_type="event")},
        resource_type="event",
    )
)
print(result)

Source code in src/mixpanel_headless/workspace.py

def validate_custom_property(
    self, params: CreateCustomPropertyParams
) -> dict[str, Any]:
    """Validate a custom property definition without creating it.

    Args:
        params: Custom property parameters to validate.

    Returns:
        Validation result as a raw dictionary.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        result = ws.validate_custom_property(
            CreateCustomPropertyParams(
                name="Full Name",
                display_formula='concat(properties["first"], " ", properties["last"])',
                composed_properties={"first": ComposedPropertyValue(resource_type="event"), "last": ComposedPropertyValue(resource_type="event")},
                resource_type="event",
            )
        )
        print(result)
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True, by_alias=True)
    return client.validate_custom_property(body)

list_lookup_tables ¶

list_lookup_tables(*, data_group_id: int | None = None) -> list[LookupTable]

List lookup tables.

PARAMETER	DESCRIPTION
`data_group_id`	Optional filter by data group ID. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[LookupTable]`	List of `LookupTable` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
tables = ws.list_lookup_tables()
for t in tables:
    print(f"{t.name} (mapped={t.has_mapped_properties})")

Source code in src/mixpanel_headless/workspace.py

def list_lookup_tables(
    self, *, data_group_id: int | None = None
) -> list[LookupTable]:
    """List lookup tables.

    Args:
        data_group_id: Optional filter by data group ID.

    Returns:
        List of ``LookupTable`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        tables = ws.list_lookup_tables()
        for t in tables:
            print(f"{t.name} (mapped={t.has_mapped_properties})")
        ```
    """
    client = self._require_api_client()
    raw_list = client.list_lookup_tables(data_group_id=data_group_id)
    return validate_response_models(
        LookupTable, raw_list, endpoint="list_lookup_tables"
    )

upload_lookup_table ¶

upload_lookup_table(
    params: UploadLookupTableParams,
    *,
    poll_interval: float = 2.0,
    max_poll_seconds: float = 300.0,
) -> LookupTable

Upload a CSV file as a new lookup table.

Performs a 3-step upload process: 1. Obtains a signed upload URL from the API. 2. Uploads the CSV file to the signed URL. 3. Registers the lookup table with the uploaded data.

For files >= 5 MB, the API processes the upload asynchronously. This method automatically polls until processing completes.

PARAMETER	DESCRIPTION
`params`	Upload parameters including `name`, `file_path` (path to the CSV file), and optional `data_group_id`. TYPE: `UploadLookupTableParams`
`poll_interval`	Seconds between status polls for async uploads. TYPE: `float` DEFAULT: `2.0`
`max_poll_seconds`	Maximum seconds to wait for async processing. TYPE: `float` DEFAULT: `300.0`

RETURNS	DESCRIPTION
`LookupTable`	The created `LookupTable` object.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400) or file not found.
`ServerError`	Server-side errors (5xx).
`FileNotFoundError`	If the CSV file does not exist.
`MixpanelHeadlessError`	Async processing timed out or failed.

Example

ws = Workspace()
table = ws.upload_lookup_table(
    UploadLookupTableParams(
        name="Country Codes",
        file_path="/path/to/countries.csv",
    )
)
print(f"Created: {table.name}")

Source code in src/mixpanel_headless/workspace.py

def upload_lookup_table(
    self,
    params: UploadLookupTableParams,
    *,
    poll_interval: float = 2.0,
    max_poll_seconds: float = 300.0,
) -> LookupTable:
    """Upload a CSV file as a new lookup table.

    Performs a 3-step upload process:
    1. Obtains a signed upload URL from the API.
    2. Uploads the CSV file to the signed URL.
    3. Registers the lookup table with the uploaded data.

    For files >= 5 MB, the API processes the upload asynchronously.
    This method automatically polls until processing completes.

    Args:
        params: Upload parameters including ``name``, ``file_path``
            (path to the CSV file), and optional ``data_group_id``.
        poll_interval: Seconds between status polls for async uploads.
        max_poll_seconds: Maximum seconds to wait for async processing.

    Returns:
        The created ``LookupTable`` object.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400) or file not found.
        ServerError: Server-side errors (5xx).
        FileNotFoundError: If the CSV file does not exist.
        MixpanelHeadlessError: Async processing timed out or failed.

    Example:
        ```python
        ws = Workspace()
        table = ws.upload_lookup_table(
            UploadLookupTableParams(
                name="Country Codes",
                file_path="/path/to/countries.csv",
            )
        )
        print(f"Created: {table.name}")
        ```
    """
    client = self._require_api_client()
    logger = logging.getLogger(__name__)

    # Step 1: Get signed upload URL
    url_info = client.get_lookup_upload_url()

    # Step 2: Read and upload the CSV file
    csv_bytes = Path(params.file_path).read_bytes()
    client.upload_to_signed_url(url_info["url"], csv_bytes)

    # Step 3: Register the lookup table
    form_data: dict[str, str] = {
        "name": params.name,
        "path": url_info["path"],
        "key": url_info["key"],
    }
    if params.data_group_id is not None:
        form_data["data-group-id"] = str(params.data_group_id)

    raw = client.register_lookup_table(form_data)

    # The API returns {"uploadId": "..."} for files >= 5 MB,
    # indicating async processing via Celery.
    upload_id = raw.get("uploadId") if isinstance(raw, dict) else None
    if upload_id is not None:
        logger.info(
            "Lookup table upload is processing asynchronously "
            "(uploadId=%s), polling for completion...",
            upload_id,
        )
        raw = self._poll_lookup_upload(
            client, upload_id, poll_interval, max_poll_seconds
        )

    # Upload response may only contain {'id': '...'} without 'name';
    # inject the name from params so LookupTable validation succeeds.
    if isinstance(raw, dict) and "name" not in raw:
        raw = {**raw, "name": params.name}
    return validate_response_model(LookupTable, raw, endpoint="upload_lookup_table")

mark_lookup_table_ready ¶

mark_lookup_table_ready(params: MarkLookupTableReadyParams) -> LookupTable

Mark a lookup table as ready after upload.

PARAMETER	DESCRIPTION
`params`	Parameters including `name`, `key`, and optional `data_group_id`. TYPE: `MarkLookupTableReadyParams`

RETURNS	DESCRIPTION
`LookupTable`	The updated `LookupTable`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
table = ws.mark_lookup_table_ready(
    MarkLookupTableReadyParams(
        name="Country Codes",
        key="uploads/abc123.csv",
    )
)

Source code in src/mixpanel_headless/workspace.py

def mark_lookup_table_ready(
    self, params: MarkLookupTableReadyParams
) -> LookupTable:
    """Mark a lookup table as ready after upload.

    Args:
        params: Parameters including ``name``, ``key``, and optional
            ``data_group_id``.

    Returns:
        The updated ``LookupTable``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        table = ws.mark_lookup_table_ready(
            MarkLookupTableReadyParams(
                name="Country Codes",
                key="uploads/abc123.csv",
            )
        )
        ```
    """
    client = self._require_api_client()
    form_data: dict[str, str] = {
        "name": params.name,
        "key": params.key,
    }
    if params.data_group_id is not None:
        form_data["data-group-id"] = str(params.data_group_id)

    raw = client.mark_lookup_table_ready(form_data)
    return validate_response_model(
        LookupTable, raw, endpoint="mark_lookup_table_ready"
    )

get_lookup_upload_url ¶

get_lookup_upload_url(content_type: str = 'text/csv') -> LookupTableUploadUrl

Get a signed URL for uploading lookup table data.

PARAMETER	DESCRIPTION
`content_type`	MIME type of the file to upload (default: `"text/csv"`). TYPE: `str` DEFAULT: `'text/csv'`

RETURNS	DESCRIPTION
`LookupTableUploadUrl`	`LookupTableUploadUrl` with the signed URL, path, and key.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
url_info = ws.get_lookup_upload_url()
print(url_info.url)

Source code in src/mixpanel_headless/workspace.py

def get_lookup_upload_url(
    self, content_type: str = "text/csv"
) -> LookupTableUploadUrl:
    """Get a signed URL for uploading lookup table data.

    Args:
        content_type: MIME type of the file to upload
            (default: ``"text/csv"``).

    Returns:
        ``LookupTableUploadUrl`` with the signed URL, path, and key.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        url_info = ws.get_lookup_upload_url()
        print(url_info.url)
        ```
    """
    client = self._require_api_client()
    raw = client.get_lookup_upload_url(content_type)
    return validate_response_model(
        LookupTableUploadUrl, raw, endpoint="get_lookup_upload_url"
    )

get_lookup_upload_status ¶

get_lookup_upload_status(upload_id: str) -> dict[str, Any]

Get the processing status of a lookup table upload.

PARAMETER	DESCRIPTION
`upload_id`	Upload ID returned from the upload process. TYPE: `str`

RETURNS	DESCRIPTION
`dict[str, Any]`	Raw status dictionary with processing details.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Upload not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
status = ws.get_lookup_upload_status("upload-abc123")
print(status["state"])

Source code in src/mixpanel_headless/workspace.py

def get_lookup_upload_status(self, upload_id: str) -> dict[str, Any]:
    """Get the processing status of a lookup table upload.

    Args:
        upload_id: Upload ID returned from the upload process.

    Returns:
        Raw status dictionary with processing details.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Upload not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        status = ws.get_lookup_upload_status("upload-abc123")
        print(status["state"])
        ```
    """
    client = self._require_api_client()
    return client.get_lookup_upload_status(upload_id)

update_lookup_table ¶

update_lookup_table(
    data_group_id: int, params: UpdateLookupTableParams
) -> LookupTable

Update a lookup table.

PARAMETER	DESCRIPTION
`data_group_id`	Data group ID of the lookup table. TYPE: `int`
`params`	Fields to update. TYPE: `UpdateLookupTableParams`

RETURNS	DESCRIPTION
`LookupTable`	The updated `LookupTable`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Table not found (404) or validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
table = ws.update_lookup_table(
    123,
    UpdateLookupTableParams(name="Renamed Table"),
)

Source code in src/mixpanel_headless/workspace.py

def update_lookup_table(
    self, data_group_id: int, params: UpdateLookupTableParams
) -> LookupTable:
    """Update a lookup table.

    Args:
        data_group_id: Data group ID of the lookup table.
        params: Fields to update.

    Returns:
        The updated ``LookupTable``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Table not found (404) or validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        table = ws.update_lookup_table(
            123,
            UpdateLookupTableParams(name="Renamed Table"),
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True)
    raw = client.update_lookup_table(data_group_id, body)
    return validate_response_model(LookupTable, raw, endpoint="update_lookup_table")

delete_lookup_tables ¶

delete_lookup_tables(data_group_ids: list[int]) -> None

Delete one or more lookup tables.

PARAMETER	DESCRIPTION
`data_group_ids`	List of data group IDs to delete. TYPE: `list[int]`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_lookup_tables([123, 456])

Source code in src/mixpanel_headless/workspace.py

def delete_lookup_tables(self, data_group_ids: list[int]) -> None:
    """Delete one or more lookup tables.

    Args:
        data_group_ids: List of data group IDs to delete.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_lookup_tables([123, 456])
        ```
    """
    client = self._require_api_client()
    client.delete_lookup_tables(data_group_ids)

download_lookup_table ¶

download_lookup_table(
    data_group_id: int,
    *,
    file_name: str | None = None,
    limit: int | None = None,
) -> bytes

Download lookup table data as raw bytes (CSV).

PARAMETER	DESCRIPTION
`data_group_id`	Data group ID of the lookup table. TYPE: `int`
`file_name`	Optional file name filter. TYPE: `str \| None` DEFAULT: `None`
`limit`	Optional row limit. TYPE: `int \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bytes`	Raw CSV bytes of the lookup table data.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Table not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
csv_data = ws.download_lookup_table(123)
Path("output.csv").write_bytes(csv_data)

Source code in src/mixpanel_headless/workspace.py

def download_lookup_table(
    self,
    data_group_id: int,
    *,
    file_name: str | None = None,
    limit: int | None = None,
) -> bytes:
    """Download lookup table data as raw bytes (CSV).

    Args:
        data_group_id: Data group ID of the lookup table.
        file_name: Optional file name filter.
        limit: Optional row limit.

    Returns:
        Raw CSV bytes of the lookup table data.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Table not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        csv_data = ws.download_lookup_table(123)
        Path("output.csv").write_bytes(csv_data)
        ```
    """
    client = self._require_api_client()
    return client.download_lookup_table(
        data_group_id, file_name=file_name, limit=limit
    )

get_lookup_download_url ¶

get_lookup_download_url(data_group_id: int) -> str

Get a signed download URL for a lookup table.

PARAMETER	DESCRIPTION
`data_group_id`	Data group ID of the lookup table. TYPE: `int`

RETURNS	DESCRIPTION
`str`	Signed URL string for downloading the lookup table data.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Table not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
url = ws.get_lookup_download_url(123)
print(url)

Source code in src/mixpanel_headless/workspace.py

def get_lookup_download_url(self, data_group_id: int) -> str:
    """Get a signed download URL for a lookup table.

    Args:
        data_group_id: Data group ID of the lookup table.

    Returns:
        Signed URL string for downloading the lookup table data.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Table not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        url = ws.get_lookup_download_url(123)
        print(url)
        ```
    """
    client = self._require_api_client()
    return client.get_lookup_download_url(data_group_id)

list_custom_events ¶

list_custom_events() -> list[EventDefinition]

List all custom events.

RETURNS	DESCRIPTION
`list[EventDefinition]`	List of `EventDefinition` objects for custom events.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
events = ws.list_custom_events()
for e in events:
    print(e.name)

Source code in src/mixpanel_headless/workspace.py

def list_custom_events(self) -> list[EventDefinition]:
    """List all custom events.

    Returns:
        List of ``EventDefinition`` objects for custom events.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        events = ws.list_custom_events()
        for e in events:
            print(e.name)
        ```
    """
    client = self._require_api_client()
    raw_list = client.list_custom_events()
    return validate_response_models(
        EventDefinition, raw_list, endpoint="list_custom_events"
    )

update_custom_event ¶

update_custom_event(
    custom_event_id: int, params: UpdateEventDefinitionParams
) -> EventDefinition

Update a custom event's lexicon entry (description, tags, etc.).

The Mixpanel data-definitions/events/ endpoint matches updates by the most specific identifier; for custom events that's the customEventId. This SDK method requires the id (rather than the display name) to avoid creating orphan lexicon entries — passing a name alone causes the server to fabricate a new, unlinked entry.

Get the id from :meth:create_custom_event's return value (CustomEvent.id) or from the custom_event_id field on entries returned by :meth:list_custom_events.

PARAMETER	DESCRIPTION
`custom_event_id`	Server-assigned custom event ID. TYPE: `int`
`params`	Fields to update. See :class:`UpdateEventDefinitionParams` for the full list of supported fields. TYPE: `UpdateEventDefinitionParams`

RETURNS	DESCRIPTION
`EventDefinition`	The updated `EventDefinition` (lexicon view of the custom
`EventDefinition`	event, with `custom_event_id` populated).

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Event not found (404) or validation error (400).
`ServerError`	Server-side errors (5xx).
`MixpanelHeadlessError`	Server returned an entry with a different `customEventId` than requested (`code="UPDATE_TARGET_MISMATCH"`).

Example

ws = Workspace()
ce = ws.create_custom_event(CreateCustomEventParams(
    name="Metric Tree Opened", alternatives=["Enter room"],
))
event = ws.update_custom_event(
    ce.id,
    UpdateEventDefinitionParams(
        description="Fires when a user opens a metric tree canvas.",
        verified=True,
    ),
)

Source code in src/mixpanel_headless/workspace.py

def update_custom_event(
    self, custom_event_id: int, params: UpdateEventDefinitionParams
) -> EventDefinition:
    """Update a custom event's lexicon entry (description, tags, etc.).

    The Mixpanel ``data-definitions/events/`` endpoint matches updates by
    the most specific identifier; for custom events that's the
    ``customEventId``. This SDK method requires the id (rather than the
    display name) to avoid creating orphan lexicon entries — passing a
    name alone causes the server to fabricate a new, unlinked entry.

    Get the id from :meth:`create_custom_event`'s return value
    (``CustomEvent.id``) or from the ``custom_event_id`` field on entries
    returned by :meth:`list_custom_events`.

    Args:
        custom_event_id: Server-assigned custom event ID.
        params: Fields to update. See
            :class:`UpdateEventDefinitionParams` for the full list of
            supported fields.

    Returns:
        The updated ``EventDefinition`` (lexicon view of the custom
        event, with ``custom_event_id`` populated).

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Event not found (404) or validation error (400).
        ServerError: Server-side errors (5xx).
        MixpanelHeadlessError: Server returned an entry with a different
            ``customEventId`` than requested
            (``code="UPDATE_TARGET_MISMATCH"``).

    Example:
        ```python
        ws = Workspace()
        ce = ws.create_custom_event(CreateCustomEventParams(
            name="Metric Tree Opened", alternatives=["Enter room"],
        ))
        event = ws.update_custom_event(
            ce.id,
            UpdateEventDefinitionParams(
                description="Fires when a user opens a metric tree canvas.",
                verified=True,
            ),
        )
        ```
    """
    client = self._require_api_client()
    body = params.model_dump(exclude_none=True, by_alias=True)
    raw = client.update_custom_event(custom_event_id, body)
    return validate_response_model(
        EventDefinition, raw, endpoint="update_custom_event"
    )

delete_custom_event ¶

delete_custom_event(custom_event_id: int) -> None

Delete a custom event.

Identifies the entry by custom_event_id (not name) for the same reason :meth:update_custom_event does: a name-only DELETE against the data-definitions endpoint is ambiguous when multiple entries share a display name and may silently delete the wrong row, an auto-derived orphan lexicon entry, or no-op while still reporting success.

Get the id from :meth:create_custom_event's return value (CustomEvent.id) or from the custom_event_id field on entries returned by :meth:list_custom_events.

PARAMETER	DESCRIPTION
`custom_event_id`	Server-assigned custom event ID. TYPE: `int`

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Event not found (404).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_custom_event(42)

Source code in src/mixpanel_headless/workspace.py

def delete_custom_event(self, custom_event_id: int) -> None:
    """Delete a custom event.

    Identifies the entry by ``custom_event_id`` (not name) for the
    same reason :meth:`update_custom_event` does: a name-only DELETE
    against the data-definitions endpoint is ambiguous when multiple
    entries share a display name and may silently delete the wrong row,
    an auto-derived orphan lexicon entry, or no-op while still
    reporting success.

    Get the id from :meth:`create_custom_event`'s return value
    (``CustomEvent.id``) or from the ``custom_event_id`` field on
    entries returned by :meth:`list_custom_events`.

    Args:
        custom_event_id: Server-assigned custom event ID.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Event not found (404).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_custom_event(42)
        ```
    """
    client = self._require_api_client()
    client.delete_custom_event(custom_event_id)

list_metrics ¶

list_metrics(
    *,
    metric_type: str | None = None,
    verified: bool | None = None,
    name_contains: str | None = None,
    viewable_only: bool = False,
) -> list[SavedMetric]

List saved metrics: behavior metrics, formulas, and warehouse metrics.

Returns what the server returns, which includes metrics that the caller cannot view (can_view is False, but the definition is complete). The server has no pagination, filters, or search, so one request fetches every active metric, and the filters below apply locally to that response. On a large project the request can take more than 30 seconds; the read timeout is at least 120 seconds.

PARAMETER	DESCRIPTION
`metric_type`	Keep only metrics of this kind: `"metric"` (a behavior metric), `"formula"`, `"warehouse"`, or the legacy `"behavior"`. Exact match. TYPE: `str \| None` DEFAULT: `None`
`verified`	`True` keeps verified metrics; `False` keeps unverified metrics. `None` (default) keeps both. TYPE: `bool \| None` DEFAULT: `None`
`name_contains`	Keep only metrics whose name contains this text, ignoring case. TYPE: `str \| None` DEFAULT: `None`
`viewable_only`	Drop the metrics that the server marks `can_view: false` for the caller, as the web app does. Rows without a `can_view` flag are kept. Default False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`list[SavedMetric]`	`SavedMetric` objects in server order.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The caller lacks the metrics permission or scope (403).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
for metric in ws.list_metrics(verified=True, viewable_only=True):
    print(metric.id, metric.type, metric.name)

formulas = ws.list_metrics(metric_type="formula", name_contains="rate")

Source code in src/mixpanel_headless/workspace.py

def list_metrics(
    self,
    *,
    metric_type: str | None = None,
    verified: bool | None = None,
    name_contains: str | None = None,
    viewable_only: bool = False,
) -> list[SavedMetric]:
    """List saved metrics: behavior metrics, formulas, and warehouse metrics.

    Returns what the server returns, which includes metrics that the
    caller cannot view (``can_view`` is False, but the definition is
    complete). The server has no pagination, filters, or search, so one
    request fetches every active metric, and the filters below apply
    locally to that response. On a large project the request can take
    more than 30 seconds; the read timeout is at least 120 seconds.

    Args:
        metric_type: Keep only metrics of this kind: ``"metric"`` (a
            behavior metric), ``"formula"``, ``"warehouse"``, or the
            legacy ``"behavior"``. Exact match.
        verified: ``True`` keeps verified metrics; ``False`` keeps
            unverified metrics. ``None`` (default) keeps both.
        name_contains: Keep only metrics whose name contains this text,
            ignoring case.
        viewable_only: Drop the metrics that the server marks
            ``can_view: false`` for the caller, as the web app does.
            Rows without a ``can_view`` flag are kept. Default False.

    Returns:
        ``SavedMetric`` objects in server order.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The caller lacks the metrics permission or scope (403).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        for metric in ws.list_metrics(verified=True, viewable_only=True):
            print(metric.id, metric.type, metric.name)

        formulas = ws.list_metrics(metric_type="formula", name_contains="rate")
        ```
    """
    client = self._require_api_client()
    metrics = validate_response_models(
        SavedMetric, client.list_metrics(), endpoint="list_metrics"
    )
    if metric_type is not None:
        metrics = [m for m in metrics if m.type == metric_type]
    if verified is not None:
        metrics = [m for m in metrics if m.verified is verified]
    if name_contains is not None:
        needle = name_contains.casefold()
        metrics = [m for m in metrics if needle in m.name.casefold()]
    if viewable_only:
        metrics = [m for m in metrics if m.can_view is not False]
    return metrics

get_metric ¶

get_metric(metric_id: int) -> SavedMetric

Get one saved metric by id, with its full definition.

PARAMETER	DESCRIPTION
`metric_id`	The saved metric id. TYPE: `int`

RETURNS	DESCRIPTION
`SavedMetric`	The `SavedMetric`. Its typed accessors (`math`,
`SavedMetric`	`formula_expression`, `referenced_metric_ids`, `display`,
`SavedMetric`	`goals`) read the definition.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The metric does not exist or is deleted (404), or the caller lacks permission (403).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
metric = ws.get_metric(104700)
print(metric.type, metric.math, metric.definition)

Source code in src/mixpanel_headless/workspace.py

def get_metric(self, metric_id: int) -> SavedMetric:
    """Get one saved metric by id, with its full definition.

    Args:
        metric_id: The saved metric id.

    Returns:
        The ``SavedMetric``. Its typed accessors (``math``,
        ``formula_expression``, ``referenced_metric_ids``, ``display``,
        ``goals``) read the definition.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The metric does not exist or is deleted (404), or the
            caller lacks permission (403).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        metric = ws.get_metric(104700)
        print(metric.type, metric.math, metric.definition)
        ```
    """
    client = self._require_api_client()
    return validate_response_model(
        SavedMetric, client.get_metric(metric_id), endpoint="get_metric"
    )

create_metric ¶

create_metric(
    params: CreateMetricParams, *, validate: bool = True
) -> SavedMetric

Create a saved metric from a typed or raw definition.

The kind comes from the definition: a Metric, CohortMetric, FunnelMetric, or RetentionMetric gives a behavior metric, a Formula with its own operands gives a saved formula, a WarehouseMetric gives a warehouse metric, and a RawMetricDefinition gives the kind it names. A behavior metric saves the behavior and measurement that :meth:query writes for the same value, and a saved formula holds the operands that a query formula holds, so the saved metric queries the same way as its inline twin.

Stored definitions can carry legacy keys (for example a behavior filter, or the id and type of a measurement) that the server reads past at query time but refuses on a create. So the method removes them from a RawMetricDefinition, with or without validate, and a copy of a stored metric works. A definition compiled from a typed value never has one; if it does, the method refuses it (SM4_SCHEMA).

Before any request, the method checks the name and description and the definition (see Raises). Then it sends the create. The server drops owned_by and verified from a create, so when the params set an owner or verified=True, a second request (an update) sets them. The two requests are not atomic: if the second one fails, the metric exists without the owner or the verified flag, and the method raises an error that names the id of the created metric (see Raises).

In a project with sharing on, a new metric is private to its creator; this API cannot share it.

PARAMETER	DESCRIPTION
`params`	Name, definition, and optional description, display, goals, owner, and verified flag. TYPE: `CreateMetricParams`
`validate`	Check the definition with the mirror of the server schema before the request (default), including the refusal of legacy keys in a compiled definition. `False` sends it without the check (a raw definition still loses its legacy keys); the server still checks a create and answers a failing definition with a 400 (`QueryError`). TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`SavedMetric`	The created `SavedMetric` (after the second request, when one
`SavedMetric`	was needed).

RAISES	DESCRIPTION
`ParamValidationError`	Before any request: an empty name (`SM1_EMPTY_NAME`); a name or description longer than 255 characters, which the server fails with a 500 (`SM2_NAME_TOO_LONG`); a definition that fails the schema mirror, or a warehouse definition without a source (`SM4_SCHEMA`); a saved formula whose operands use segment method or attribution (`FM6_OPERAND_ATTRIBUTION`); a `Formula` without operands (`SM7_FORMULA_WITHOUT_OPERANDS`).
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The server refused the body (400; the message names the failure and its schema location, and `response_body` holds the full server body); the pricing-plan gate ("Cannot save metric with your current plan"), a missing permission, or an unknown warehouse source (403; the body can have an empty error); an active metric has the same name (409).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx).
`MixpanelHeadlessError`	The create succeeded, but the second request (owner or verified flag) failed (`code="CREATE_FOLLOW_UP_FAILED"`). `details` holds `metric_id` (the created metric) and `fields` (the values that were not set); the error of the second request is chained as `__cause__`. The errors above come from the create itself, so nothing was created.

Example

ws = Workspace()
saved = ws.create_metric(CreateMetricParams(
    name="Weekly buyers",
    definition=Metric("Purchase", math="unique"),
    description="Unique users who bought.",
    verified=True,
))
print(saved.id, saved.verified)

Source code in src/mixpanel_headless/workspace.py

def create_metric(
    self, params: CreateMetricParams, *, validate: bool = True
) -> SavedMetric:
    """Create a saved metric from a typed or raw definition.

    The kind comes from the definition: a ``Metric``, ``CohortMetric``,
    ``FunnelMetric``, or ``RetentionMetric`` gives a behavior metric, a
    ``Formula`` with its own operands gives a saved formula, a
    ``WarehouseMetric`` gives a warehouse metric, and a
    ``RawMetricDefinition`` gives the kind it names. A behavior metric
    saves the ``behavior`` and ``measurement`` that :meth:`query` writes
    for the same value, and a saved formula holds the operands that a
    query formula holds, so the saved metric queries the same way as its
    inline twin.

    Stored definitions can carry legacy keys (for example a behavior
    ``filter``, or the ``id`` and ``type`` of a measurement) that the
    server reads past at query time but refuses on a create. So the
    method removes them from a ``RawMetricDefinition``, with or without
    ``validate``, and a copy of a stored metric works. A definition
    compiled from a typed value never has one; if it does, the method
    refuses it (``SM4_SCHEMA``).

    Before any request, the method checks the name and description and
    the definition (see Raises). Then it sends the create. The server
    drops ``owned_by`` and ``verified`` from a create, so when the params
    set an owner or ``verified=True``, a second request (an update)
    sets them. The two requests are not atomic: if the second one fails,
    the metric exists without the owner or the verified flag, and the
    method raises an error that names the id of the created metric
    (see Raises).

    In a project with sharing on, a new metric is private to its
    creator; this API cannot share it.

    Args:
        params: Name, definition, and optional description, display,
            goals, owner, and verified flag.
        validate: Check the definition with the mirror of the server
            schema before the request (default), including the refusal
            of legacy keys in a compiled definition. ``False`` sends it
            without the check (a raw definition still loses its legacy
            keys); the server still checks a create and answers a
            failing definition with a 400 (``QueryError``).

    Returns:
        The created ``SavedMetric`` (after the second request, when one
        was needed).

    Raises:
        ParamValidationError: Before any request: an empty name
            (``SM1_EMPTY_NAME``); a name or description longer than 255
            characters, which the server fails with a 500
            (``SM2_NAME_TOO_LONG``); a definition that fails the schema
            mirror, or a warehouse definition without a source
            (``SM4_SCHEMA``); a saved formula whose operands use segment
            method or attribution (``FM6_OPERAND_ATTRIBUTION``); a
            ``Formula`` without operands (``SM7_FORMULA_WITHOUT_OPERANDS``).
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The server refused the body (400; the message names
            the failure and its schema location, and ``response_body``
            holds the full server body); the pricing-plan gate
            ("Cannot save metric with your current plan"), a missing
            permission, or an unknown warehouse source (403; the body can
            have an empty error); an active metric has the same name
            (409).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx).
        MixpanelHeadlessError: The create succeeded, but the second
            request (owner or verified flag) failed
            (``code="CREATE_FOLLOW_UP_FAILED"``). ``details`` holds
            ``metric_id`` (the created metric) and ``fields`` (the
            values that were not set); the error of the second request
            is chained as ``__cause__``. The errors above come from the
            create itself, so nothing was created.

    Example:
        ```python
        ws = Workspace()
        saved = ws.create_metric(CreateMetricParams(
            name="Weekly buyers",
            definition=Metric("Purchase", math="unique"),
            description="Unique users who bought.",
            verified=True,
        ))
        print(saved.id, saved.verified)
        ```
    """
    check_name(params.name, entity="saved metric")
    check_description(params.description, entity="saved metric")
    parts = prepare_new_metric(
        params.definition,
        params.display,
        params.goals,
        validate=validate,
        for_create=True,
    )
    if parts.kind == "warehouse" and parts.warehouse_source_id is None:
        raise ParamValidationError(
            "A new warehouse metric needs a warehouse source: set "
            "WarehouseMetric.source_id or RawMetricDefinition."
            "warehouse_source_id.",
            code="SM4_SCHEMA",
            details={"path": "warehouse_source_id"},
        )
    body: dict[str, Any] = {"type": parts.kind, "name": params.name}
    if params.description is not None:
        body["description"] = params.description
    body["definition"] = parts.definition
    if parts.kind == "warehouse":
        body["warehouse_source_id"] = parts.warehouse_source_id

    client = self._require_api_client()
    created = validate_response_model(
        SavedMetric, client.create_metric(body), endpoint="create_metric"
    )
    follow_up: dict[str, Any] = {}
    if params.owned_by is not None:
        follow_up["owned_by"] = {"id": params.owned_by}
    if params.verified:
        follow_up["verified"] = True
    if not follow_up:
        return created
    try:
        row = client.update_metric(created.id, follow_up)
    except MixpanelHeadlessError as exc:
        fields = sorted(follow_up)
        logger.warning(
            "create_metric: created saved metric %s, but the follow-up "
            "update of %s failed",
            created.id,
            fields,
        )
        raise MixpanelHeadlessError(
            f"create_metric: created saved metric {created.id}, but the "
            f"follow-up update of {', '.join(fields)} failed: {exc.message}. "
            f"The metric exists without these values; set them with "
            f"update_metric or remove the metric with delete_metric.",
            code="CREATE_FOLLOW_UP_FAILED",
            details={"metric_id": created.id, "fields": fields},
        ) from exc
    return validate_response_model(SavedMetric, row, endpoint="create_metric")

update_metric ¶

update_metric(
    metric_id: int, params: UpdateMetricParams, *, validate: bool = True
) -> SavedMetric

Update a saved metric: metadata, definition, presentation, owner, or verified.

The server runs no schema check on an update and stores a new definition as sent, so this method runs the same checks as :meth:create_metric before any request. It sends one update.

When the params change the definition, the display, or the goals, the method reads the metric first, because the server replaces the definition in full:

A new definition must have the stored kind and, for a warehouse metric, the stored source. It keeps the stored display and goals unless the params or the new definition set them.
Display or goals without a definition send the stored definition back with the new values, as the web app does.
The params display merges into the stored display (or into the display of the new definition, when it has one): the keys that you set replace the stored ones, a key set to None is removed, and the other keys stay. The params goals replace the stored goals in full.
A WarehouseMetric whose aggregation or sync_interval is None keeps the stored value, so an update of the SQL alone keeps a stored "sum" and "daily". A RawMetricDefinition is sent as given.

The read and the update are not atomic; an edit in the web app between them is overwritten. A failed read raises; the method never guesses the stored definition.

PARAMETER	DESCRIPTION
`metric_id`	The saved metric id. TYPE: `int`
`params`	The fields to change; `None` leaves a field as it is. `verified=True` stamps the verification time again. `owned_by` sets an owner; an owner cannot be removed. TYPE: `UpdateMetricParams`
`validate`	Check new definition, display, and goal values with the mirror of the server schema (default). `False` sends them as given, and the server stores them unchecked. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`SavedMetric`	The updated `SavedMetric`.

RAISES	DESCRIPTION
`ParamValidationError`	Before any request: an empty name (`SM1_EMPTY_NAME`), a name or description longer than 255 characters (`SM2_NAME_TOO_LONG`), a value that fails the schema mirror (`SM4_SCHEMA`), or a saved formula operand with segment method or attribution (`FM6_OPERAND_ATTRIBUTION`). After the read: a new definition of another kind or warehouse source (`SM3_KIND_CHANGE`).
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The metric does not exist or is deleted (404), the caller cannot edit it or the pricing-plan gate blocks the write (403), or the new name is taken (409).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.update_metric(104700, UpdateMetricParams(
    display=MetricDisplay(suffix=" users", precision=0),
    verified=True,
))
ws.update_metric(104700, UpdateMetricParams(
    definition=Metric("Purchase", math="unique", segment_method="first"),
))

Source code in src/mixpanel_headless/workspace.py

def update_metric(
    self,
    metric_id: int,
    params: UpdateMetricParams,
    *,
    validate: bool = True,
) -> SavedMetric:
    """Update a saved metric: metadata, definition, presentation, owner, or verified.

    The server runs no schema check on an update and stores a new
    definition as sent, so this method runs the same checks as
    :meth:`create_metric` before any request. It sends one update.

    When the params change the definition, the display, or the goals,
    the method reads the metric first, because the server replaces the
    definition in full:

    - A new definition must have the stored kind and, for a warehouse
      metric, the stored source. It keeps the stored display and goals
      unless the params or the new definition set them.
    - Display or goals without a definition send the stored definition
      back with the new values, as the web app does.
    - The params display merges into the stored display (or into the
      display of the new definition, when it has one): the keys that
      you set replace the stored ones, a key set to ``None`` is
      removed, and the other keys stay. The params goals replace the
      stored goals in full.
    - A ``WarehouseMetric`` whose ``aggregation`` or ``sync_interval``
      is ``None`` keeps the stored value, so an update of the SQL alone
      keeps a stored ``"sum"`` and ``"daily"``. A
      ``RawMetricDefinition`` is sent as given.

    The read and the update are not atomic; an edit in the web app
    between them is overwritten. A failed read raises; the method never
    guesses the stored definition.

    Args:
        metric_id: The saved metric id.
        params: The fields to change; ``None`` leaves a field as it is.
            ``verified=True`` stamps the verification time again.
            ``owned_by`` sets an owner; an owner cannot be removed.
        validate: Check new definition, display, and goal values with the
            mirror of the server schema (default). ``False`` sends them
            as given, and the server stores them unchecked.

    Returns:
        The updated ``SavedMetric``.

    Raises:
        ParamValidationError: Before any request: an empty name
            (``SM1_EMPTY_NAME``), a name or description longer than 255
            characters (``SM2_NAME_TOO_LONG``), a value that fails the
            schema mirror (``SM4_SCHEMA``), or a saved formula operand
            with segment method or attribution
            (``FM6_OPERAND_ATTRIBUTION``). After the read: a new
            definition of another kind or warehouse source
            (``SM3_KIND_CHANGE``).
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The metric does not exist or is deleted (404), the
            caller cannot edit it or the pricing-plan gate blocks the write
            (403), or the new name is taken (409).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.update_metric(104700, UpdateMetricParams(
            display=MetricDisplay(suffix=" users", precision=0),
            verified=True,
        ))
        ws.update_metric(104700, UpdateMetricParams(
            definition=Metric("Purchase", math="unique", segment_method="first"),
        ))
        ```
    """
    check_name(params.name, entity="saved metric")
    check_description(params.description, entity="saved metric")
    change = prepare_metric_change(
        params.definition, params.display, params.goals, validate=validate
    )
    client = self._require_api_client()
    body: dict[str, Any] = {}
    if params.name is not None:
        body["name"] = params.name
    if params.description is not None:
        body["description"] = params.description
    if change is not None:
        stored = validate_response_model(
            SavedMetric, client.get_metric(metric_id), endpoint="update_metric"
        )
        body["definition"] = finish_metric_change(change, stored)
    if params.owned_by is not None:
        body["owned_by"] = {"id": params.owned_by}
    if params.verified is not None:
        body["verified"] = params.verified
    row = client.update_metric(metric_id, body)
    return validate_response_model(SavedMetric, row, endpoint="update_metric")

bulk_update_metrics ¶

bulk_update_metrics(
    entries: Sequence[BulkUpdateMetricEntry], *, validate: bool = True
) -> list[SavedMetric]

Update several saved metrics with one request, for example to verify them.

Each entry holds a metric id plus the fields to change. The method runs the checks of :meth:update_metric on every entry before it sends anything. An entry with a new definition reads its metric first (one read per such entry) to check the kind and to keep the stored display and goals. One bad entry stops the whole batch.

The server skips ids that do not name a metric of the project, with no error; compare the ids of the result with the ids you sent.

PARAMETER	DESCRIPTION
`entries`	One entry per metric. TYPE: `Sequence[BulkUpdateMetricEntry]`
`validate`	Check new definitions with the mirror of the server schema (default). TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`list[SavedMetric]`	The updated `SavedMetric` objects, in server order. An empty
`list[SavedMetric]`	`entries` sends no request and returns `[]`.

RAISES	DESCRIPTION
`ParamValidationError`	An entry breaks a rule of :meth:`update_metric` (`SM1_EMPTY_NAME`, `SM2_NAME_TOO_LONG`, `SM4_SCHEMA`, `FM6_OPERAND_ATTRIBUTION`, `SM3_KIND_CHANGE`); nothing was sent.
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The read of an entry's metric failed (404), the caller cannot edit one of the metrics (403), or a new name is taken (409).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
candidates = ws.list_metrics(name_contains="[core]", verified=False)
ws.bulk_update_metrics(
    [BulkUpdateMetricEntry(id=m.id, verified=True) for m in candidates]
)

Source code in src/mixpanel_headless/workspace.py

def bulk_update_metrics(
    self,
    entries: Sequence[BulkUpdateMetricEntry],
    *,
    validate: bool = True,
) -> list[SavedMetric]:
    """Update several saved metrics with one request, for example to verify them.

    Each entry holds a metric id plus the fields to change. The method
    runs the checks of :meth:`update_metric` on every entry before it
    sends anything. An entry with a new definition reads its metric
    first (one read per such entry) to check the kind and to keep the
    stored display and goals. One bad entry stops the whole batch.

    The server skips ids that do not name a metric of the project, with
    no error; compare the ids of the result with the ids you sent.

    Args:
        entries: One entry per metric.
        validate: Check new definitions with the mirror of the server
            schema (default).

    Returns:
        The updated ``SavedMetric`` objects, in server order. An empty
        ``entries`` sends no request and returns ``[]``.

    Raises:
        ParamValidationError: An entry breaks a rule of
            :meth:`update_metric` (``SM1_EMPTY_NAME``,
            ``SM2_NAME_TOO_LONG``, ``SM4_SCHEMA``,
            ``FM6_OPERAND_ATTRIBUTION``, ``SM3_KIND_CHANGE``); nothing
            was sent.
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The read of an entry's metric failed (404), the
            caller cannot edit one of the metrics (403), or a new name
            is taken (409).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        candidates = ws.list_metrics(name_contains="[core]", verified=False)
        ws.bulk_update_metrics(
            [BulkUpdateMetricEntry(id=m.id, verified=True) for m in candidates]
        )
        ```
    """
    prepared = []
    for entry in entries:
        check_name(entry.name, entity="saved metric")
        check_description(entry.description, entity="saved metric")
        change = prepare_metric_change(
            entry.definition, None, None, validate=validate
        )
        prepared.append((entry, change))
    if not prepared:
        return []
    client = self._require_api_client()
    wire_entries: list[dict[str, Any]] = []
    for entry, change in prepared:
        item: dict[str, Any] = {"id": entry.id}
        if entry.name is not None:
            item["name"] = entry.name
        if entry.description is not None:
            item["description"] = entry.description
        if change is not None:
            stored = validate_response_model(
                SavedMetric,
                client.get_metric(entry.id),
                endpoint="bulk_update_metrics",
            )
            item["definition"] = finish_metric_change(change, stored)
        if entry.owned_by is not None:
            item["owned_by"] = {"id": entry.owned_by}
        if entry.verified is not None:
            item["verified"] = entry.verified
        wire_entries.append(item)
    rows = client.bulk_update_metrics(wire_entries)
    return validate_response_models(
        SavedMetric, rows, endpoint="bulk_update_metrics"
    )

delete_metric ¶

delete_metric(metric_id: int, *, force: bool = False) -> None

Delete one saved metric, after a read that confirms it exists and is yours to edit.

The server has no working single-metric delete, and its bulk delete skips unknown ids with no error. So this method reads the metric first, then sends the bulk delete with the one id. An unknown id raises instead of passing silently. The delete is a soft delete on the server; reports that refer to the metric keep a copy of its definition but lose the link.

The server's bulk delete lets a project superadmin delete metrics that other users own, even when the metric's can_update_basic flag is false for that account. So this method refuses a metric whose can_update_basic is false, unless force is true. A read without the flag does not refuse; the server stays the authority.

PARAMETER	DESCRIPTION
`metric_id`	The saved metric id. TYPE: `int`
`force`	Delete even when the read says that the caller cannot edit the metric (a superadmin account can delete metrics that other users own). The existence read still runs. TYPE: `bool` DEFAULT: `False`

RAISES	DESCRIPTION
`ParamValidationError`	The read found no active metric with this id (404); nothing was deleted (`SM5_NOT_FOUND_FOR_DELETE`). The read shows `can_update_basic` false and `force` is false; nothing was deleted (`SM6_DELETE_NOT_PERMITTED`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The caller cannot read or edit the metric, or lacks the warehouse permission for a warehouse metric (403).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
ws.delete_metric(104700)
ws.delete_metric(118228, force=True)  # a metric another user owns

Source code in src/mixpanel_headless/workspace.py

def delete_metric(self, metric_id: int, *, force: bool = False) -> None:
    """Delete one saved metric, after a read that confirms it exists and is yours to edit.

    The server has no working single-metric delete, and its bulk delete
    skips unknown ids with no error. So this method reads the metric
    first, then sends the bulk delete with the one id. An unknown id
    raises instead of passing silently. The delete is a soft delete on
    the server; reports that refer to the metric keep a copy of its
    definition but lose the link.

    The server's bulk delete lets a project superadmin delete metrics
    that other users own, even when the metric's ``can_update_basic``
    flag is false for that account. So this method refuses a metric
    whose ``can_update_basic`` is false, unless ``force`` is true. A
    read without the flag does not refuse; the server stays the
    authority.

    Args:
        metric_id: The saved metric id.
        force: Delete even when the read says that the caller cannot
            edit the metric (a superadmin account can delete metrics
            that other users own). The existence read still runs.

    Raises:
        ParamValidationError: The read found no active metric with this
            id (404); nothing was deleted (``SM5_NOT_FOUND_FOR_DELETE``).
            The read shows ``can_update_basic`` false and ``force`` is
            false; nothing was deleted (``SM6_DELETE_NOT_PERMITTED``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The caller cannot read or edit the metric, or lacks
            the warehouse permission for a warehouse metric (403).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        ws.delete_metric(104700)
        ws.delete_metric(118228, force=True)  # a metric another user owns
        ```
    """
    client = self._require_api_client()
    try:
        row = client.get_metric(metric_id)
    except QueryError as exc:
        if exc.status_code != 404:
            raise
        raise ParamValidationError(
            f"Saved metric {metric_id} was not found in project "
            f"{client.project_id}; nothing was deleted.",
            code="SM5_NOT_FOUND_FOR_DELETE",
            details={
                "metric_id": metric_id,
                "project_id": client.project_id,
                "status_code": 404,
            },
        ) from exc
    if not force and row.get("can_update_basic") is False:
        self._refuse_delete("metric", [row])
    client.delete_metrics([metric_id])

delete_metrics ¶

delete_metrics(metric_ids: Sequence[int], *, force: bool = False) -> None

Delete several saved metrics with one bulk request.

The server skips ids that do not name an active metric of the project, with no error, so a typo in an id passes silently. Use :meth:delete_metric to delete one metric with an existence check. An empty sequence sends no request.

The server's bulk delete lets a project superadmin delete metrics that other users own. So, unless force is true, this method reads the metric list once and refuses the whole request, before the delete, when any target has can_update_basic false. Ids that the list does not hold are not refused; the server skips them.

PARAMETER	DESCRIPTION
`metric_ids`	The saved metric ids to delete. TYPE: `Sequence[int]`
`force`	Skip the list read and the permission guard, and send the delete as given. TYPE: `bool` DEFAULT: `False`

RAISES	DESCRIPTION
`ParamValidationError`	A target has `can_update_basic` false and `force` is false; nothing was deleted. The error lists every refused id (`SM6_DELETE_NOT_PERMITTED`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The caller cannot edit one of the metrics, or lacks the warehouse permission for a warehouse metric (403); nothing was deleted.
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
stale = ws.list_metrics(name_contains="[old]")
ws.delete_metrics([m.id for m in stale])

Source code in src/mixpanel_headless/workspace.py

def delete_metrics(self, metric_ids: Sequence[int], *, force: bool = False) -> None:
    """Delete several saved metrics with one bulk request.

    The server skips ids that do not name an active metric of the
    project, with no error, so a typo in an id passes silently. Use
    :meth:`delete_metric` to delete one metric with an existence check.
    An empty sequence sends no request.

    The server's bulk delete lets a project superadmin delete metrics
    that other users own. So, unless ``force`` is true, this method
    reads the metric list once and refuses the whole request, before
    the delete, when any target has ``can_update_basic`` false. Ids that
    the list does not hold are not refused; the server skips them.

    Args:
        metric_ids: The saved metric ids to delete.
        force: Skip the list read and the permission guard, and send the
            delete as given.

    Raises:
        ParamValidationError: A target has ``can_update_basic`` false and
            ``force`` is false; nothing was deleted. The error lists every
            refused id (``SM6_DELETE_NOT_PERMITTED``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The caller cannot edit one of the metrics, or lacks
            the warehouse permission for a warehouse metric (403);
            nothing was deleted.
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        stale = ws.list_metrics(name_contains="[old]")
        ws.delete_metrics([m.id for m in stale])
        ```
    """
    if not metric_ids:
        return
    client = self._require_api_client()
    if not force:
        self._check_bulk_delete("metric", metric_ids, client.list_metrics())
    client.delete_metrics(list(metric_ids))

list_behaviors ¶

list_behaviors(
    *, behavior_type: str | None = None, name_contains: str | None = None
) -> list[SavedBehavior]

List saved behaviors: simple, funnel, and retention behaviors.

The server has no pagination, filters, or search, so one request fetches every active behavior, and the filters below apply locally to that response. The read timeout is at least 120 seconds.

PARAMETER	DESCRIPTION
`behavior_type`	Keep only behaviors of this type: `"simple"`, `"funnel"`, or `"retention"`. Exact match. TYPE: `str \| None` DEFAULT: `None`
`name_contains`	Keep only behaviors whose name contains this text, ignoring case. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[SavedBehavior]`	`SavedBehavior` objects in server order.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The caller lacks the behaviors permission or scope (403).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
for behavior in ws.list_behaviors(behavior_type="funnel"):
    print(behavior.id, behavior.name)

Source code in src/mixpanel_headless/workspace.py

def list_behaviors(
    self,
    *,
    behavior_type: str | None = None,
    name_contains: str | None = None,
) -> list[SavedBehavior]:
    """List saved behaviors: simple, funnel, and retention behaviors.

    The server has no pagination, filters, or search, so one request
    fetches every active behavior, and the filters below apply locally
    to that response. The read timeout is at least 120 seconds.

    Args:
        behavior_type: Keep only behaviors of this type: ``"simple"``,
            ``"funnel"``, or ``"retention"``. Exact match.
        name_contains: Keep only behaviors whose name contains this
            text, ignoring case.

    Returns:
        ``SavedBehavior`` objects in server order.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The caller lacks the behaviors permission or scope (403).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        for behavior in ws.list_behaviors(behavior_type="funnel"):
            print(behavior.id, behavior.name)
        ```
    """
    client = self._require_api_client()
    behaviors = validate_response_models(
        SavedBehavior, client.list_behaviors(), endpoint="list_behaviors"
    )
    if behavior_type is not None:
        behaviors = [b for b in behaviors if b.type == behavior_type]
    if name_contains is not None:
        needle = name_contains.casefold()
        behaviors = [b for b in behaviors if needle in b.name.casefold()]
    return behaviors

get_behavior ¶

get_behavior(behavior_id: int) -> SavedBehavior

Get one saved behavior by id, with its full definition.

The server does not answer an unknown or deleted id with 404; it answers with a 500, which raises ServerError.

PARAMETER	DESCRIPTION
`behavior_id`	The saved behavior id. TYPE: `int`

RETURNS	DESCRIPTION
`SavedBehavior`	The `SavedBehavior`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The caller lacks permission (403).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx), including an unknown or deleted behavior id.

Example

ws = Workspace()
behavior = ws.get_behavior(3001)
print(behavior.type, behavior.definition["behavior"])

Source code in src/mixpanel_headless/workspace.py

def get_behavior(self, behavior_id: int) -> SavedBehavior:
    """Get one saved behavior by id, with its full definition.

    The server does not answer an unknown or deleted id with 404; it
    answers with a 500, which raises ``ServerError``.

    Args:
        behavior_id: The saved behavior id.

    Returns:
        The ``SavedBehavior``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The caller lacks permission (403).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx), including an unknown or
            deleted behavior id.

    Example:
        ```python
        ws = Workspace()
        behavior = ws.get_behavior(3001)
        print(behavior.type, behavior.definition["behavior"])
        ```
    """
    client = self._require_api_client()
    return validate_response_model(
        SavedBehavior, client.get_behavior(behavior_id), endpoint="get_behavior"
    )

create_behavior ¶

create_behavior(
    params: CreateBehaviorParams, *, validate: bool = True
) -> SavedBehavior

Create a saved behavior: a reusable simple, funnel, or retention behavior.

The wire type of the behavior comes from its definition. Before the request, the method checks the name and description and the definition (see Raises). In a project with sharing on, a new behavior is private to its creator; this API cannot share it.

Stored definitions can carry legacy keys (for example a behavior filter, or a legacy funnel step key of an exclusion) that the server reads past at query time but refuses on a create. So the method removes them from a RawBehaviorDefinition, with or without validate, and a copy of a stored behavior works. A definition compiled from a typed value never has one; if it does, the method refuses it (SM4_SCHEMA).

PARAMETER	DESCRIPTION
`params`	Name, behavior definition, and optional description. TYPE: `CreateBehaviorParams`
`validate`	Check the definition with the mirror of the server schema before the request (default), including the refusal of legacy keys in a compiled definition. `False` sends it without the check (a raw definition still loses its legacy keys); the server still checks a create and answers a failing definition with a 400 (`QueryError`). TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`SavedBehavior`	The created `SavedBehavior`.

RAISES	DESCRIPTION
`ParamValidationError`	Before any request: an empty name (`SM1_EMPTY_NAME`); a name or description longer than 255 characters (`SM2_NAME_TOO_LONG`); a definition with no `behavior.type` string, or one that fails the schema mirror (`SM4_SCHEMA`).
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The server refused the body (400); the pricing-plan gate ("Cannot save behavior with your current plan") or a missing permission (403); an active behavior has the same name (409).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
source = ws.get_behavior(3001)
copy = ws.create_behavior(CreateBehaviorParams(
    name="Checkout (copy)",
    behavior=RawBehaviorDefinition(source.definition),
))

Source code in src/mixpanel_headless/workspace.py

def create_behavior(
    self, params: CreateBehaviorParams, *, validate: bool = True
) -> SavedBehavior:
    """Create a saved behavior: a reusable simple, funnel, or retention behavior.

    The wire type of the behavior comes from its definition. Before the
    request, the method checks the name and description and the
    definition (see Raises). In a project with sharing on, a new
    behavior is private to its creator; this API cannot share it.

    Stored definitions can carry legacy keys (for example a behavior
    ``filter``, or a legacy funnel step key of an exclusion) that the
    server reads past at query time but refuses on a create. So the
    method removes them from a ``RawBehaviorDefinition``, with or
    without ``validate``, and a copy of a stored behavior works. A
    definition compiled from a typed value never has one; if it does,
    the method refuses it (``SM4_SCHEMA``).

    Args:
        params: Name, behavior definition, and optional description.
        validate: Check the definition with the mirror of the server
            schema before the request (default), including the refusal
            of legacy keys in a compiled definition. ``False`` sends it
            without the check (a raw definition still loses its legacy
            keys); the server still checks a create and answers a
            failing definition with a 400 (``QueryError``).

    Returns:
        The created ``SavedBehavior``.

    Raises:
        ParamValidationError: Before any request: an empty name
            (``SM1_EMPTY_NAME``); a name or description longer than 255
            characters (``SM2_NAME_TOO_LONG``); a definition with no
            ``behavior.type`` string, or one that fails the schema mirror
            (``SM4_SCHEMA``).
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The server refused the body (400); the pricing-plan gate
            ("Cannot save behavior with your current plan") or a missing
            permission (403); an active behavior has the same name (409).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        source = ws.get_behavior(3001)
        copy = ws.create_behavior(CreateBehaviorParams(
            name="Checkout (copy)",
            behavior=RawBehaviorDefinition(source.definition),
        ))
        ```
    """
    check_name(params.name, entity="saved behavior")
    check_description(params.description, entity="saved behavior")
    definition = behavior_wire_definition(params.behavior, for_create=True)
    behavior_type = self._saved_behavior_type(definition)
    if validate:
        check_behavior_definition(definition, for_create=True)
    body: dict[str, Any] = {"type": behavior_type, "name": params.name}
    if params.description is not None:
        body["description"] = params.description
    body["definition"] = definition
    client = self._require_api_client()
    row = client.create_behavior(body)
    return validate_response_model(SavedBehavior, row, endpoint="create_behavior")

update_behavior ¶

update_behavior(
    behavior_id: int, params: UpdateBehaviorParams, *, validate: bool = True
) -> SavedBehavior

Update a saved behavior: name, description, definition, or verified flag.

The server runs no schema check on an update and ignores the behavior type, so a new definition goes through the checks of :meth:create_behavior first. A new definition also makes the method read the behavior, to refuse a change of type. The server answers the read of an unknown or deleted id with a 500.

PARAMETER	DESCRIPTION
`behavior_id`	The saved behavior id. TYPE: `int`
`params`	The fields to change; `None` leaves a field as it is. `verified=True` stamps the verification time again. TYPE: `UpdateBehaviorParams`
`validate`	Check a new definition with the mirror of the server schema (default). `False` sends it as given, and the server stores it unchecked. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`SavedBehavior`	The updated `SavedBehavior`.

RAISES	DESCRIPTION
`ParamValidationError`	Before any request: an empty name (`SM1_EMPTY_NAME`), a name or description longer than 255 characters (`SM2_NAME_TOO_LONG`), or a definition with no type or one that fails the schema mirror (`SM4_SCHEMA`). After the read: a definition of another type (`SM3_KIND_CHANGE`).
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The caller cannot edit the behavior (403), or the new name is taken (409).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx), including the read of an unknown behavior id.

Example

ws = Workspace()
ws.update_behavior(3001, UpdateBehaviorParams(verified=True))

Source code in src/mixpanel_headless/workspace.py

def update_behavior(
    self,
    behavior_id: int,
    params: UpdateBehaviorParams,
    *,
    validate: bool = True,
) -> SavedBehavior:
    """Update a saved behavior: name, description, definition, or verified flag.

    The server runs no schema check on an update and ignores the
    behavior type, so a new definition goes through the checks of
    :meth:`create_behavior` first. A new definition also makes the method
    read the behavior, to refuse a change of type. The server answers
    the read of an unknown or deleted id with a 500.

    Args:
        behavior_id: The saved behavior id.
        params: The fields to change; ``None`` leaves a field as it is.
            ``verified=True`` stamps the verification time again.
        validate: Check a new definition with the mirror of the server
            schema (default). ``False`` sends it as given, and the server
            stores it unchecked.

    Returns:
        The updated ``SavedBehavior``.

    Raises:
        ParamValidationError: Before any request: an empty name
            (``SM1_EMPTY_NAME``), a name or description longer than 255
            characters (``SM2_NAME_TOO_LONG``), or a definition with no
            type or one that fails the schema mirror (``SM4_SCHEMA``).
            After the read: a definition of another type
            (``SM3_KIND_CHANGE``).
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The caller cannot edit the behavior (403), or the new
            name is taken (409).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx), including the read of an
            unknown behavior id.

    Example:
        ```python
        ws = Workspace()
        ws.update_behavior(3001, UpdateBehaviorParams(verified=True))
        ```
    """
    check_name(params.name, entity="saved behavior")
    check_description(params.description, entity="saved behavior")
    definition: dict[str, Any] | None = None
    behavior_type: str | None = None
    if params.behavior is not None:
        definition = behavior_wire_definition(params.behavior)
        behavior_type = self._saved_behavior_type(definition)
        if validate:
            check_behavior_definition(definition)
    client = self._require_api_client()
    body: dict[str, Any] = {}
    if params.name is not None:
        body["name"] = params.name
    if params.description is not None:
        body["description"] = params.description
    if definition is not None and behavior_type is not None:
        stored = validate_response_model(
            SavedBehavior,
            client.get_behavior(behavior_id),
            endpoint="update_behavior",
        )
        check_same_kind(
            entity="saved behavior",
            entity_id=behavior_id,
            stored_kind=stored.type,
            new_kind=behavior_type,
        )
        body["definition"] = definition
    if params.verified is not None:
        body["verified"] = params.verified
    row = client.update_behavior(behavior_id, body)
    return validate_response_model(SavedBehavior, row, endpoint="update_behavior")

delete_behavior ¶

delete_behavior(behavior_id: int, *, force: bool = False) -> None

Delete one saved behavior, after a read that confirms it exists and is yours to edit.

Sends the bulk delete with the one id, because the bulk route is the one that checks the caller's permission; the single-behavior route does not. The bulk route skips unknown ids with no error, so this method reads the behavior first. For an unknown or deleted id that read fails with a server 500 (ServerError), and nothing is deleted.

The server's bulk delete lets a project superadmin delete behaviors that other users created, even when the behavior's can_update_basic flag is false for that account. So this method refuses a behavior whose can_update_basic is false, unless force is true. A read without the flag does not refuse.

PARAMETER	DESCRIPTION
`behavior_id`	The saved behavior id. TYPE: `int`
`force`	Delete even when the read says that the caller cannot edit the behavior. The existence read still runs. TYPE: `bool` DEFAULT: `False`

RAISES	DESCRIPTION
`ParamValidationError`	The read shows `can_update_basic` false and `force` is false; nothing was deleted (`BH4_DELETE_NOT_PERMITTED`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The caller cannot read or edit the behavior (403).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx), including the read of an unknown or deleted behavior id.

Example

ws = Workspace()
ws.delete_behavior(3001)

Source code in src/mixpanel_headless/workspace.py

def delete_behavior(self, behavior_id: int, *, force: bool = False) -> None:
    """Delete one saved behavior, after a read that confirms it exists and is yours to edit.

    Sends the bulk delete with the one id, because the bulk route is the
    one that checks the caller's permission; the single-behavior route
    does not. The bulk route skips unknown ids with no error, so this
    method reads the behavior first. For an unknown or deleted id that
    read fails with a server 500 (``ServerError``), and nothing is
    deleted.

    The server's bulk delete lets a project superadmin delete behaviors
    that other users created, even when the behavior's
    ``can_update_basic`` flag is false for that account. So this method
    refuses a behavior whose ``can_update_basic`` is false, unless
    ``force`` is true. A read without the flag does not refuse.

    Args:
        behavior_id: The saved behavior id.
        force: Delete even when the read says that the caller cannot
            edit the behavior. The existence read still runs.

    Raises:
        ParamValidationError: The read shows ``can_update_basic`` false
            and ``force`` is false; nothing was deleted
            (``BH4_DELETE_NOT_PERMITTED``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The caller cannot read or edit the behavior (403).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx), including the read of an
            unknown or deleted behavior id.

    Example:
        ```python
        ws = Workspace()
        ws.delete_behavior(3001)
        ```
    """
    client = self._require_api_client()
    row = client.get_behavior(behavior_id)
    if not force and row.get("can_update_basic") is False:
        self._refuse_delete("behavior", [row])
    client.delete_behaviors([behavior_id])

delete_behaviors ¶

delete_behaviors(behavior_ids: Sequence[int], *, force: bool = False) -> None

Delete several saved behaviors with one bulk request.

The server skips ids that do not name a behavior of the project, with no error, so a typo in an id passes silently. Use :meth:delete_behavior to delete one behavior with an existence check. An empty sequence sends no request.

The server's bulk delete lets a project superadmin delete behaviors that other users created. So, unless force is true, this method reads the behavior list once and refuses the whole request, before the delete, when any target has can_update_basic false. Ids that the list does not hold are not refused; the server skips them.

PARAMETER	DESCRIPTION
`behavior_ids`	The saved behavior ids to delete. TYPE: `Sequence[int]`
`force`	Skip the list read and the permission guard, and send the delete as given. TYPE: `bool` DEFAULT: `False`

RAISES	DESCRIPTION
`ParamValidationError`	A target has `can_update_basic` false and `force` is false; nothing was deleted. The error lists every refused id (`BH4_DELETE_NOT_PERMITTED`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	The caller cannot edit one of the behaviors (403).
`RateLimitError`	Rate limit exceeded after retries (429).
`ServerError`	Server-side errors (5xx).

Example

ws = Workspace()
drafts = ws.list_behaviors(name_contains="draft")
ws.delete_behaviors([b.id for b in drafts])

Source code in src/mixpanel_headless/workspace.py

def delete_behaviors(
    self, behavior_ids: Sequence[int], *, force: bool = False
) -> None:
    """Delete several saved behaviors with one bulk request.

    The server skips ids that do not name a behavior of the project,
    with no error, so a typo in an id passes silently. Use
    :meth:`delete_behavior` to delete one behavior with an existence
    check. An empty sequence sends no request.

    The server's bulk delete lets a project superadmin delete behaviors
    that other users created. So, unless ``force`` is true, this method
    reads the behavior list once and refuses the whole request, before
    the delete, when any target has ``can_update_basic`` false. Ids that
    the list does not hold are not refused; the server skips them.

    Args:
        behavior_ids: The saved behavior ids to delete.
        force: Skip the list read and the permission guard, and send the
            delete as given.

    Raises:
        ParamValidationError: A target has ``can_update_basic`` false and
            ``force`` is false; nothing was deleted. The error lists every
            refused id (``BH4_DELETE_NOT_PERMITTED``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: The caller cannot edit one of the behaviors (403).
        RateLimitError: Rate limit exceeded after retries (429).
        ServerError: Server-side errors (5xx).

    Example:
        ```python
        ws = Workspace()
        drafts = ws.list_behaviors(name_contains="draft")
        ws.delete_behaviors([b.id for b in drafts])
        ```
    """
    if not behavior_ids:
        return
    client = self._require_api_client()
    if not force:
        self._check_bulk_delete("behavior", behavior_ids, client.list_behaviors())
    client.delete_behaviors(list(behavior_ids))

list_schema_registry ¶

list_schema_registry(*, entity_type: str | None = None) -> list[SchemaEntry]

List schema registry entries.

PARAMETER	DESCRIPTION
`entity_type`	Filter by entity type ("event", "custom_event", "profile"). If None, returns all schemas. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[SchemaEntry]`	List of `SchemaEntry` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`RateLimitError`	Rate limit exceeded (429).

Example

ws = Workspace()
schemas = ws.list_schema_registry(entity_type="event")
for s in schemas:
    print(f"{s.name}: {s.entity_type}")

Source code in src/mixpanel_headless/workspace.py

def list_schema_registry(
    self,
    *,
    entity_type: str | None = None,
) -> list[SchemaEntry]:
    """List schema registry entries.

    Args:
        entity_type: Filter by entity type ("event", "custom_event",
            "profile"). If None, returns all schemas.

    Returns:
        List of ``SchemaEntry`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        RateLimitError: Rate limit exceeded (429).

    Example:
        ```python
        ws = Workspace()
        schemas = ws.list_schema_registry(entity_type="event")
        for s in schemas:
            print(f"{s.name}: {s.entity_type}")
        ```
    """
    client = self._require_api_client()
    raw_list = client.list_schema_registry(entity_type=entity_type)
    return validate_response_models(
        SchemaEntry, raw_list, endpoint="list_schema_registry"
    )

create_schema ¶

create_schema(
    entity_type: str, entity_name: str, schema_json: dict[str, Any]
) -> dict[str, Any]

Create a single schema definition.

PARAMETER	DESCRIPTION
`entity_type`	Entity type ("event", "custom_event", "profile"). TYPE: `str`
`entity_name`	Entity name (event name or "$user" for profile). TYPE: `str`
`schema_json`	JSON Schema Draft 7 definition. TYPE: `dict[str, Any]`

RETURNS	DESCRIPTION
`dict[str, Any]`	Created schema as dict.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`RateLimitError`	Rate limit exceeded (429).

Example

ws = Workspace()
ws.create_schema("event", "Purchase", {
    "properties": {"amount": {"type": "number"}}
})

Source code in src/mixpanel_headless/workspace.py

def create_schema(
    self,
    entity_type: str,
    entity_name: str,
    schema_json: dict[str, Any],
) -> dict[str, Any]:
    """Create a single schema definition.

    Args:
        entity_type: Entity type ("event", "custom_event", "profile").
        entity_name: Entity name (event name or "$user" for profile).
        schema_json: JSON Schema Draft 7 definition.

    Returns:
        Created schema as dict.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        RateLimitError: Rate limit exceeded (429).

    Example:
        ```python
        ws = Workspace()
        ws.create_schema("event", "Purchase", {
            "properties": {"amount": {"type": "number"}}
        })
        ```
    """
    client = self._require_api_client()
    return client.create_schema(entity_type, entity_name, schema_json)

create_schemas_bulk ¶

create_schemas_bulk(
    params: BulkCreateSchemasParams,
) -> BulkCreateSchemasResponse

Bulk create schemas.

PARAMETER	DESCRIPTION
`params`	Bulk creation parameters with entries list and optional truncate flag. TYPE: `BulkCreateSchemasParams`

RETURNS	DESCRIPTION
`BulkCreateSchemasResponse`	Response with `added` and `deleted` counts.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).
`RateLimitError`	Rate limit exceeded (429).

Example

ws = Workspace()
result = ws.create_schemas_bulk(BulkCreateSchemasParams(
    entries=[SchemaEntry(...)], truncate=True
))
print(f"Added: {result.added}")

Source code in src/mixpanel_headless/workspace.py

def create_schemas_bulk(
    self,
    params: BulkCreateSchemasParams,
) -> BulkCreateSchemasResponse:
    """Bulk create schemas.

    Args:
        params: Bulk creation parameters with entries list and
            optional truncate flag.

    Returns:
        Response with ``added`` and ``deleted`` counts.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).
        RateLimitError: Rate limit exceeded (429).

    Example:
        ```python
        ws = Workspace()
        result = ws.create_schemas_bulk(BulkCreateSchemasParams(
            entries=[SchemaEntry(...)], truncate=True
        ))
        print(f"Added: {result.added}")
        ```
    """
    client = self._require_api_client()
    raw = client.create_schemas_bulk(
        params.model_dump(exclude_none=True, by_alias=True)
    )
    return validate_response_model(
        BulkCreateSchemasResponse, raw, endpoint="create_schemas_bulk"
    )

update_schema ¶

update_schema(
    entity_type: str, entity_name: str, schema_json: dict[str, Any]
) -> dict[str, Any]

Update a single schema definition (merge semantics).

PARAMETER	DESCRIPTION
`entity_type`	Entity type. TYPE: `str`
`entity_name`	Entity name. TYPE: `str`
`schema_json`	Partial JSON Schema to merge with existing. TYPE: `dict[str, Any]`

RETURNS	DESCRIPTION
`dict[str, Any]`	Updated schema as dict.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Entity not found or validation error (400, 404).
`RateLimitError`	Rate limit exceeded (429).

Example

ws = Workspace()
ws.update_schema("event", "Purchase", {
    "properties": {"tax": {"type": "number"}}
})

Source code in src/mixpanel_headless/workspace.py

def update_schema(
    self,
    entity_type: str,
    entity_name: str,
    schema_json: dict[str, Any],
) -> dict[str, Any]:
    """Update a single schema definition (merge semantics).

    Args:
        entity_type: Entity type.
        entity_name: Entity name.
        schema_json: Partial JSON Schema to merge with existing.

    Returns:
        Updated schema as dict.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Entity not found or validation error (400, 404).
        RateLimitError: Rate limit exceeded (429).

    Example:
        ```python
        ws = Workspace()
        ws.update_schema("event", "Purchase", {
            "properties": {"tax": {"type": "number"}}
        })
        ```
    """
    client = self._require_api_client()
    return client.update_schema(entity_type, entity_name, schema_json)

update_schemas_bulk ¶

update_schemas_bulk(params: BulkCreateSchemasParams) -> list[BulkPatchResult]

Bulk update schemas (merge semantics per entry).

PARAMETER	DESCRIPTION
`params`	Bulk update parameters with entries list. TYPE: `BulkCreateSchemasParams`

RETURNS	DESCRIPTION
`list[BulkPatchResult]`	List of per-entry results with status ("ok" or "error").

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`RateLimitError`	Rate limit exceeded (429).

Example

ws = Workspace()
results = ws.update_schemas_bulk(BulkCreateSchemasParams(
    entries=[SchemaEntry(...)]
))
for r in results:
    print(f"{r.name}: {r.status}")

Source code in src/mixpanel_headless/workspace.py

def update_schemas_bulk(
    self,
    params: BulkCreateSchemasParams,
) -> list[BulkPatchResult]:
    """Bulk update schemas (merge semantics per entry).

    Args:
        params: Bulk update parameters with entries list.

    Returns:
        List of per-entry results with status ("ok" or "error").

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        RateLimitError: Rate limit exceeded (429).

    Example:
        ```python
        ws = Workspace()
        results = ws.update_schemas_bulk(BulkCreateSchemasParams(
            entries=[SchemaEntry(...)]
        ))
        for r in results:
            print(f"{r.name}: {r.status}")
        ```
    """
    client = self._require_api_client()
    raw_list = client.update_schemas_bulk(
        params.model_dump(exclude_none=True, by_alias=True)
    )
    return validate_response_models(
        BulkPatchResult, raw_list, endpoint="update_schemas_bulk"
    )

delete_schemas ¶

delete_schemas(
    *, entity_type: str | None = None, entity_name: str | None = None
) -> DeleteSchemasResponse

Delete schemas by entity type and/or name.

If both provided, deletes a single schema. If only entity_type, deletes all schemas of that type. If neither, deletes all schemas.

PARAMETER	DESCRIPTION
`entity_type`	Filter by entity type. TYPE: `str \| None` DEFAULT: `None`
`entity_name`	Filter by entity name (requires entity_type). TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`DeleteSchemasResponse`	Response with `delete_count`.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid parameters (400).
`RateLimitError`	Rate limit exceeded (429).
`MixpanelHeadlessError`	If entity_name is provided without entity_type.

Example

ws = Workspace()
resp = ws.delete_schemas(entity_type="event", entity_name="Purchase")
print(f"Deleted: {resp.delete_count}")

Source code in src/mixpanel_headless/workspace.py

def delete_schemas(
    self,
    *,
    entity_type: str | None = None,
    entity_name: str | None = None,
) -> DeleteSchemasResponse:
    """Delete schemas by entity type and/or name.

    If both provided, deletes a single schema. If only entity_type,
    deletes all schemas of that type. If neither, deletes all schemas.

    Args:
        entity_type: Filter by entity type.
        entity_name: Filter by entity name (requires entity_type).

    Returns:
        Response with ``delete_count``.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid parameters (400).
        RateLimitError: Rate limit exceeded (429).
        MixpanelHeadlessError: If entity_name is provided without entity_type.

    Example:
        ```python
        ws = Workspace()
        resp = ws.delete_schemas(entity_type="event", entity_name="Purchase")
        print(f"Deleted: {resp.delete_count}")
        ```
    """
    if entity_name is not None and entity_type is None:
        raise MixpanelHeadlessError(
            "entity_name requires entity_type: providing entity_name "
            "without entity_type would delete all schemas",
        )
    client = self._require_api_client()
    raw = client.delete_schemas(entity_type=entity_type, entity_name=entity_name)
    return validate_response_model(
        DeleteSchemasResponse, raw, endpoint="delete_schemas"
    )

get_schema_enforcement ¶

get_schema_enforcement(*, fields: str | None = None) -> SchemaEnforcementConfig

Get current schema enforcement configuration.

PARAMETER	DESCRIPTION
`fields`	Comma-separated field names to return (e.g., "ruleEvent,state"). If None, returns all fields. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`SchemaEnforcementConfig`	Schema enforcement configuration.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	No enforcement configured (404).

Example

ws = Workspace()
config = ws.get_schema_enforcement()
print(f"Rule: {config.rule_event}")

Source code in src/mixpanel_headless/workspace.py

def get_schema_enforcement(
    self,
    *,
    fields: str | None = None,
) -> SchemaEnforcementConfig:
    """Get current schema enforcement configuration.

    Args:
        fields: Comma-separated field names to return (e.g.,
            "ruleEvent,state"). If None, returns all fields.

    Returns:
        Schema enforcement configuration.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: No enforcement configured (404).

    Example:
        ```python
        ws = Workspace()
        config = ws.get_schema_enforcement()
        print(f"Rule: {config.rule_event}")
        ```
    """
    client = self._require_api_client()
    raw = client.get_schema_enforcement(fields=fields)
    return validate_response_model(
        SchemaEnforcementConfig, raw, endpoint="get_schema_enforcement"
    )

init_schema_enforcement ¶

init_schema_enforcement(params: InitSchemaEnforcementParams) -> dict[str, Any]

Initialize schema enforcement.

PARAMETER	DESCRIPTION
`params`	Init parameters with rule_event. TYPE: `InitSchemaEnforcementParams`

RETURNS	DESCRIPTION
`dict[str, Any]`	Raw API response as dict.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Already initialized or invalid rule_event (400).

Example

ws = Workspace()
ws.init_schema_enforcement(
    InitSchemaEnforcementParams(rule_event="Warn and Accept")
)

Source code in src/mixpanel_headless/workspace.py

def init_schema_enforcement(
    self,
    params: InitSchemaEnforcementParams,
) -> dict[str, Any]:
    """Initialize schema enforcement.

    Args:
        params: Init parameters with rule_event.

    Returns:
        Raw API response as dict.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Already initialized or invalid rule_event (400).

    Example:
        ```python
        ws = Workspace()
        ws.init_schema_enforcement(
            InitSchemaEnforcementParams(rule_event="Warn and Accept")
        )
        ```
    """
    client = self._require_api_client()
    return client.init_schema_enforcement(
        params.model_dump(exclude_none=True, by_alias=True)
    )

update_schema_enforcement ¶

update_schema_enforcement(
    params: UpdateSchemaEnforcementParams,
) -> dict[str, Any]

Partially update enforcement configuration.

PARAMETER	DESCRIPTION
`params`	Partial update parameters. TYPE: `UpdateSchemaEnforcementParams`

RETURNS	DESCRIPTION
`dict[str, Any]`	Raw API response as dict.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	No enforcement configured or validation error (400).

Example

ws = Workspace()
ws.update_schema_enforcement(
    UpdateSchemaEnforcementParams(rule_event="Warn and Drop")
)

Source code in src/mixpanel_headless/workspace.py

def update_schema_enforcement(
    self,
    params: UpdateSchemaEnforcementParams,
) -> dict[str, Any]:
    """Partially update enforcement configuration.

    Args:
        params: Partial update parameters.

    Returns:
        Raw API response as dict.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: No enforcement configured or validation error (400).

    Example:
        ```python
        ws = Workspace()
        ws.update_schema_enforcement(
            UpdateSchemaEnforcementParams(rule_event="Warn and Drop")
        )
        ```
    """
    client = self._require_api_client()
    return client.update_schema_enforcement(
        params.model_dump(exclude_none=True, by_alias=True)
    )

replace_schema_enforcement ¶

replace_schema_enforcement(
    params: ReplaceSchemaEnforcementParams,
) -> dict[str, Any]

Fully replace enforcement configuration.

PARAMETER	DESCRIPTION
`params`	Complete replacement parameters. TYPE: `ReplaceSchemaEnforcementParams`

RETURNS	DESCRIPTION
`dict[str, Any]`	Raw API response as dict.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).

Example

ws = Workspace()
ws.replace_schema_enforcement(ReplaceSchemaEnforcementParams(
    events=[...], common_properties=[...],
    user_properties=[...], rule_event="Warn and Hide",
    notification_emails=["admin@example.com"],
))

Source code in src/mixpanel_headless/workspace.py

def replace_schema_enforcement(
    self,
    params: ReplaceSchemaEnforcementParams,
) -> dict[str, Any]:
    """Fully replace enforcement configuration.

    Args:
        params: Complete replacement parameters.

    Returns:
        Raw API response as dict.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).

    Example:
        ```python
        ws = Workspace()
        ws.replace_schema_enforcement(ReplaceSchemaEnforcementParams(
            events=[...], common_properties=[...],
            user_properties=[...], rule_event="Warn and Hide",
            notification_emails=["admin@example.com"],
        ))
        ```
    """
    client = self._require_api_client()
    return client.replace_schema_enforcement(
        params.model_dump(exclude_none=True, by_alias=True)
    )

delete_schema_enforcement ¶

delete_schema_enforcement() -> dict[str, Any]

Delete enforcement configuration.

RETURNS	DESCRIPTION
`dict[str, Any]`	Raw API response as dict.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	No enforcement configured (404).

Example

ws = Workspace()
ws.delete_schema_enforcement()

Source code in src/mixpanel_headless/workspace.py

def delete_schema_enforcement(self) -> dict[str, Any]:
    """Delete enforcement configuration.

    Returns:
        Raw API response as dict.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: No enforcement configured (404).

    Example:
        ```python
        ws = Workspace()
        ws.delete_schema_enforcement()
        ```
    """
    client = self._require_api_client()
    return client.delete_schema_enforcement()

run_audit ¶

run_audit() -> AuditResponse

Run a full data audit (events + properties).

RETURNS	DESCRIPTION
`AuditResponse`	Audit response with violations and `computed_at` timestamp.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	No schemas defined (400).

Example

ws = Workspace()
audit = ws.run_audit()
for v in audit.violations:
    print(f"{v.violation}: {v.name} ({v.count})")

Source code in src/mixpanel_headless/workspace.py

def run_audit(self) -> AuditResponse:
    """Run a full data audit (events + properties).

    Returns:
        Audit response with violations and ``computed_at`` timestamp.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: No schemas defined (400).

    Example:
        ```python
        ws = Workspace()
        audit = ws.run_audit()
        for v in audit.violations:
            print(f"{v.violation}: {v.name} ({v.count})")
        ```
    """
    client = self._require_api_client()
    raw = client.run_audit()
    # raw is [violations_list, {"computed_at": ...}]
    if not raw:
        return AuditResponse(violations=[], computed_at="")
    if not isinstance(raw[0], list):
        raise MixpanelHeadlessError(
            f"Unexpected audit response: expected list of violations, "
            f"got {type(raw[0]).__name__}",
        )
    violations = validate_response_models(
        AuditViolation, raw[0], endpoint="run_audit"
    )
    metadata = raw[1] if len(raw) > 1 and isinstance(raw[1], dict) else {}
    return AuditResponse(
        violations=violations,
        computed_at=metadata.get("computed_at", ""),
    )

run_audit_events_only ¶

run_audit_events_only() -> AuditResponse

Run an events-only data audit (faster).

RETURNS	DESCRIPTION
`AuditResponse`	Audit response with event violations only.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	No schemas defined (400).

Example

ws = Workspace()
audit = ws.run_audit_events_only()

Source code in src/mixpanel_headless/workspace.py

def run_audit_events_only(self) -> AuditResponse:
    """Run an events-only data audit (faster).

    Returns:
        Audit response with event violations only.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: No schemas defined (400).

    Example:
        ```python
        ws = Workspace()
        audit = ws.run_audit_events_only()
        ```
    """
    client = self._require_api_client()
    raw = client.run_audit_events_only()
    if not raw:
        return AuditResponse(violations=[], computed_at="")
    if not isinstance(raw[0], list):
        raise MixpanelHeadlessError(
            f"Unexpected audit response: expected list of violations, "
            f"got {type(raw[0]).__name__}",
        )
    violations = validate_response_models(
        AuditViolation, raw[0], endpoint="run_audit_events_only"
    )
    metadata = raw[1] if len(raw) > 1 and isinstance(raw[1], dict) else {}
    return AuditResponse(
        violations=violations,
        computed_at=metadata.get("computed_at", ""),
    )

list_data_volume_anomalies ¶

list_data_volume_anomalies(
    *, query_params: dict[str, str] | None = None
) -> list[DataVolumeAnomaly]

List detected data volume anomalies.

PARAMETER	DESCRIPTION
`query_params`	Optional filters (status, limit, event_id, etc.). TYPE: `dict[str, str] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`list[DataVolumeAnomaly]`	List of `DataVolumeAnomaly` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).

Example

ws = Workspace()
anomalies = ws.list_data_volume_anomalies(
    query_params={"status": "open"}
)

Source code in src/mixpanel_headless/workspace.py

def list_data_volume_anomalies(
    self,
    *,
    query_params: dict[str, str] | None = None,
) -> list[DataVolumeAnomaly]:
    """List detected data volume anomalies.

    Args:
        query_params: Optional filters (status, limit, event_id, etc.).

    Returns:
        List of ``DataVolumeAnomaly`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).

    Example:
        ```python
        ws = Workspace()
        anomalies = ws.list_data_volume_anomalies(
            query_params={"status": "open"}
        )
        ```
    """
    client = self._require_api_client()
    raw_list = client.list_data_volume_anomalies(query_params=query_params)
    return validate_response_models(
        DataVolumeAnomaly, raw_list, endpoint="list_data_volume_anomalies"
    )

update_anomaly ¶

update_anomaly(params: UpdateAnomalyParams) -> dict[str, Any]

Update the status of a single anomaly.

PARAMETER	DESCRIPTION
`params`	Update parameters with id, status, and anomaly_class. TYPE: `UpdateAnomalyParams`

RETURNS	DESCRIPTION
`dict[str, Any]`	Raw API response as dict.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Anomaly not found or invalid parameters (400).

Example

ws = Workspace()
ws.update_anomaly(UpdateAnomalyParams(
    id=123, status="dismissed", anomaly_class="Event"
))

Source code in src/mixpanel_headless/workspace.py

def update_anomaly(
    self,
    params: UpdateAnomalyParams,
) -> dict[str, Any]:
    """Update the status of a single anomaly.

    Args:
        params: Update parameters with id, status, and anomaly_class.

    Returns:
        Raw API response as dict.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Anomaly not found or invalid parameters (400).

    Example:
        ```python
        ws = Workspace()
        ws.update_anomaly(UpdateAnomalyParams(
            id=123, status="dismissed", anomaly_class="Event"
        ))
        ```
    """
    client = self._require_api_client()
    return client.update_anomaly(params.model_dump(by_alias=True))

bulk_update_anomalies ¶

bulk_update_anomalies(params: BulkUpdateAnomalyParams) -> dict[str, Any]

Bulk update anomaly statuses.

PARAMETER	DESCRIPTION
`params`	Bulk update with anomalies list and target status. TYPE: `BulkUpdateAnomalyParams`

RETURNS	DESCRIPTION
`dict[str, Any]`	Raw API response as dict.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid parameters (400).

Example

ws = Workspace()
ws.bulk_update_anomalies(BulkUpdateAnomalyParams(
    anomalies=[BulkAnomalyEntry(id=1, anomaly_class="Event")],
    status="dismissed",
))

Source code in src/mixpanel_headless/workspace.py

def bulk_update_anomalies(
    self,
    params: BulkUpdateAnomalyParams,
) -> dict[str, Any]:
    """Bulk update anomaly statuses.

    Args:
        params: Bulk update with anomalies list and target status.

    Returns:
        Raw API response as dict.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid parameters (400).

    Example:
        ```python
        ws = Workspace()
        ws.bulk_update_anomalies(BulkUpdateAnomalyParams(
            anomalies=[BulkAnomalyEntry(id=1, anomaly_class="Event")],
            status="dismissed",
        ))
        ```
    """
    client = self._require_api_client()
    return client.bulk_update_anomalies(params.model_dump(by_alias=True))

list_deletion_requests ¶

list_deletion_requests() -> list[EventDeletionRequest]

List all event deletion requests.

RETURNS	DESCRIPTION
`list[EventDeletionRequest]`	List of `EventDeletionRequest` objects.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).

Example

ws = Workspace()
for r in ws.list_deletion_requests():
    print(f"{r.event_name}: {r.status}")

Source code in src/mixpanel_headless/workspace.py

def list_deletion_requests(self) -> list[EventDeletionRequest]:
    """List all event deletion requests.

    Returns:
        List of ``EventDeletionRequest`` objects.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).

    Example:
        ```python
        ws = Workspace()
        for r in ws.list_deletion_requests():
            print(f"{r.event_name}: {r.status}")
        ```
    """
    client = self._require_api_client()
    raw_list = client.list_deletion_requests()
    return validate_response_models(
        EventDeletionRequest, raw_list, endpoint="list_deletion_requests"
    )

create_deletion_request ¶

create_deletion_request(
    params: CreateDeletionRequestParams,
) -> list[EventDeletionRequest]

Create a new event deletion request.

PARAMETER	DESCRIPTION
`params`	Deletion parameters with event_name, from_date, to_date, and optional filters. TYPE: `CreateDeletionRequestParams`

RETURNS	DESCRIPTION
`list[EventDeletionRequest]`	Updated full list of deletion requests.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Validation error (400).

Example

ws = Workspace()
requests = ws.create_deletion_request(
    CreateDeletionRequestParams(
        event_name="Test", from_date="2026-01-01",
        to_date="2026-01-31",
    )
)

Source code in src/mixpanel_headless/workspace.py

def create_deletion_request(
    self,
    params: CreateDeletionRequestParams,
) -> list[EventDeletionRequest]:
    """Create a new event deletion request.

    Args:
        params: Deletion parameters with event_name, from_date,
            to_date, and optional filters.

    Returns:
        Updated full list of deletion requests.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Validation error (400).

    Example:
        ```python
        ws = Workspace()
        requests = ws.create_deletion_request(
            CreateDeletionRequestParams(
                event_name="Test", from_date="2026-01-01",
                to_date="2026-01-31",
            )
        )
        ```
    """
    client = self._require_api_client()
    raw_list = client.create_deletion_request(
        params.model_dump(exclude_none=True, by_alias=True)
    )
    return validate_response_models(
        EventDeletionRequest, raw_list, endpoint="create_deletion_request"
    )

cancel_deletion_request ¶

cancel_deletion_request(request_id: int) -> list[EventDeletionRequest]

Cancel a pending deletion request.

PARAMETER	DESCRIPTION
`request_id`	Deletion request ID to cancel. TYPE: `int`

RETURNS	DESCRIPTION
`list[EventDeletionRequest]`	Updated full list of deletion requests.

RAISES	DESCRIPTION
`ResponseValidationError`	Malformed API response payload (`RESPONSE_VALIDATION_ERROR`).
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Request not found or not cancellable (400).

Example

ws = Workspace()
requests = ws.cancel_deletion_request(42)

Source code in src/mixpanel_headless/workspace.py

def cancel_deletion_request(self, request_id: int) -> list[EventDeletionRequest]:
    """Cancel a pending deletion request.

    Args:
        request_id: Deletion request ID to cancel.

    Returns:
        Updated full list of deletion requests.

    Raises:
        ResponseValidationError: Malformed API response payload
            (``RESPONSE_VALIDATION_ERROR``).
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Request not found or not cancellable (400).

    Example:
        ```python
        ws = Workspace()
        requests = ws.cancel_deletion_request(42)
        ```
    """
    client = self._require_api_client()
    raw_list = client.cancel_deletion_request(request_id)
    return validate_response_models(
        EventDeletionRequest, raw_list, endpoint="cancel_deletion_request"
    )

preview_deletion_filters ¶

preview_deletion_filters(
    params: PreviewDeletionFiltersParams,
) -> list[dict[str, Any]]

Preview what events a deletion filter would match.

This is a read-only operation that does not modify any data.

PARAMETER	DESCRIPTION
`params`	Preview parameters with event_name, date range, and optional filters. TYPE: `PreviewDeletionFiltersParams`

RETURNS	DESCRIPTION
`list[dict[str, Any]]`	List of expanded/normalized filters.

RAISES	DESCRIPTION
`ConfigError`	If credentials are not available.
`AuthenticationError`	Invalid credentials (401).
`QueryError`	Invalid filter parameters (400).

Example

ws = Workspace()
preview = ws.preview_deletion_filters(
    PreviewDeletionFiltersParams(
        event_name="Test", from_date="2026-01-01",
        to_date="2026-01-31",
    )
)

Source code in src/mixpanel_headless/workspace.py

def preview_deletion_filters(
    self,
    params: PreviewDeletionFiltersParams,
) -> list[dict[str, Any]]:
    """Preview what events a deletion filter would match.

    This is a read-only operation that does not modify any data.

    Args:
        params: Preview parameters with event_name, date range,
            and optional filters.

    Returns:
        List of expanded/normalized filters.

    Raises:
        ConfigError: If credentials are not available.
        AuthenticationError: Invalid credentials (401).
        QueryError: Invalid filter parameters (400).

    Example:
        ```python
        ws = Workspace()
        preview = ws.preview_deletion_filters(
            PreviewDeletionFiltersParams(
                event_name="Test", from_date="2026-01-01",
                to_date="2026-01-31",
            )
        )
        ```
    """
    client = self._require_api_client()
    return client.preview_deletion_filters(
        params.model_dump(exclude_none=True, by_alias=True)
    )

Workspace¶

Overview¶

Key Features¶

Entity CRUD¶

Feature Flags & Experiments¶

Data Governance¶

Saved Metrics & Behaviors¶

Business Context¶

Session Replay¶

Report Links¶

In-Session Switching¶

Class Reference¶

mixpanel_headless.Workspace ¶

account property ¶

project property ¶

workspace property ¶

session property ¶

api property ¶

close ¶

use ¶

me ¶

projects ¶

workspaces ¶

list_workspaces ¶

resolve_workspace_id ¶

events ¶

properties ¶

property_values ¶

subproperties ¶

funnels ¶

cohorts ¶

list_bookmarks ¶

top_events ¶

lexicon_schemas ¶

lexicon_schema ¶

schema_graph ¶

clear_discovery_cache ¶

stream_events ¶

stream_profiles ¶

get_business_context ¶

set_business_context ¶

clear_business_context ¶

get_business_context_chain ¶

query ¶

build_params ¶

run_params ¶

query_funnel ¶

build_funnel_params ¶

run_funnel_params ¶

query_retention ¶

build_retention_params ¶

run_retention_params ¶

query_flow ¶

build_flow_params ¶

run_flow_params ¶

query_user ¶

build_user_params ¶

run_user_params ¶

segmentation ¶

funnel ¶

retention ¶

event_counts ¶

property_counts ¶

activity_feed ¶

query_saved_report ¶

query_saved_flows ¶

frequency ¶

segmentation_numeric ¶

segmentation_sum ¶

segmentation_average ¶

list_dashboards ¶

create_dashboard ¶

get_dashboard ¶

update_dashboard ¶

delete_dashboard ¶

bulk_delete_dashboards ¶

favorite_dashboard ¶

unfavorite_dashboard ¶

pin_dashboard ¶

unpin_dashboard ¶

account `property` ¶

project `property` ¶

workspace `property` ¶

session `property` ¶

api `property` ¶