Skip to content

User Profile Queries

Query user profiles from Mixpanel's Engage API — filter by properties, sort, select fields, count matching profiles, and fetch large result sets with parallel pagination. Uses the same Filter vocabulary as the other query engines, with the exceptions listed in Filtering Profiles.

Recommended

Workspace.query_user() is the 5th engine in the unified query system. It answers identity questions ("who are these users?") that complement the behavioral questions answered by insights, funnels, retention, and flows.

When to Use query_user()

Use query_user() when you need to work with user profiles rather than events:

Use Case Example
Filter profiles by property query_user(mode="profiles", where=Filter.equals("plan", "premium"))
Count matching profiles query_user(where=Filter.is_set("$email"))
Get top users by a metric query_user(mode="profiles", sort_by="ltv", sort_order="descending", limit=50)
Look up specific users query_user(mode="profiles", distinct_id="user_abc123")
Profile a behavioral cohort query_user(mode="profiles", cohort=CohortDefinition.all_of(...))
Export profiles at scale query_user(mode="profiles", properties=[...], limit=5000, parallel=True)
Cross-engine profiling Insights identifies a segment, query_user() profiles those users

Use stream_profiles() when you need to iterate over raw profile dicts without structured filtering or DataFrame output.

Getting Started

import mixpanel_headless as mp
from mixpanel_headless import Filter

ws = mp.Workspace()

# Quick count — how many profiles exist? (default: mode="aggregate")
result = ws.query_user()
print(f"Total profiles: {result.value}")

# Quick peek — one sample profile
result = ws.query_user(mode="profiles")
print(result.df)

# Filter and select properties
result = ws.query_user(
    mode="profiles",
    where=Filter.equals("plan", "premium"),
    properties=["$email", "$name", "ltv"],
    sort_by="ltv",
    sort_order="descending",
    limit=50,
)
print(result.df)  # distinct_id | last_seen | email | name | ltv

Filtering Profiles

where= takes a Filter, a list of filters (AND-combined), or a raw Engage selector string. query_user() translates each Filter into an Engage selector:

# Users seen since September 1 (a day in the project timezone)
ws.query_user(where=Filter.since("$last_seen", "2026-09-01", resource_type="people"))

# Users seen in the last 7 days with a lifetime value of at least 100
ws.query_user(
    where=[
        Filter.in_the_last("$last_seen", 7, "day", resource_type="people"),
        Filter.at_least("ltv", 100, resource_type="people"),
    ],
)
Filter constructors Engage meaning
equals, not_equals, contains, not_contains String comparisons. contains on a list property tests membership.
greater_than, less_than, at_least, at_most, between, not_between Number comparisons. between includes both bounds; not_between excludes them.
is_set, is_not_set, is_true, is_false Existence and boolean checks.
on, since, date_between Whole days in the project timezone. on matches its day, since matches its day and later, and date_between matches its range with both endpoint days included.
before Days before the named day, in the project timezone. The named day is excluded.
not_on, date_not_between A set value outside the named day or range, in the project timezone. The named day, or both endpoint days, are excluded.
in_the_last, not_in_the_last, in_the_next Rolling windows from the server's clock (see below).
in_cohort One per query, sent as a cohort filter.

Relative dates are rolling windows. The Engage selector has no calendar functions, so a relative filter counts back (or forward) from the moment the server runs the query: in_the_last("$last_seen", 7, "day") covers the last 168 hours. Insights starts the same window at the start of a calendar day, so counts near the start of the window can differ. A week is 7 days and a month is 30 days, as in Insights. A window can span at most 50 years; use since(), before(), or date_between() for a longer range.

Not supported. starts_with, ends_with, and list_contains have no Engage selector form, and a raw selector string cannot express them either. They raise BookmarkValidationError, and the message names a workaround (for example, narrow with contains and finish the match in result.df). not_in_cohort is rejected too.

Raw selectors. Pass a string for any other expression the Engage selector accepts, for example where='properties["$last_seen"] > datetime("2026-09-01T00:00:00")'. A datetime("…") literal is read in the project timezone.

Aggregate Mode

Aggregate mode is the default (mode="aggregate"). Compute statistics across matching profiles without fetching individual records:

# Count users with email (aggregate is the default mode)
count = ws.query_user(where=Filter.is_set("$email"))
print(f"Users with email: {count.value}")

# Total users (all)
total = ws.query_user()
print(f"Total profiles: {total.value}")

# Extremes (min/max) of a numeric property
result = ws.query_user(
    aggregate="extremes",
    aggregate_property="ltv",
)
print(result.aggregate_data)  # {"max": 9500, "min": 0, ...}

# Percentile
result = ws.query_user(
    aggregate="percentile",
    aggregate_property="ltv",
    percentile=90,
)
print(result.aggregate_data)  # {"percentile": 90, "result": 4500}

# Numeric summary (count, mean, variance, sum_of_squares)
result = ws.query_user(
    aggregate="numeric_summary",
    aggregate_property="ltv",
)
print(result.aggregate_data)  # {"count": 1532, "mean": 245.6, ...}

# Segmented count by cohort IDs
result = ws.query_user(
    segment_by=[12345, 67890],
)
print(result.df)  # columns: segment, value

Behavioral Filtering

Filter by behavioral criteria using the same CohortDefinition builders available across all engines:

from mixpanel_headless import CohortDefinition, CohortCriteria

# Users who purchased 3+ times in 30 days
result = ws.query_user(
    mode="profiles",
    cohort=CohortDefinition.all_of(
        CohortCriteria.did_event("Purchase", at_least=3, within_days=30),
    ),
    properties=["$email", "plan", "ltv"],
    limit=200,
)
print(f"Power buyers: {len(result.profiles)}")

# Filter by saved cohort ID
result = ws.query_user(mode="profiles", cohort=12345, limit=100)

Parallel Fetching

For large result sets, enable concurrent page retrieval:

result = ws.query_user(
    mode="profiles",
    where=Filter.is_set("$email"),
    properties=["$email", "plan", "ltv"],
    limit=5000,
    parallel=True,
    workers=5,
)
print(f"Fetched {len(result.profiles)} profiles")
print(f"Pages: {result.meta['pages_fetched']}, Workers: {result.meta['workers']}")

Cross-Engine Composition

The real power of query_user() is combining it with behavioral engines. Identify interesting behavior with event engines, then profile those users:

# Step 1: Which plan drives the most DAU?
dau = ws.query("Login", math="dau", group_by="plan", last=30)
top_plan = dau.df.sort_values("count", ascending=False).iloc[0]["event"]

# Step 2: Profile users from that plan
users = ws.query_user(
    mode="profiles",
    where=Filter.equals("plan", top_plan),
    properties=["$email", "company", "ltv"],
    sort_by="ltv",
    sort_order="descending",
    limit=100,
)
print(f"Plan '{top_plan}' has {len(users.profiles)} top users")
print(users.df.describe())

UserQueryResult

All results are returned as UserQueryResult, a frozen dataclass with:

Property Type Description
.df pd.DataFrame Lazy cached DataFrame. Profiles mode: distinct_id, last_seen, then alphabetical properties ($ prefix stripped). Aggregate mode: metric/value columns.
.total int Number of profiles returned (len(profiles)). Use mode='aggregate', aggregate='count' for full population count.
.profiles list[dict] Normalized profile dicts
.distinct_ids list[str] List of distinct IDs from profiles
.value int \| float \| None Scalar aggregate result (aggregate mode only)
.params dict Engage API params used (for debugging)
.meta dict Execution metadata (session_id, pages_fetched, parallel, workers)
.to_dict() dict JSON-serializable output

Previewing Parameters

Inspect the generated Engage API params without executing:

params = ws.build_user_params(
    where=Filter.equals("plan", "premium"),
    properties=["$email", "ltv"],
    sort_by="ltv",
)
import json
print(json.dumps(params, indent=2))

Running Built Params

Use run_user_params() to execute params that build_user_params() produced (or params you wrote by hand). It returns the same UserQueryResult as query_user(). The mode is read from the params: a dict with an aggregate action runs as an aggregate query, anything else runs as a profiles query. limit, parallel, and workers are execution settings the builder does not store, so pass them here:

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

What's Next