Workspace¶
The Workspace class is the unified entry point for all Mixpanel data operations.
Explore on DeepWiki
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 >
[active] > Account.default_project. Pass session= to
bypass the resolver and use a pre-built :class:Session directly.
| PARAMETER | DESCRIPTION |
|---|---|
account
|
Named account from
TYPE:
|
project
|
Project ID override (digit string).
TYPE:
|
workspace
|
Workspace ID override (positive int).
TYPE:
|
target
|
Apply all three axes from
TYPE:
|
session
|
Pre-built :class:
TYPE:
|
_api_client
|
Injected :class:
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
|
ConfigError
|
Account or project axis cannot be resolved. |
OAuthError
|
Auth header construction fails. |
Source code in src/mixpanel_headless/workspace.py
workspace
property
¶
Return the resolved :class:WorkspaceRef (or None for lazy).
api
property
¶
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 all resources (HTTP client).
This method is idempotent and safe to call multiple times.
Source code in src/mixpanel_headless/workspace.py
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:
|
project
|
Replacement project ID.
TYPE:
|
workspace
|
Replacement workspace ID.
TYPE:
|
target
|
Apply this target's three axes atomically.
TYPE:
|
persist
|
When
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Workspace
|
|
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
Mutually exclusive args
( |
ValueError
|
Referenced name missing. |
OAuthError
|
New auth header construction fails (atomic on success). |
ConfigError
|
|
Source code in src/mixpanel_headless/workspace.py
758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 | |
me
¶
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:
|
| 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
Source code in src/mixpanel_headless/workspace.py
projects
¶
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
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Project]
|
List of :class: |
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials lack /me access. |
Example
Source code in src/mixpanel_headless/workspace.py
workspaces
¶
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:
|
refresh
|
When True, bypass the on-disk and in-memory
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[WorkspaceRef]
|
List of :class: |
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials lack /me access. |
Example
Source code in src/mixpanel_headless/workspace.py
list_workspaces
¶
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 |
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400, 404). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
resolve_workspace_id
¶
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, 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. |
Source code in src/mixpanel_headless/workspace.py
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:
|
from_date
|
TYPE:
|
to_date
|
TYPE:
|
| 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 |
Source code in src/mixpanel_headless/workspace.py
properties
¶
List the property names of an event that this account can query.
Results are cached per event for the lifetime of the Workspace.
When the account cannot read classified data, the classified
properties are left out, because a query on one of them fails. A
UserWarning then names the left-out properties (also on a cached
call). An account with access to classified data gets every property.
| PARAMETER | DESCRIPTION |
|---|---|
event
|
Event name to get properties for.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[str]
|
Alphabetically sorted list of property names. |
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If API credentials not available. |
EventNotFoundError
|
The server rejected the event name (400). The error lists similar names. An event that the project does not track is not rejected. The call returns an empty list for it. |
Example
Source code in src/mixpanel_headless/workspace.py
property_values
¶
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:
|
event
|
Optional event to filter by.
TYPE:
|
limit
|
Maximum number of values to return.
TYPE:
|
| 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
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.
TYPE:
|
event
|
Optional event name to scope the sample. Strongly recommended; without it the API may return values from across all events.
TYPE:
|
sample_size
|
Number of raw values to sample. Default: 50.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[SubPropertyInfo]
|
Alphabetically sorted list of :class: |
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 |
Example
Source code in src/mixpanel_headless/workspace.py
funnels
¶
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
cohorts
¶
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
list_bookmarks
¶
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:
|
| 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
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:
|
limit
|
Maximum number of events to return.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[TopEvent]
|
List of TopEvent objects with |
list[TopEvent]
|
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If API credentials not available. |
Example
Source code in src/mixpanel_headless/workspace.py
lexicon_schemas
¶
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:
|
| 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
lexicon_schema
¶
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:
|
name
|
Entity name.
TYPE:
|
| 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
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 (
TYPE:
|
include_user_properties
|
Also gather user properties.
TYPE:
|
force_refresh
|
Bypass the cache and re-fetch.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
A
|
class:
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If API credentials are not available. |
AuthenticationError
|
If credentials are invalid. |
Example
Source code in src/mixpanel_headless/workspace.py
clear_discovery_cache
¶
Clear cached discovery results.
Subsequent discovery calls will fetch fresh data from the API.
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:
|
to_date
|
End date inclusive (YYYY-MM-DD format).
TYPE:
|
events
|
Optional list of event names to filter. If None, all events returned.
TYPE:
|
where
|
Optional Mixpanel filter expression (e.g., 'properties["country"]=="US"').
TYPE:
|
limit
|
Optional maximum number of events to return (max 100000).
TYPE:
|
raw
|
If True, return events in raw Mixpanel API format. If False (default), return normalized format with datetime objects.
TYPE:
|
| 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
|
Rate limit exceeded (429), when the retries run out
or at once when |
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:
Source code in src/mixpanel_headless/workspace.py
1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 | |
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:
|
cohort_id
|
Optional cohort ID to filter by. Only profiles that are members of this cohort will be returned.
TYPE:
|
output_properties
|
Optional list of property names to include in the response. If None, all properties are returned.
TYPE:
|
raw
|
If True, return profiles in raw Mixpanel API format. If False (default), return normalized format.
TYPE:
|
distinct_id
|
Optional single user ID to fetch. Mutually exclusive with distinct_ids.
TYPE:
|
distinct_ids
|
Optional list of user IDs to fetch. Mutually exclusive with distinct_id. Duplicates are automatically removed.
TYPE:
|
group_id
|
Optional group type identifier (e.g., "companies") to fetch group profiles instead of user profiles.
TYPE:
|
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
TYPE:
|
as_of_timestamp
|
Optional Unix timestamp to query profile state at a specific point in time. Must be in the past.
TYPE:
|
include_all_users
|
If True, include all users and mark cohort membership. Only valid when cohort_id is provided.
TYPE:
|
| 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
|
Rate limit exceeded (429), when the retries run out
or at once when |
ValueError
|
If mutually exclusive parameters are provided. |
Example
Filter to premium users:
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:
Fetch group profiles:
Source code in src/mixpanel_headless/workspace.py
1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 | |
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
|
TYPE:
|
organization_id
|
Optional explicit org ID, only honored
when
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BusinessContext
|
|
BusinessContext
|
current state. |
BusinessContext
|
org-level returns; |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
|
ConfigError
|
Credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400, 403, 404). |
ServerError
|
Server-side errors (5xx). |
WorkspaceScopeError
|
|
MixpanelHeadlessError
|
API response is missing the |
Example
Source code in src/mixpanel_headless/workspace.py
12260 12261 12262 12263 12264 12265 12266 12267 12268 12269 12270 12271 12272 12273 12274 12275 12276 12277 12278 12279 12280 12281 12282 12283 12284 12285 12286 12287 12288 12289 12290 12291 12292 12293 12294 12295 12296 12297 12298 12299 12300 12301 12302 12303 12304 12305 12306 12307 12308 12309 12310 12311 12312 12313 12314 12315 12316 12317 12318 12319 12320 12321 12322 12323 12324 12325 12326 12327 12328 12329 12330 12331 12332 12333 12334 | |
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:
|
level
|
TYPE:
|
organization_id
|
Optional explicit org ID, only honored
when
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BusinessContext
|
|
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
|
BusinessContextValidationError
|
|
ConfigError
|
Credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Caller lacks |
ServerError
|
Server-side errors (5xx). |
WorkspaceScopeError
|
|
MixpanelHeadlessError
|
API response is missing the |
Example
Source code in src/mixpanel_headless/workspace.py
12336 12337 12338 12339 12340 12341 12342 12343 12344 12345 12346 12347 12348 12349 12350 12351 12352 12353 12354 12355 12356 12357 12358 12359 12360 12361 12362 12363 12364 12365 12366 12367 12368 12369 12370 12371 12372 12373 12374 12375 12376 12377 12378 12379 12380 12381 12382 12383 12384 12385 12386 12387 12388 12389 12390 12391 12392 12393 12394 12395 12396 12397 12398 12399 12400 12401 12402 12403 12404 12405 12406 12407 12408 12409 12410 12411 12412 12413 12414 12415 12416 12417 12418 12419 12420 12421 | |
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
|
TYPE:
|
organization_id
|
Optional explicit org ID for
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BusinessContext
|
|
BusinessContext
|
echoed back from the server). |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
|
ConfigError
|
Credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Caller lacks |
ServerError
|
Server-side errors (5xx). |
WorkspaceScopeError
|
|
Source code in src/mixpanel_headless/workspace.py
get_business_context_chain
¶
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
|
|
BusinessContextChain
|
context is set at that scope. |
BusinessContextChain
|
|
BusinessContextChain
|
|
| 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 |
Example
Source code in src/mixpanel_headless/workspace.py
12467 12468 12469 12470 12471 12472 12473 12474 12475 12476 12477 12478 12479 12480 12481 12482 12483 12484 12485 12486 12487 12488 12489 12490 12491 12492 12493 12494 12495 12496 12497 12498 12499 12500 12501 12502 12503 12504 12505 12506 12507 12508 12509 12510 12511 12512 12513 12514 12515 12516 12517 12518 12519 12520 12521 12522 12523 12524 12525 12526 12527 12528 | |
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
TYPE:
|
from_date
|
Start date (YYYY-MM-DD). If set, overrides
TYPE:
|
to_date
|
End date (YYYY-MM-DD). Requires
TYPE:
|
last
|
Relative time range in days. Default: 30.
Ignored if
TYPE:
|
unit
|
Time aggregation unit. Default:
TYPE:
|
math
|
Aggregation function for plain-string events.
Default:
TYPE:
|
math_property
|
Property name for property-based math (average, sum, percentiles).
TYPE:
|
per_user
|
Per-user pre-aggregation (average, total, min, max).
TYPE:
|
percentile_value
|
Custom percentile value (e.g. 95 for p95).
Required when
TYPE:
|
group_by
|
Break down results by property or cohort membership.
Accepts a string,
TYPE:
|
where
|
Filter results by conditions. Accepts a Filter, a
FrequencyFilter, or a list mixing both. A
TYPE:
|
formula
|
Formula expression referencing events by position
(A, B, C...). Requires 2+ events. Cannot be combined
with Formula objects in
TYPE:
|
formula_label
|
Display label for formula result.
TYPE:
|
rolling
|
Rolling window size in periods.
Mutually exclusive with
TYPE:
|
cumulative
|
Enable cumulative analysis mode.
Mutually exclusive with
TYPE:
|
mode
|
Result shape.
TYPE:
|
time_comparison
|
Optional period-over-period comparison.
Use
TYPE:
|
data_group_id
|
Optional data group ID for group-level
analytics. Scopes the query to a specific data group.
Default:
TYPE:
|
limit
|
Segments to return, 1 to 50000. Default
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
QueryResult
|
QueryResult with series data, DataFrame, and metadata. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
If arguments violate validation rules. |
ParamValidationError
|
|
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
2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 | |
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
TYPE:
|
from_date
|
Start date (YYYY-MM-DD). If set, overrides
TYPE:
|
to_date
|
End date (YYYY-MM-DD). Requires
TYPE:
|
last
|
Relative time range in days. Default: 30.
TYPE:
|
unit
|
Time aggregation unit. Default:
TYPE:
|
math
|
Aggregation function for plain-string events.
Default:
TYPE:
|
math_property
|
Property name for property-based math.
TYPE:
|
per_user
|
Per-user pre-aggregation.
TYPE:
|
percentile_value
|
Custom percentile value (e.g. 95).
Required when
TYPE:
|
group_by
|
Break down results by property or cohort membership.
Accepts a string,
TYPE:
|
where
|
Filter results by conditions. A
TYPE:
|
formula
|
Formula expression referencing events by position.
TYPE:
|
formula_label
|
Display label for formula result.
TYPE:
|
rolling
|
Rolling window size in periods.
TYPE:
|
cumulative
|
Enable cumulative analysis mode.
TYPE:
|
mode
|
Result shape. Default:
TYPE:
|
time_comparison
|
Optional period-over-period comparison.
Use
TYPE:
|
data_group_id
|
Optional data group ID for group-level
analytics. Scopes the query to a specific data group.
Default:
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any]
|
Bookmark params dict with |
dict[str, Any]
|
keys, ready for use with the insights API or |
dict[str, Any]
|
meth: |
| RAISES | DESCRIPTION |
|---|---|
BookmarkValidationError
|
If arguments violate validation rules. |
ParamValidationError
|
|
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
2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 | |
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:
TYPE:
|
limit
|
Segments to return, 1 to 50000. Default
TYPE:
|
workspace_id
|
Optional data view to run under. Wins over the pinned session workspace.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
QueryResult
|
QueryResult with series data, DataFrame, and metadata. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
|
AuthenticationError
|
Invalid credentials. |
QueryError
|
Invalid bookmark params. |
RateLimitError
|
Rate limit exceeded. |
Example
Source code in src/mixpanel_headless/workspace.py
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
TYPE:
|
conversion_window
|
How long users have to complete the funnel. Default: 14.
TYPE:
|
conversion_window_unit
|
Time unit for conversion window.
Default:
TYPE:
|
order
|
Step ordering mode.
TYPE:
|
from_date
|
Start date (YYYY-MM-DD). If set, overrides
TYPE:
|
to_date
|
End date (YYYY-MM-DD). Requires
TYPE:
|
last
|
Relative time range in days. Default: 30.
TYPE:
|
unit
|
Time aggregation unit. Default:
TYPE:
|
math
|
Funnel aggregation function. Default:
TYPE:
|
math_property
|
Numeric property name for property-aggregation
math types (
TYPE:
|
group_by
|
Break down results by property or cohort
membership. Accepts a string,
TYPE:
|
where
|
Filter results by conditions. |
exclusions
|
Events to exclude between steps. Accepts
event name strings or
TYPE:
|
holding_constant
|
Properties to hold constant across
steps. Accepts strings,
TYPE:
|
mode
|
Result display mode.
TYPE:
|
reentry_mode
|
Funnel reentry mode controlling how users
re-enter the funnel after conversion. One of
TYPE:
|
time_comparison
|
Optional period-over-period comparison.
Use
TYPE:
|
data_group_id
|
Optional data group ID for group-level
analytics. Scopes the query to a specific data group.
Default:
TYPE:
|
limit
|
Segments to return, 1 to 50000. Default
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
FunnelQueryResult
|
FunnelQueryResult with step data, DataFrame, and metadata. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
|
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
3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 | |
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
TYPE:
|
conversion_window
|
Conversion window size. Default: 14.
TYPE:
|
conversion_window_unit
|
Time unit. Default:
TYPE:
|
order
|
Step ordering mode. Default:
TYPE:
|
from_date
|
Start date (YYYY-MM-DD) or None.
TYPE:
|
to_date
|
End date (YYYY-MM-DD) or None.
TYPE:
|
last
|
Relative time range in days. Default: 30.
TYPE:
|
unit
|
Time aggregation unit. Default:
TYPE:
|
math
|
Aggregation function. Default:
TYPE:
|
math_property
|
Numeric property name for property-aggregation
math types. Required for
TYPE:
|
group_by
|
Break down results by property or cohort
membership. Accepts a string,
TYPE:
|
where
|
Filter results by conditions. |
exclusions
|
Events to exclude between steps.
TYPE:
|
holding_constant
|
Properties to hold constant.
TYPE:
|
mode
|
Display mode. Default:
TYPE:
|
reentry_mode
|
Funnel reentry mode controlling how users
re-enter the funnel after conversion. One of
TYPE:
|
time_comparison
|
Optional period-over-period comparison.
Use
TYPE:
|
data_group_id
|
Optional data group ID for group-level
analytics. Scopes the query to a specific data group.
Default:
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any]
|
Bookmark params dict with |
dict[str, Any]
|
|
| 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
3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 | |
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:
TYPE:
|
limit
|
Segments to return, 1 to 50000. Default
TYPE:
|
workspace_id
|
Optional data view to run under. Wins over the pinned session workspace.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
FunnelQueryResult
|
FunnelQueryResult with step data, DataFrame, and metadata. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
|
AuthenticationError
|
Invalid credentials. |
QueryError
|
Invalid bookmark params. |
RateLimitError
|
Rate limit exceeded. |
Example
Source code in src/mixpanel_headless/workspace.py
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
TYPE:
|
return_event
|
Event that defines return. Accepts an event
name string or a
TYPE:
|
retention_unit
|
Retention period unit. Default:
TYPE:
|
alignment
|
Retention alignment mode. Default:
TYPE:
|
bucket_sizes
|
Custom bucket sizes (positive ints in
ascending order). Default:
TYPE:
|
from_date
|
Start date (YYYY-MM-DD). If set, overrides
TYPE:
|
to_date
|
End date (YYYY-MM-DD). Requires
TYPE:
|
last
|
Relative time range in days. Default: 30.
TYPE:
|
unit
|
Time aggregation unit (
TYPE:
|
math
|
Retention aggregation function. Default:
TYPE:
|
group_by
|
Break down results by property or cohort
membership. Accepts a string,
TYPE:
|
where
|
Filter results by conditions. |
mode
|
Result display mode. Default:
TYPE:
|
unbounded_mode
|
Retention unbounded mode controlling how
retention is counted in unbounded periods. One of
TYPE:
|
retention_cumulative
|
Whether to use cumulative retention
counting. Default:
TYPE:
|
time_comparison
|
Optional period-over-period comparison.
Use
TYPE:
|
data_group_id
|
Optional data group ID for group-level
analytics. Scopes the query to a specific data group.
Default:
TYPE:
|
limit
|
Segments to return, 1 to 50000. Default
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
RetentionQueryResult
|
RetentionQueryResult with cohort data, DataFrame, and |
RetentionQueryResult
|
metadata. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
|
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
4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 4865 4866 4867 4868 4869 4870 4871 4872 4873 4874 4875 | |
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
TYPE:
|
return_event
|
Event that defines return. Required unless
TYPE:
|
retention_unit
|
Retention period unit. Default:
TYPE:
|
alignment
|
Retention alignment mode. Default:
TYPE:
|
bucket_sizes
|
Custom bucket sizes. Default:
TYPE:
|
from_date
|
Start date (YYYY-MM-DD) or None.
TYPE:
|
to_date
|
End date (YYYY-MM-DD) or None.
TYPE:
|
last
|
Relative time range in days. Default: 30.
TYPE:
|
unit
|
Time aggregation unit (
TYPE:
|
math
|
Aggregation function. Default:
TYPE:
|
group_by
|
Break down results by property or cohort
membership. Accepts a string,
TYPE:
|
where
|
Filter results by conditions. |
mode
|
Display mode. Default:
TYPE:
|
unbounded_mode
|
Retention unbounded mode controlling how
retention is counted in unbounded periods. One of
TYPE:
|
retention_cumulative
|
Whether to use cumulative retention
counting. Default:
TYPE:
|
time_comparison
|
Optional period-over-period comparison.
Use
TYPE:
|
data_group_id
|
Optional data group ID for group-level
analytics. Scopes the query to a specific data group.
Default:
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any]
|
Bookmark params dict with |
dict[str, Any]
|
|
| 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
4920 4921 4922 4923 4924 4925 4926 4927 4928 4929 4930 4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 4945 4946 4947 4948 4949 4950 4951 4952 4953 4954 4955 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 5014 5015 5016 5017 5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 | |
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:
TYPE:
|
limit
|
Segments to return, 1 to 50000. Default
TYPE:
|
workspace_id
|
Optional data view to run under. Wins over the pinned session workspace.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
RetentionQueryResult
|
RetentionQueryResult with cohort data, DataFrame, and |
RetentionQueryResult
|
metadata. |
| RAISES | DESCRIPTION |
|---|---|
ValueError
|
|
AuthenticationError
|
Invalid credentials. |
QueryError
|
Invalid bookmark params. |
RateLimitError
|
Rate limit exceeded. |
Example
Source code in src/mixpanel_headless/workspace.py
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 |
forward
|
Default number of forward steps to trace from
each anchor event. Overridden by per-step values.
Default:
TYPE:
|
reverse
|
Default number of reverse steps to trace from
each anchor event. Overridden by per-step values.
Default:
TYPE:
|
from_date
|
Start date (YYYY-MM-DD). If set, overrides
TYPE:
|
to_date
|
End date (YYYY-MM-DD). Requires
TYPE:
|
last
|
Relative time range in days. Default: 30.
TYPE:
|
conversion_window
|
Conversion window size. Default: 7.
TYPE:
|
conversion_window_unit
|
Conversion window unit.
Default:
TYPE:
|
count_type
|
Counting method for flow analysis.
Default:
TYPE:
|
cardinality
|
Number of top paths to display.
Default:
TYPE:
|
collapse_repeated
|
Whether to merge consecutive repeated
events. Default:
TYPE:
|
hidden_events
|
Events to hide from the flow visualization.
Default:
TYPE:
|
mode
|
Flow visualization mode. Default:
TYPE:
|
where
|
Filter results by cohort membership or property
conditions. Cohort filters ( |
data_group_id
|
Optional data group ID for group-level
analytics. Scopes the query to a specific data group.
Default:
TYPE:
|
segments
|
Segment (breakdown) specification for flow
results. Accepts a string,
TYPE:
|
exclusions
|
List of event names to exclude from flow
paths. Default:
TYPE:
|
| 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
4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 | |
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 |
forward
|
Default forward step count. Default:
TYPE:
|
reverse
|
Default reverse step count. Default:
TYPE:
|
from_date
|
Start date (YYYY-MM-DD) or
TYPE:
|
to_date
|
End date (YYYY-MM-DD) or
TYPE:
|
last
|
Relative time range in days. Default: 30.
TYPE:
|
conversion_window
|
Conversion window size. Default: 7.
TYPE:
|
conversion_window_unit
|
Conversion window unit.
Default:
TYPE:
|
count_type
|
Counting method. Default:
TYPE:
|
cardinality
|
Number of top paths. Default:
TYPE:
|
collapse_repeated
|
Merge repeated events. Default:
TYPE:
|
hidden_events
|
Events to hide. Default:
TYPE:
|
mode
|
Display mode. Default:
TYPE:
|
where
|
Filter results by cohort membership or property
conditions. Cohort filters produce |
data_group_id
|
Optional data group ID for group-level
analytics. Scopes the query to a specific data group.
Default:
TYPE:
|
segments
|
Segment (breakdown) specification for flow
results. Accepts a string,
TYPE:
|
exclusions
|
List of event names to exclude from flow
paths. Default:
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any]
|
Flat bookmark params dict with |
dict[str, Any]
|
|
| RAISES | DESCRIPTION |
|---|---|
BookmarkValidationError
|
If arguments violate validation rules. |
Example
Source code in src/mixpanel_headless/workspace.py
4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 | |
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:
TYPE:
|
mode
|
Flow chart mode.
TYPE:
|
workspace_id
|
Optional data view to run under. Wins over the pinned session workspace.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
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
|
cohort
|
Filter by cohort membership. An
TYPE:
|
properties
|
Output properties to include in results.
TYPE:
|
sort_by
|
Property name to sort results by.
TYPE:
|
sort_order
|
Sort direction (
TYPE:
|
limit
|
Maximum profiles to return. Defaults to
TYPE:
|
search
|
Full-text search term applied to profile properties.
TYPE:
|
distinct_id
|
Look up a single user by distinct ID.
TYPE:
|
distinct_ids
|
Batch look up multiple users by distinct IDs.
TYPE:
|
group_id
|
Query group profiles instead of user profiles.
TYPE:
|
as_of
|
Point-in-time query. An ISO date string (
TYPE:
|
mode
|
Output mode (
TYPE:
|
aggregate
|
Aggregation function for aggregate mode. One of
TYPE:
|
aggregate_property
|
Property to aggregate on (required for non-count aggregations).
TYPE:
|
percentile
|
Percentile value (0-100 exclusive). Required
when
TYPE:
|
segment_by
|
Cohort IDs for segmented aggregation.
TYPE:
|
parallel
|
Whether to enable concurrent page fetching.
TYPE:
|
workers
|
Maximum concurrent workers for parallel fetching.
TYPE:
|
include_all_users
|
Include non-members in cohort query results.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
UserQueryResult
|
|
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
11507 11508 11509 11510 11511 11512 11513 11514 11515 11516 11517 11518 11519 11520 11521 11522 11523 11524 11525 11526 11527 11528 11529 11530 11531 11532 11533 11534 11535 11536 11537 11538 11539 11540 11541 11542 11543 11544 11545 11546 11547 11548 11549 11550 11551 11552 11553 11554 11555 11556 11557 11558 11559 11560 11561 11562 11563 11564 11565 11566 11567 11568 11569 11570 11571 11572 11573 11574 11575 11576 11577 11578 11579 11580 11581 11582 11583 11584 11585 11586 11587 11588 11589 11590 11591 11592 11593 11594 11595 11596 11597 11598 11599 11600 11601 11602 11603 11604 11605 11606 11607 11608 11609 11610 11611 11612 11613 11614 11615 11616 11617 11618 11619 11620 11621 11622 11623 11624 11625 11626 11627 11628 11629 11630 11631 11632 11633 11634 11635 11636 11637 11638 11639 11640 11641 11642 11643 11644 11645 11646 11647 11648 11649 11650 11651 | |
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
|
cohort
|
Filter by cohort membership. An
TYPE:
|
properties
|
Output properties to include in results.
TYPE:
|
sort_by
|
Property name to sort results by.
TYPE:
|
sort_order
|
Sort direction (
TYPE:
|
search
|
Full-text search term applied to profile properties.
TYPE:
|
distinct_id
|
Look up a single user by distinct ID.
TYPE:
|
distinct_ids
|
Batch look up multiple users by distinct IDs.
TYPE:
|
group_id
|
Query group profiles instead of user profiles.
TYPE:
|
as_of
|
Point-in-time query. An ISO date string (
TYPE:
|
mode
|
Output mode (
TYPE:
|
aggregate
|
Aggregation function for aggregate mode. One of
TYPE:
|
aggregate_property
|
Property to aggregate on (required for non-count aggregations).
TYPE:
|
percentile
|
Percentile value (0-100 exclusive). Required
when
TYPE:
|
segment_by
|
Cohort IDs for segmented aggregation.
TYPE:
|
limit
|
Maximum profiles to return. Defaults to
TYPE:
|
parallel
|
Whether to enable concurrent page fetching.
Accepted for signature compatibility with
TYPE:
|
workers
|
Maximum concurrent workers for parallel fetching.
Accepted for signature compatibility with
TYPE:
|
include_all_users
|
Include non-members in cohort query results.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, Any]
|
Engage API params dict. Does not include pagination params |
dict[str, Any]
|
( |
dict[str, Any]
|
execution time by |
| RAISES | DESCRIPTION |
|---|---|
BookmarkValidationError
|
If any validation rule fails at either the argument level (U1-U28) or the param level (UP1-UP4). |
Example
Source code in src/mixpanel_headless/workspace.py
11736 11737 11738 11739 11740 11741 11742 11743 11744 11745 11746 11747 11748 11749 11750 11751 11752 11753 11754 11755 11756 11757 11758 11759 11760 11761 11762 11763 11764 11765 11766 11767 11768 11769 11770 11771 11772 11773 11774 11775 11776 11777 11778 11779 11780 11781 11782 11783 11784 11785 11786 11787 11788 11789 11790 11791 11792 11793 11794 11795 11796 11797 11798 11799 11800 11801 11802 11803 11804 11805 11806 11807 11808 11809 11810 11811 11812 11813 11814 11815 11816 11817 11818 11819 11820 11821 11822 11823 11824 11825 11826 11827 11828 11829 11830 11831 11832 11833 11834 11835 11836 11837 11838 11839 11840 11841 11842 11843 11844 11845 11846 11847 11848 11849 11850 11851 | |
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:
TYPE:
|
limit
|
Maximum profiles to return in profiles mode.
TYPE:
|
parallel
|
Fetch profile pages concurrently. Ignored when
TYPE:
|
workers
|
Maximum concurrent workers for parallel fetching.
Default:
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
UserQueryResult
|
|
UserQueryResult
|
count, DataFrame, and execution metadata. |
| RAISES | DESCRIPTION |
|---|---|
AuthenticationError
|
Invalid credentials (401). |
RateLimitError
|
API rate limit exceeded (429). |
APIError
|
Other API communication errors. |
Example
Source code in src/mixpanel_headless/workspace.py
11653 11654 11655 11656 11657 11658 11659 11660 11661 11662 11663 11664 11665 11666 11667 11668 11669 11670 11671 11672 11673 11674 11675 11676 11677 11678 11679 11680 11681 11682 11683 11684 11685 11686 11687 11688 11689 11690 11691 11692 11693 11694 11695 11696 11697 11698 11699 11700 11701 11702 11703 11704 11705 11706 11707 11708 11709 11710 11711 11712 11713 11714 11715 11716 11717 11718 11719 11720 11721 11722 11723 11724 11725 11726 11727 11728 11729 11730 11731 11732 11733 11734 | |
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:
|
from_date
|
Start date (YYYY-MM-DD).
TYPE:
|
to_date
|
End date (YYYY-MM-DD).
TYPE:
|
on
|
Optional property to segment by.
TYPE:
|
unit
|
Time unit for aggregation.
TYPE:
|
where
|
Optional WHERE clause.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SegmentationResult
|
SegmentationResult with time-series data. |
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If API credentials not available. |
Source code in src/mixpanel_headless/workspace.py
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:
|
from_date
|
Start date (YYYY-MM-DD).
TYPE:
|
to_date
|
End date (YYYY-MM-DD).
TYPE:
|
unit
|
Optional time unit.
TYPE:
|
on
|
Optional property to segment by.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
FunnelResult
|
FunnelResult with step conversion rates. |
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If API credentials not available. |
Source code in src/mixpanel_headless/workspace.py
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:
|
return_event
|
Event that defines return.
TYPE:
|
from_date
|
Start date (YYYY-MM-DD).
TYPE:
|
to_date
|
End date (YYYY-MM-DD).
TYPE:
|
born_where
|
Optional filter for born event.
TYPE:
|
return_where
|
Optional filter for return event.
TYPE:
|
interval
|
Retention interval.
TYPE:
|
interval_count
|
Number of intervals.
TYPE:
|
unit
|
Time unit.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
RetentionResult
|
RetentionResult with cohort retention data. |
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If API credentials not available. |
Source code in src/mixpanel_headless/workspace.py
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:
|
from_date
|
Start date (YYYY-MM-DD).
TYPE:
|
to_date
|
End date (YYYY-MM-DD).
TYPE:
|
type
|
Counting method.
TYPE:
|
unit
|
Time unit.
TYPE:
|
| 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
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:
|
property_name
|
Property to break down by.
TYPE:
|
from_date
|
Start date (YYYY-MM-DD).
TYPE:
|
to_date
|
End date (YYYY-MM-DD).
TYPE:
|
type
|
Counting method.
TYPE:
|
unit
|
Time unit.
TYPE:
|
values
|
Optional list of property values to include.
TYPE:
|
limit
|
Maximum number of property values.
TYPE:
|
| 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
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:
|
from_date
|
Optional start date filter (
TYPE:
|
to_date
|
Optional end date filter (
TYPE:
|
limit
|
Optional max events to return (server ceiling 15000).
TYPE:
|
include_events
|
Optional event names to include; mutually exclusive
with
TYPE:
|
exclude_events
|
Optional event names to exclude; mutually exclusive
with
TYPE:
|
sentinel_event
|
Optional pagination cursor from a prior result's
TYPE:
|
paging_window
|
Optional days (<= 30) bounding each page's scan window.
TYPE:
|
search
|
Optional full-text search string applied to events.
TYPE:
|
search_properties
|
Optional property descriptors to restrict the
TYPE:
|
use_custom_events
|
When
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ActivityFeedResult
|
ActivityFeedResult with user events plus a |
ActivityFeedResult
|
( |
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If API credentials not available. |
QueryError
|
If both |
Example
Source code in src/mixpanel_headless/workspace.py
1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 | |
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:
|
bookmark_type
|
Type of bookmark to query. Determines which API endpoint is called. Defaults to 'insights'.
TYPE:
|
from_date
|
Start date (YYYY-MM-DD). Required for funnels, optional otherwise.
TYPE:
|
to_date
|
End date (YYYY-MM-DD). Required for funnels, optional otherwise.
TYPE:
|
| 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
query_saved_flows
¶
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:
|
| 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
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:
|
to_date
|
End date (YYYY-MM-DD).
TYPE:
|
unit
|
Overall time unit.
TYPE:
|
addiction_unit
|
Measurement granularity.
TYPE:
|
event
|
Optional event filter.
TYPE:
|
where
|
Optional WHERE clause.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
FrequencyResult
|
FrequencyResult with frequency distribution. |
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If API credentials not available. |
Source code in src/mixpanel_headless/workspace.py
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:
|
from_date
|
Start date.
TYPE:
|
to_date
|
End date.
TYPE:
|
on
|
Numeric property expression.
TYPE:
|
unit
|
Time unit.
TYPE:
|
where
|
Optional filter.
TYPE:
|
type
|
Counting method.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
NumericBucketResult
|
NumericBucketResult with bucketed data. |
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If API credentials not available. |
Source code in src/mixpanel_headless/workspace.py
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:
|
from_date
|
Start date.
TYPE:
|
to_date
|
End date.
TYPE:
|
on
|
Numeric property expression.
TYPE:
|
unit
|
Time unit.
TYPE:
|
where
|
Optional filter.
TYPE:
|
| 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
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:
|
from_date
|
Start date.
TYPE:
|
to_date
|
End date.
TYPE:
|
on
|
Numeric property expression.
TYPE:
|
unit
|
Time unit.
TYPE:
|
where
|
Optional filter.
TYPE:
|
| 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
list_dashboards
¶
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:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Dashboard]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400, 404). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
create_dashboard
¶
Create a new dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Dashboard creation parameters.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Dashboard
|
The newly created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Invalid parameters (400, 422). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
get_dashboard
¶
Get a single dashboard by ID.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Dashboard
|
The |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Dashboard not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_dashboard
¶
Update an existing dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
params
|
Fields to update.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Dashboard
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
delete_dashboard
¶
Delete a dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Dashboard not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
bulk_delete_dashboards
¶
Delete multiple dashboards.
| PARAMETER | DESCRIPTION |
|---|---|
ids
|
List of dashboard IDs to delete.
TYPE:
|
| 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). |
Source code in src/mixpanel_headless/workspace.py
favorite_dashboard
¶
Favorite a dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Dashboard not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
unfavorite_dashboard
¶
Unfavorite a dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Dashboard not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
pin_dashboard
¶
Pin a dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Dashboard not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
unpin_dashboard
¶
Unpin a dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Dashboard not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
add_report_to_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:
|
bookmark_id
|
Bookmark/report identifier to add.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Dashboard
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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. |
Source code in src/mixpanel_headless/workspace.py
remove_report_from_dashboard
¶
Remove a report from a dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
bookmark_id
|
Bookmark/report identifier to remove.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Dashboard
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Dashboard or bookmark not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
list_blueprint_templates
¶
List available dashboard blueprint templates.
| PARAMETER | DESCRIPTION |
|---|---|
include_reports
|
Whether to include report details.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[BlueprintTemplate]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
create_blueprint
¶
Create a dashboard from a blueprint template.
| PARAMETER | DESCRIPTION |
|---|---|
template_type
|
Blueprint template type identifier.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Dashboard
|
The newly created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Invalid template type (400). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
get_blueprint_config
¶
Get the blueprint configuration for a dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BlueprintConfig
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Dashboard not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_blueprint_cohorts
¶
Update cohorts for blueprint configuration.
| PARAMETER | DESCRIPTION |
|---|---|
cohorts
|
List of cohort configuration dicts.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Invalid cohort configuration (400). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
finalize_blueprint
¶
Finalize a blueprint dashboard with cards.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Blueprint finalization parameters.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Dashboard
|
The finalized |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Invalid parameters (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
create_rca_dashboard
¶
Create an RCA (Root Cause Analysis) dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
RCA dashboard parameters.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Dashboard
|
The newly created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Invalid parameters (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
get_bookmark_dashboard_ids
¶
Get dashboard IDs containing a bookmark/report.
| PARAMETER | DESCRIPTION |
|---|---|
bookmark_id
|
Bookmark identifier.
TYPE:
|
| 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). |
Source code in src/mixpanel_headless/workspace.py
get_dashboard_erf
¶
Get ERF data for a dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
| 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). |
Source code in src/mixpanel_headless/workspace.py
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:
|
report_link_id
|
Report link identifier.
TYPE:
|
params
|
Update parameters.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
update_text_card
¶
Update a text card on a dashboard.
| PARAMETER | DESCRIPTION |
|---|---|
dashboard_id
|
Dashboard identifier.
TYPE:
|
text_card_id
|
Text card identifier.
TYPE:
|
params
|
Update parameters.
TYPE:
|
| 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). |
Source code in src/mixpanel_headless/workspace.py
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.,
TYPE:
|
ids
|
Optional list of bookmark IDs to filter by.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Bookmark]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400, 404). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
create_bookmark
¶
Create a new bookmark (saved report).
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Bookmark creation parameters.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Bookmark
|
The newly created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
MixpanelHeadlessError
|
If |
BookmarkValidationError
|
If |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Invalid parameters (400, 422). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5832 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 5862 5863 5864 5865 5866 5867 5868 5869 5870 5871 5872 5873 5874 5875 5876 5877 5878 5879 5880 5881 5882 5883 5884 5885 5886 5887 5888 5889 5890 5891 5892 5893 5894 5895 5896 5897 5898 | |
get_bookmark
¶
Get a single bookmark by ID.
| PARAMETER | DESCRIPTION |
|---|---|
bookmark_id
|
Bookmark identifier.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Bookmark
|
The |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Bookmark not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_bookmark
¶
Update an existing bookmark.
| PARAMETER | DESCRIPTION |
|---|---|
bookmark_id
|
Bookmark identifier.
TYPE:
|
params
|
Fields to update.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Bookmark
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
BookmarkValidationError
|
If |
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
Source code in src/mixpanel_headless/workspace.py
delete_bookmark
¶
Delete a bookmark.
| PARAMETER | DESCRIPTION |
|---|---|
bookmark_id
|
Bookmark identifier.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Bookmark not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
bulk_delete_bookmarks
¶
Delete multiple bookmarks.
| PARAMETER | DESCRIPTION |
|---|---|
ids
|
List of bookmark IDs to delete.
TYPE:
|
| 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). |
Source code in src/mixpanel_headless/workspace.py
bulk_update_bookmarks
¶
Update multiple bookmarks.
| PARAMETER | DESCRIPTION |
|---|---|
entries
|
List of bookmark update entries.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
bookmark_linked_dashboard_ids
¶
Get dashboard IDs linked to a bookmark.
| PARAMETER | DESCRIPTION |
|---|---|
bookmark_id
|
Bookmark identifier.
TYPE:
|
| 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). |
Source code in src/mixpanel_headless/workspace.py
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:
|
cursor
|
Opaque pagination cursor.
TYPE:
|
page_size
|
Maximum entries per page.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BookmarkHistoryResponse
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Bookmark not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
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:
|
ids
|
Optional list of cohort IDs to filter by.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Cohort]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400, 404). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
get_cohort
¶
Get a single cohort by ID via the App API.
| PARAMETER | DESCRIPTION |
|---|---|
cohort_id
|
Cohort identifier.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Cohort
|
The |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Cohort not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
create_cohort
¶
Create a new cohort.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Cohort creation parameters.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Cohort
|
The newly created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Invalid parameters (400). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_cohort
¶
Update an existing cohort.
| PARAMETER | DESCRIPTION |
|---|---|
cohort_id
|
Cohort identifier.
TYPE:
|
params
|
Fields to update.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Cohort
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Cohort not found or invalid params (400, 404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
delete_cohort
¶
Delete a cohort.
| PARAMETER | DESCRIPTION |
|---|---|
cohort_id
|
Cohort identifier.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Cohort not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
bulk_delete_cohorts
¶
Delete multiple cohorts.
| PARAMETER | DESCRIPTION |
|---|---|
ids
|
List of cohort IDs to delete.
TYPE:
|
| 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). |
Source code in src/mixpanel_headless/workspace.py
bulk_update_cohorts
¶
Update multiple cohorts.
| PARAMETER | DESCRIPTION |
|---|---|
entries
|
List of cohort update entries.
TYPE:
|
| 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). |
Source code in src/mixpanel_headless/workspace.py
list_feature_flags
¶
List feature flags for the current project/workspace.
| PARAMETER | DESCRIPTION |
|---|---|
include_archived
|
When True, include archived flags.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[FeatureFlag]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400, 404). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
create_feature_flag
¶
Create a new feature flag.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Flag creation parameters.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
FeatureFlag
|
The newly created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Duplicate key or invalid parameters (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
get_feature_flag
¶
Get a single feature flag by ID.
| PARAMETER | DESCRIPTION |
|---|---|
flag_id
|
Feature flag UUID.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
FeatureFlag
|
The |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Flag not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_feature_flag
¶
Update a feature flag (full replacement, PUT semantics).
| PARAMETER | DESCRIPTION |
|---|---|
flag_id
|
Feature flag UUID.
TYPE:
|
params
|
Complete flag configuration.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
FeatureFlag
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
delete_feature_flag
¶
Delete a feature flag.
| PARAMETER | DESCRIPTION |
|---|---|
flag_id
|
Feature flag UUID.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Flag not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
archive_feature_flag
¶
Archive a feature flag (soft-delete).
| PARAMETER | DESCRIPTION |
|---|---|
flag_id
|
Feature flag UUID.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Flag not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
restore_feature_flag
¶
Restore an archived feature flag.
| PARAMETER | DESCRIPTION |
|---|---|
flag_id
|
Feature flag UUID.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
FeatureFlag
|
The restored |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Flag not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
duplicate_feature_flag
¶
Duplicate a feature flag.
| PARAMETER | DESCRIPTION |
|---|---|
flag_id
|
Feature flag UUID.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
FeatureFlag
|
The newly created duplicate |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Flag not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
set_flag_test_users
¶
Set test user variant overrides for a feature flag.
| PARAMETER | DESCRIPTION |
|---|---|
flag_id
|
Feature flag UUID.
TYPE:
|
params
|
Test user mapping.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
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:
|
page
|
Pagination cursor.
TYPE:
|
page_size
|
Results per page.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
FlagHistoryResponse
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Flag not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
get_flag_limits
¶
Get account-level feature flag limits and usage.
| RETURNS | DESCRIPTION |
|---|---|
FlagLimitsResponse
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
list_experiments
¶
List experiments for the current project.
| PARAMETER | DESCRIPTION |
|---|---|
include_archived
|
When True, include archived experiments.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Experiment]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400, 404). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
create_experiment
¶
Create a new experiment in Draft status.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Experiment creation parameters.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Experiment
|
The newly created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Invalid parameters (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
get_experiment
¶
Get a single experiment by ID.
| PARAMETER | DESCRIPTION |
|---|---|
experiment_id
|
Experiment UUID.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Experiment
|
The |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Experiment not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_experiment
¶
Update an experiment (PATCH semantics).
| PARAMETER | DESCRIPTION |
|---|---|
experiment_id
|
Experiment UUID.
TYPE:
|
params
|
Fields to update.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Experiment
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
delete_experiment
¶
Delete an experiment.
| PARAMETER | DESCRIPTION |
|---|---|
experiment_id
|
Experiment UUID.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Experiment not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
launch_experiment
¶
Launch an experiment (Draft → Active).
| PARAMETER | DESCRIPTION |
|---|---|
experiment_id
|
Experiment UUID.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Experiment
|
The launched |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Invalid state transition (400) or not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
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:
|
params
|
Optional conclude parameters (e.g. end date override).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Experiment
|
The concluded |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Invalid state transition (400) or not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
decide_experiment
¶
Record the experiment decision (Concluded → Success/Fail).
| PARAMETER | DESCRIPTION |
|---|---|
experiment_id
|
Experiment UUID.
TYPE:
|
params
|
Decision parameters (success, variant, message).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Experiment
|
The decided |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
archive_experiment
¶
Archive an experiment.
| PARAMETER | DESCRIPTION |
|---|---|
experiment_id
|
Experiment UUID.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Experiment not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
restore_experiment
¶
Restore an archived experiment.
| PARAMETER | DESCRIPTION |
|---|---|
experiment_id
|
Experiment UUID.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Experiment
|
The restored |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Experiment not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
duplicate_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:
|
params
|
Duplication parameters ( |
| RETURNS | DESCRIPTION |
|---|---|
Experiment
|
The newly created duplicate |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Experiment not found (404). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
list_erf_experiments
¶
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). |
Source code in src/mixpanel_headless/workspace.py
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:
|
skip_user_filter
|
If True, list alerts for all users.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[CustomAlert]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
create_alert
¶
Create a new custom alert.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Alert creation parameters (bookmark_id, name, condition, frequency, paused, and subscriptions are required).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
CustomAlert
|
The created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
get_alert
¶
Get a single custom alert by ID.
| PARAMETER | DESCRIPTION |
|---|---|
alert_id
|
Alert ID (integer).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
CustomAlert
|
The |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Alert not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_alert
¶
Update a custom alert (PATCH semantics).
| PARAMETER | DESCRIPTION |
|---|---|
alert_id
|
Alert ID (integer).
TYPE:
|
params
|
Fields to update.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
CustomAlert
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Alert not found (404) or validation error (400). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
delete_alert
¶
Delete a custom alert.
| PARAMETER | DESCRIPTION |
|---|---|
alert_id
|
Alert ID (integer).
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Alert not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
bulk_delete_alerts
¶
Bulk-delete custom alerts.
| PARAMETER | DESCRIPTION |
|---|---|
ids
|
List of alert IDs to delete.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
get_alert_count
¶
Get alert count and limits.
| PARAMETER | DESCRIPTION |
|---|---|
alert_type
|
Optional filter by alert type.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
AlertCount
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
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:
|
page_size
|
Number of results per page.
TYPE:
|
next_cursor
|
Cursor for the next page.
TYPE:
|
previous_cursor
|
Cursor for the previous page.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
AlertHistoryResponse
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Alert not found (404). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
test_alert
¶
Send a test alert notification.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Alert parameters for the test (same shape as create).
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
get_alert_screenshot_url
¶
Get a signed URL for an alert screenshot.
| PARAMETER | DESCRIPTION |
|---|---|
gcs_key
|
GCS object key for the screenshot.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
AlertScreenshotResponse
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Screenshot not found (404). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
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). |
| RETURNS | DESCRIPTION |
|---|---|
ValidateAlertsForBookmarkResponse
|
|
ValidateAlertsForBookmarkResponse
|
and invalid count. |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
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.
TYPE:
|
to_date
|
End date filter (ISO format, e.g.
TYPE:
|
tags
|
Tag IDs to filter by.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[Annotation]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
create_annotation
¶
Create a new timeline annotation.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Annotation creation parameters (date, description required).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Annotation
|
The created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
get_annotation
¶
Get a single annotation by ID.
| PARAMETER | DESCRIPTION |
|---|---|
annotation_id
|
Annotation ID.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Annotation
|
The |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Annotation not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_annotation
¶
Update an annotation (PATCH semantics).
| PARAMETER | DESCRIPTION |
|---|---|
annotation_id
|
Annotation ID.
TYPE:
|
params
|
Fields to update (description, tags).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
Annotation
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
delete_annotation
¶
Delete an annotation.
| PARAMETER | DESCRIPTION |
|---|---|
annotation_id
|
Annotation ID.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Annotation not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
list_annotation_tags
¶
List annotation tags for the project.
| RETURNS | DESCRIPTION |
|---|---|
list[AnnotationTag]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
create_annotation_tag
¶
Create a new annotation tag.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Tag creation parameters (name required). |
| RETURNS | DESCRIPTION |
|---|---|
AnnotationTag
|
The created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
list_webhooks
¶
List all webhooks for the current project.
| RETURNS | DESCRIPTION |
|---|---|
list[ProjectWebhook]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
create_webhook
¶
Create a new webhook.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Webhook creation parameters.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
WebhookMutationResult
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
update_webhook
¶
Update an existing webhook.
| PARAMETER | DESCRIPTION |
|---|---|
webhook_id
|
Webhook UUID string.
TYPE:
|
params
|
Fields to update (PATCH semantics).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
WebhookMutationResult
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Webhook not found (404). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
delete_webhook
¶
Delete a webhook.
| PARAMETER | DESCRIPTION |
|---|---|
webhook_id
|
Webhook UUID string.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Webhook not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
test_webhook
¶
Test webhook connectivity.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Webhook test parameters (url is required).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
WebhookTestResult
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
API error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
get_event_definitions
¶
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:
|
| RETURNS | DESCRIPTION |
|---|---|
list[EventDefinition]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
update_event_definition
¶
Update an event definition in Lexicon.
| PARAMETER | DESCRIPTION |
|---|---|
event_name
|
Name of the event to update.
TYPE:
|
params
|
Fields to update (hidden, dropped, merged, verified, tags, display_name, description). |
| RETURNS | DESCRIPTION |
|---|---|
EventDefinition
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
delete_event_definition
¶
Delete an event definition from Lexicon.
| PARAMETER | DESCRIPTION |
|---|---|
event_name
|
Name of the event to delete.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Event not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
bulk_update_event_definitions
¶
Bulk-update event definitions in Lexicon.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Bulk update parameters containing a list of event updates (name + fields to change).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[EventDefinition]
|
List of updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
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. The Lexicon API looks up one name per request, so this method sends one request per distinct name. The match is exact. A name that the project neither tracks nor defines in Lexicon is left out of the result.
| PARAMETER | DESCRIPTION |
|---|---|
names
|
List of property names to look up.
TYPE:
|
resource_type
|
Optional resource type filter (e.g.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[PropertyDefinition]
|
List of |
list[PropertyDefinition]
|
that exist, in the order of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
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:
|
params
|
Fields to update (hidden, dropped, merged, sensitive, display_name, description, example_value, resource_type). |
| RETURNS | DESCRIPTION |
|---|---|
PropertyDefinition
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
bulk_update_property_definitions
¶
Bulk-update property definitions in Lexicon.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Bulk update parameters containing a list of property updates (name + fields to change). |
| RETURNS | DESCRIPTION |
|---|---|
list[PropertyDefinition]
|
List of updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
list_lexicon_tags
¶
List all Lexicon tags.
| RETURNS | DESCRIPTION |
|---|---|
list[LexiconTag]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
ServerError
|
Server-side errors (5xx). |
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
create_lexicon_tag
¶
Create a new Lexicon tag.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Tag creation parameters (name is required).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LexiconTag
|
The created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400) or tag already exists. |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_lexicon_tag
¶
Update a Lexicon tag.
| PARAMETER | DESCRIPTION |
|---|---|
tag_id
|
Tag ID (integer).
TYPE:
|
params
|
Fields to update (e.g. name).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LexiconTag
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Tag not found (404) or validation error (400). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
delete_lexicon_tag
¶
Delete a Lexicon tag by name.
| PARAMETER | DESCRIPTION |
|---|---|
tag_name
|
Name of the tag to delete.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Tag not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
get_tracking_metadata
¶
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:
|
| 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). |
Source code in src/mixpanel_headless/workspace.py
get_event_history
¶
Get change history for an event definition.
| PARAMETER | DESCRIPTION |
|---|---|
event_name
|
Name of the event.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
get_property_history
¶
Get change history for a property definition.
| PARAMETER | DESCRIPTION |
|---|---|
property_name
|
Name of the property.
TYPE:
|
entity_type
|
Entity type (e.g.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
export_lexicon
¶
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.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
list_drop_filters
¶
List all drop filters.
| RETURNS | DESCRIPTION |
|---|---|
list[DropFilter]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
create_drop_filter
¶
Create a new drop filter.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Drop filter creation parameters.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[DropFilter]
|
Full list of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
update_drop_filter
¶
Update a drop filter.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Drop filter update parameters (must include the filter ID).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[DropFilter]
|
Full list of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
delete_drop_filter
¶
Delete a drop filter.
| PARAMETER | DESCRIPTION |
|---|---|
drop_filter_id
|
Drop filter ID (integer).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[DropFilter]
|
Full list of remaining |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Filter not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
get_drop_filter_limits
¶
Get drop filter usage limits.
| RETURNS | DESCRIPTION |
|---|---|
DropFilterLimitsResponse
|
|
DropFilterLimitsResponse
|
drop filters for the project. |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
list_custom_properties
¶
List all custom properties.
| RETURNS | DESCRIPTION |
|---|---|
list[CustomProperty]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Server-side data corruption (e.g. invalid
|
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
create_custom_property
¶
Create a new custom property.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Custom property creation parameters (name, display_formula or behavior, resource_type are required). |
| RETURNS | DESCRIPTION |
|---|---|
CustomProperty
|
The created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
get_custom_property
¶
Get a custom property by ID.
| PARAMETER | DESCRIPTION |
|---|---|
property_id
|
Custom property ID (string).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
CustomProperty
|
The |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Property not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_custom_property
¶
Update a custom property.
| PARAMETER | DESCRIPTION |
|---|---|
property_id
|
Custom property ID (string).
TYPE:
|
params
|
Fields to update. |
| RETURNS | DESCRIPTION |
|---|---|
CustomProperty
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
delete_custom_property
¶
Delete a custom property.
| PARAMETER | DESCRIPTION |
|---|---|
property_id
|
Custom property ID (string).
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Property not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
validate_custom_property
¶
Validate a custom property definition without creating it.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Custom property parameters to validate. |
| 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
list_lookup_tables
¶
List lookup tables.
| PARAMETER | DESCRIPTION |
|---|---|
data_group_id
|
Optional filter by data group ID.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[LookupTable]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
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
TYPE:
|
poll_interval
|
Seconds between status polls for async uploads.
TYPE:
|
max_poll_seconds
|
Maximum seconds to wait for async processing.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LookupTable
|
The created |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
8568 8569 8570 8571 8572 8573 8574 8575 8576 8577 8578 8579 8580 8581 8582 8583 8584 8585 8586 8587 8588 8589 8590 8591 8592 8593 8594 8595 8596 8597 8598 8599 8600 8601 8602 8603 8604 8605 8606 8607 8608 8609 8610 8611 8612 8613 8614 8615 8616 8617 8618 8619 8620 8621 8622 8623 8624 8625 8626 8627 8628 8629 8630 8631 8632 8633 8634 8635 8636 8637 8638 8639 8640 8641 8642 8643 8644 8645 8646 8647 8648 8649 8650 8651 8652 8653 8654 | |
mark_lookup_table_ready
¶
Mark a lookup table as ready after upload.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Parameters including |
| RETURNS | DESCRIPTION |
|---|---|
LookupTable
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
get_lookup_upload_url
¶
Get a signed URL for uploading lookup table data.
| PARAMETER | DESCRIPTION |
|---|---|
content_type
|
MIME type of the file to upload
(default:
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LookupTableUploadUrl
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
get_lookup_upload_status
¶
Get the processing status of a lookup table upload.
| PARAMETER | DESCRIPTION |
|---|---|
upload_id
|
Upload ID returned from the upload process.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
update_lookup_table
¶
Update a lookup table.
| PARAMETER | DESCRIPTION |
|---|---|
data_group_id
|
Data group ID of the lookup table.
TYPE:
|
params
|
Fields to update.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
LookupTable
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
delete_lookup_tables
¶
Delete one or more lookup tables.
| PARAMETER | DESCRIPTION |
|---|---|
data_group_ids
|
List of data group IDs to delete.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
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:
|
file_name
|
Optional file name filter.
TYPE:
|
limit
|
Optional row limit.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
get_lookup_download_url
¶
Get a signed download URL for a lookup table.
| PARAMETER | DESCRIPTION |
|---|---|
data_group_id
|
Data group ID of the lookup table.
TYPE:
|
| 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). |
Source code in src/mixpanel_headless/workspace.py
list_custom_events
¶
List all custom events.
| RETURNS | DESCRIPTION |
|---|---|
list[EventDefinition]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
update_custom_event
¶
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:
|
params
|
Fields to update. See
:class: |
| RETURNS | DESCRIPTION |
|---|---|
EventDefinition
|
The updated |
EventDefinition
|
event, with |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
|
Example
Source code in src/mixpanel_headless/workspace.py
delete_custom_event
¶
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:
|
| RAISES | DESCRIPTION |
|---|---|
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Event not found (404). |
ServerError
|
Server-side errors (5xx). |
Source code in src/mixpanel_headless/workspace.py
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 135 seconds.
| PARAMETER | DESCRIPTION |
|---|---|
metric_type
|
Keep only metrics of this kind:
TYPE:
|
verified
|
TYPE:
|
name_contains
|
Keep only metrics whose name contains this text, ignoring case.
TYPE:
|
viewable_only
|
Drop the metrics that the server marks
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[SavedMetric]
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
9115 9116 9117 9118 9119 9120 9121 9122 9123 9124 9125 9126 9127 9128 9129 9130 9131 9132 9133 9134 9135 9136 9137 9138 9139 9140 9141 9142 9143 9144 9145 9146 9147 9148 9149 9150 9151 9152 9153 9154 9155 9156 9157 9158 9159 9160 9161 9162 9163 9164 9165 9166 9167 9168 9169 9170 9171 9172 9173 9174 9175 9176 9177 9178 | |
get_metric
¶
Get one saved metric by id, with its full definition.
| PARAMETER | DESCRIPTION |
|---|---|
metric_id
|
The saved metric id.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SavedMetric
|
The |
SavedMetric
|
|
SavedMetric
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
create_metric
¶
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:
|
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.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SavedMetric
|
The created |
SavedMetric
|
was needed). |
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
Before any request: an empty name
( |
ResponseValidationError
|
Malformed API response payload
( |
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 |
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
( |
Example
Source code in src/mixpanel_headless/workspace.py
9213 9214 9215 9216 9217 9218 9219 9220 9221 9222 9223 9224 9225 9226 9227 9228 9229 9230 9231 9232 9233 9234 9235 9236 9237 9238 9239 9240 9241 9242 9243 9244 9245 9246 9247 9248 9249 9250 9251 9252 9253 9254 9255 9256 9257 9258 9259 9260 9261 9262 9263 9264 9265 9266 9267 9268 9269 9270 9271 9272 9273 9274 9275 9276 9277 9278 9279 9280 9281 9282 9283 9284 9285 9286 9287 9288 9289 9290 9291 9292 9293 9294 9295 9296 9297 9298 9299 9300 9301 9302 9303 9304 9305 9306 9307 9308 9309 9310 9311 9312 9313 9314 9315 9316 9317 9318 9319 9320 9321 9322 9323 9324 9325 9326 9327 9328 9329 9330 9331 9332 9333 9334 9335 9336 9337 9338 9339 9340 9341 9342 9343 9344 9345 9346 9347 9348 9349 9350 9351 9352 9353 9354 9355 9356 9357 | |
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
Noneis removed, and the other keys stay. The params goals replace the stored goals in full. - A
WarehouseMetricwhoseaggregationorsync_intervalisNonekeeps the stored value, so an update of the SQL alone keeps a stored"sum"and"daily". ARawMetricDefinitionis 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:
|
params
|
The fields to change;
TYPE:
|
validate
|
Check new definition, display, and goal values with the
mirror of the server schema (default).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SavedMetric
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
Before any request: an empty name
( |
ResponseValidationError
|
Malformed API response payload
( |
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). When the caller cannot edit it, the method reads the metric once after the 403. The message names the metric and, when that read succeeds, its creator, and it says who can edit the metric. |
RateLimitError
|
Rate limit exceeded after retries (429). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
9359 9360 9361 9362 9363 9364 9365 9366 9367 9368 9369 9370 9371 9372 9373 9374 9375 9376 9377 9378 9379 9380 9381 9382 9383 9384 9385 9386 9387 9388 9389 9390 9391 9392 9393 9394 9395 9396 9397 9398 9399 9400 9401 9402 9403 9404 9405 9406 9407 9408 9409 9410 9411 9412 9413 9414 9415 9416 9417 9418 9419 9420 9421 9422 9423 9424 9425 9426 9427 9428 9429 9430 9431 9432 9433 9434 9435 9436 9437 9438 9439 9440 9441 9442 9443 9444 9445 9446 9447 9448 9449 9450 9451 9452 9453 9454 9455 9456 9457 9458 9459 9460 9461 9462 9463 9464 9465 9466 9467 9468 | |
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:
|
validate
|
Check new definitions with the mirror of the server schema (default).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[SavedMetric]
|
The updated |
list[SavedMetric]
|
|
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
An entry breaks a rule of
:meth: |
ResponseValidationError
|
Malformed API response payload
( |
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). That 403 means that nothing was changed. The method then reads the metrics one by one, to name each refused metric and its creator. It reads them only for a batch of 10 metrics or fewer, with one attempt per read and a time budget of about 10 seconds for all the reads. The message also names each metric that was not found or that the method could not read. A larger batch gets a message that lists the ids only. |
RateLimitError
|
Rate limit exceeded after retries (429). |
ServerError
|
Server-side errors (5xx). |
Example
Source code in src/mixpanel_headless/workspace.py
9470 9471 9472 9473 9474 9475 9476 9477 9478 9479 9480 9481 9482 9483 9484 9485 9486 9487 9488 9489 9490 9491 9492 9493 9494 9495 9496 9497 9498 9499 9500 9501 9502 9503 9504 9505 9506 9507 9508 9509 9510 9511 9512 9513 9514 9515 9516 9517 9518 9519 9520 9521 9522 9523 9524 9525 9526 9527 9528 9529 9530 9531 9532 9533 9534 9535 9536 9537 9538 9539 9540 9541 9542 9543 9544 9545 9546 9547 9548 9549 9550 9551 9552 9553 9554 9555 9556 9557 9558 9559 9560 9561 9562 9563 9564 9565 9566 9567 9568 | |
delete_metric
¶
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:
|
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:
|
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
The read found no active metric with this
id (404); nothing was deleted ( |
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
Source code in src/mixpanel_headless/workspace.py
9570 9571 9572 9573 9574 9575 9576 9577 9578 9579 9580 9581 9582 9583 9584 9585 9586 9587 9588 9589 9590 9591 9592 9593 9594 9595 9596 9597 9598 9599 9600 9601 9602 9603 9604 9605 9606 9607 9608 9609 9610 9611 9612 9613 9614 9615 9616 9617 9618 9619 9620 9621 9622 9623 9624 9625 9626 9627 9628 9629 9630 | |
delete_metrics
¶
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:
|
force
|
Skip the list read and the permission guard, and send the delete as given.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
A target has |
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
Source code in src/mixpanel_headless/workspace.py
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 135 seconds.
| PARAMETER | DESCRIPTION |
|---|---|
behavior_type
|
Keep only behaviors of this type:
TYPE:
|
name_contains
|
Keep only behaviors whose name contains this text, ignoring case.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[SavedBehavior]
|
|
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
get_behavior
¶
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:
|
| RETURNS | DESCRIPTION |
|---|---|
SavedBehavior
|
The |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
create_behavior
¶
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:
|
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.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SavedBehavior
|
The created |
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
Before any request: an empty name
( |
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
10034 10035 10036 10037 10038 10039 10040 10041 10042 10043 10044 10045 10046 10047 10048 10049 10050 10051 10052 10053 10054 10055 10056 10057 10058 10059 10060 10061 10062 10063 10064 10065 10066 10067 10068 10069 10070 10071 10072 10073 10074 10075 10076 10077 10078 10079 10080 10081 10082 10083 10084 10085 10086 10087 10088 10089 10090 10091 10092 10093 10094 10095 10096 10097 10098 10099 10100 10101 10102 | |
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:
|
params
|
The fields to change;
TYPE:
|
validate
|
Check a new definition with the mirror of the server
schema (default).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SavedBehavior
|
The updated |
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
Before any request: an empty name
( |
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
The caller cannot edit the behavior or lacks the
|
RateLimitError
|
Rate limit exceeded after retries (429). |
ServerError
|
Server-side errors (5xx), including the read of an unknown behavior id. |
Source code in src/mixpanel_headless/workspace.py
10104 10105 10106 10107 10108 10109 10110 10111 10112 10113 10114 10115 10116 10117 10118 10119 10120 10121 10122 10123 10124 10125 10126 10127 10128 10129 10130 10131 10132 10133 10134 10135 10136 10137 10138 10139 10140 10141 10142 10143 10144 10145 10146 10147 10148 10149 10150 10151 10152 10153 10154 10155 10156 10157 10158 10159 10160 10161 10162 10163 10164 10165 10166 10167 10168 10169 10170 10171 10172 10173 10174 10175 10176 10177 10178 10179 10180 10181 10182 10183 10184 10185 10186 10187 10188 10189 10190 10191 10192 10193 10194 | |
delete_behavior
¶
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:
|
force
|
Delete even when the read says that the caller cannot edit the behavior. The existence read still runs.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
The read shows |
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. |
Source code in src/mixpanel_headless/workspace.py
delete_behaviors
¶
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:
|
force
|
Skip the list read and the permission guard, and send the delete as given.
TYPE:
|
| RAISES | DESCRIPTION |
|---|---|
ParamValidationError
|
A target has |
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
Source code in src/mixpanel_headless/workspace.py
list_schema_registry
¶
List schema registry entries.
| PARAMETER | DESCRIPTION |
|---|---|
entity_type
|
Filter by entity type ("event", "custom_event", "profile"). If None, returns all schemas.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[SchemaEntry]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
RateLimitError
|
Rate limit exceeded (429). |
Example
Source code in src/mixpanel_headless/workspace.py
create_schema
¶
Create a single schema definition.
| PARAMETER | DESCRIPTION |
|---|---|
entity_type
|
Entity type ("event", "custom_event", "profile").
TYPE:
|
entity_name
|
Entity name (event name or "$user" for profile).
TYPE:
|
schema_json
|
JSON Schema Draft 7 definition.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
create_schemas_bulk
¶
Bulk create schemas.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Bulk creation parameters with entries list and optional truncate flag.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BulkCreateSchemasResponse
|
Response with |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
RateLimitError
|
Rate limit exceeded (429). |
Example
Source code in src/mixpanel_headless/workspace.py
update_schema
¶
Update a single schema definition (merge semantics).
| PARAMETER | DESCRIPTION |
|---|---|
entity_type
|
Entity type.
TYPE:
|
entity_name
|
Entity name.
TYPE:
|
schema_json
|
Partial JSON Schema to merge with existing.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
update_schemas_bulk
¶
Bulk update schemas (merge semantics per entry).
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Bulk update parameters with entries list.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[BulkPatchResult]
|
List of per-entry results with status ("ok" or "error"). |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
RateLimitError
|
Rate limit exceeded (429). |
Example
Source code in src/mixpanel_headless/workspace.py
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:
|
entity_name
|
Filter by entity name (requires entity_type).
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DeleteSchemasResponse
|
Response with |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
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
Source code in src/mixpanel_headless/workspace.py
get_schema_enforcement
¶
Get current schema enforcement configuration.
| PARAMETER | DESCRIPTION |
|---|---|
fields
|
Comma-separated field names to return (e.g., "ruleEvent,state"). If None, returns all fields.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
SchemaEnforcementConfig
|
Schema enforcement configuration. |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
No enforcement configured (404). |
Source code in src/mixpanel_headless/workspace.py
init_schema_enforcement
¶
Initialize schema enforcement.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Init parameters with rule_event. |
| 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
Source code in src/mixpanel_headless/workspace.py
update_schema_enforcement
¶
Partially update enforcement configuration.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Partial update parameters. |
| 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
Source code in src/mixpanel_headless/workspace.py
replace_schema_enforcement
¶
Fully replace enforcement configuration.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Complete replacement parameters. |
| 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
Source code in src/mixpanel_headless/workspace.py
delete_schema_enforcement
¶
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). |
Source code in src/mixpanel_headless/workspace.py
run_audit
¶
Run a full data audit (events + properties).
| RETURNS | DESCRIPTION |
|---|---|
AuditResponse
|
Audit response with violations and |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
No schemas defined (400). |
Example
Source code in src/mixpanel_headless/workspace.py
run_audit_events_only
¶
Run an events-only data audit (faster).
| RETURNS | DESCRIPTION |
|---|---|
AuditResponse
|
Audit response with event violations only. |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
No schemas defined (400). |
Source code in src/mixpanel_headless/workspace.py
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:
|
| RETURNS | DESCRIPTION |
|---|---|
list[DataVolumeAnomaly]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
Example
Source code in src/mixpanel_headless/workspace.py
update_anomaly
¶
Update the status of a single anomaly.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Update parameters with id, status, and anomaly_class.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
bulk_update_anomalies
¶
Bulk update anomaly statuses.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Bulk update with anomalies list and target status.
TYPE:
|
| 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
Source code in src/mixpanel_headless/workspace.py
list_deletion_requests
¶
List all event deletion requests.
| RETURNS | DESCRIPTION |
|---|---|
list[EventDeletionRequest]
|
List of |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
Source code in src/mixpanel_headless/workspace.py
create_deletion_request
¶
Create a new event deletion request.
| PARAMETER | DESCRIPTION |
|---|---|
params
|
Deletion parameters with event_name, from_date, to_date, and optional filters. |
| RETURNS | DESCRIPTION |
|---|---|
list[EventDeletionRequest]
|
Updated full list of deletion requests. |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Validation error (400). |
Example
Source code in src/mixpanel_headless/workspace.py
cancel_deletion_request
¶
Cancel a pending deletion request.
| PARAMETER | DESCRIPTION |
|---|---|
request_id
|
Deletion request ID to cancel.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list[EventDeletionRequest]
|
Updated full list of deletion requests. |
| RAISES | DESCRIPTION |
|---|---|
ResponseValidationError
|
Malformed API response payload
( |
ConfigError
|
If credentials are not available. |
AuthenticationError
|
Invalid credentials (401). |
QueryError
|
Request not found or not cancellable (400). |
Source code in src/mixpanel_headless/workspace.py
preview_deletion_filters
¶
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. |
| 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). |