events.property_values
Retrieves the most common string values for a property on a given event, ranked by occurrence count. Helps identify value space for cohort or segment filtering.
Instructions
Top distinct values a string-typed property has taken on a specific event in the period, ranked by occurrence count. Useful when you need to know the value space before filtering — e.g. cohort definitions, segment filters, "what values does plan take on signup?".
Response shape:
{
event: "signup",
property: "plan",
period: "30d",
values: [
{ value: "free", count: 412 },
{ value: "pro", count: 138 },
{ value: "growth", count: 22 }
]
}Examples:
"what plans do signups come from" → event="signup", property="plan"
"which countries hit the checkout event" → event="checkout", property="country" (only if you instrument it as a property; otherwise use traffic.breakdown)
"what
sourcevalues does the lead event carry" → event="lead", property="source"
Limitations: STRING properties only — same scope as cohort filter values (cohort filtering is string-equality only). Numeric / boolean / money properties are out of scope. Results are capped at limit (default 50, max 200) so very high-cardinality properties (user_id, session_id, URLs) are truncated to the top-N by count. Events without the property at all are skipped — only rows where the property is present and non-empty contribute.
Pairs with: events.observed_schema to discover which properties an event actually fires; cohorts.create to scope a cohort by a specific value of those.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| event | Yes | Event name (e.g. "signup", "checkout_completed"). Required — values are scoped to one event at a time. | |
| limit | No | Max distinct values to return, ranked by count desc (1-200). Defaults to 50. | |
| period | No | Time period. Use "today", "yesterday", "7d", "30d", "90d", or a custom range as "YYYY-MM-DD:YYYY-MM-DD" (e.g. "2026-01-01:2026-03-31"). Defaults to "30d". | |
| property | Yes | Property key on the event (e.g. "plan", "source"). Required. Only string-typed properties are surfaced; pass a numeric/boolean property name and you'll get an empty `values` array. | |
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| event | Yes | ||
| period | Yes | ||
| values | Yes | ||
| property | Yes |