Audience filters and dashboard links

Use Audiences to filter the user's customers and to share a dashboard link to that set. Filters select the segment; sort_by / sort_direction on preview-audience order the returned sample.

There is no first-class CLI command for audiences. Do not tell the user RevenueCat cannot filter or segment customers.

Identifying, filtering, or ranking customers

Audiences filter on the fields below, including:

• Product and duration — latestProduct, allPurchasedProductIds, latestPurchasedOffering, entitlements, offers
• Spend and renewals — totalSpent (filter, and sort_by: total_spent), totalRenewals (filter only; there is no renewal sort)
• Subscription state — status, trial, auto-renew intent, ownership
• Store, platform, and country — platform, latestStore, country, storefront
• Dates — first seen, purchases, renewals, expiration, trial, cancellation
• Attribution and experiments — media source, campaign, ad group, keywords, price experiment
• Identity and custom attributes — app user ID, email, locale, customAttribute:{key}

Map the question onto those fields, filter, then read a sample.

1. Fetch project-specific values with get-audience-filter-options for any field marked project-specific that the question uses (project_id, fields).
2. Call preview-audience with project_id and body.rules in the filter rule shape (for a saved audience from list-audiences, pass body.audience_uuid instead). It is read-only and saves nothing. Do not create-audience just to inspect a segment.
3. To rank or name a superlative, pass sort_by (status, latest_auto_renew_intent, first_seen_at, last_seen_at, total_spent) and sort_direction (asc default, or desc) as top-level parameters, not inside body. sort_by: total_spent with sort_direction: desc returns the highest spenders first, so the first customer_sample row is the top spender. The sample is capped (typically 50): it is the top or bottom matches, not every customer.
4. Answer "how many" from stats (total_customers, active_subscriptions, active_trials, total_revenue in currency), never from the sample size. When stats.is_approximate is true, give counts and revenue as approximate ("about 6,400 customers").
5. Name customers only from fields customer_sample returned (app_user_id, email, status, total_spent, latest_product_name, first/last seen). Without sort_by the sample is unordered: say it is a sample of matches, not a ranking.
6. totalRenewals is a filter only, not a sort_by value or a sample column. Filter on a high threshold and report the matches; do not invent a renewal count or claim a unique maximum.
7. Share the dashboard link. The preview-audience result for body.rules includes a line starting "Dashboard URL for this result"; link that exact URL. Build one yourself (constructing a link) only when no tool result gave you a URL.

Constructing a link

Use this only when no tool result gave you a "Dashboard URL for this result" line. Two shapes: a filtered all-customers link for ad-hoc exploration, and a saved-audience link after create-audience.

1. Get the project ID from list-projects. For dashboard URLs, strip the proj prefix.
2. Pick fields and operators from the field tables. Do not invent field or operator names.
3. For project-specific fields, fetch valid values with get-audience-filter-options first.
4. Assemble the rule JSON: one group per OR-branch, conditions inside a group for AND, values encoded per value formats.
5. Serialize and URL-encode the rule with a short script (see encoding the rule) — do not encode by hand.
6. Append it as the filters query param on https://app.revenuecat.com/projects/{project_id}/customer-lists/all-customers.

URL format

https://app.revenuecat.com/projects/{project_id}/customer-lists/all-customers?filters={encoded_rule}

• {project_id} — short hex ID from list-projects with proj stripped.
• Filters only work on the all-customers list. The unfiltered Audiences home is /projects/{project_id}/customer-lists.

Linking to a saved audience

The create-audience and get-audience results include a "Dashboard URL for this result" line; link that exact URL. If you only have list-audiences output, link with customer_list_id, the field returned alongside id:

https://app.revenuecat.com/projects/{project_id}/customer-lists/{customer_list_id}

An audience's id (aud…) and its customer_list_id (list…) are different identifiers. The dashboard route only resolves customer_list_id; an aud… id in that slot renders "Audience not found".

Correct:

https://app.revenuecat.com/projects/56965ae1/customer-lists/list7c1f0a2b93

Wrong (the audience id instead of the customer_list_id):

https://app.revenuecat.com/projects/56965ae1/customer-lists/audf0269cdf3df84dd2

Do not add a filters param to a saved-audience link — the audience carries its own rules. If the response has no customer_list_id, link to /customer-lists and name the audience rather than guessing an id.

Offering to save the filtered view

A filtered all-customers link is ad-hoc — nothing about it is saved. Say so in one short sentence when you share one, and offer to save it: "This view isn't saved — want me to save it as an audience so you can find it later?"

Offer once per conversation. If they accept, call create-audience with the same rule you built for the link, then link to it. Do not offer when the link is already to a saved audience.

The filter rule

The filters value is URL-encoded JSON with this shape:

{
  "groups": [
    {
      "conditions": [{ "field": "platform", "operator": "is", "value": "android" }]
    }
  ]
}

• Conditions within a group combine with AND.
• Groups combine with OR.
• value is always a JSON string — booleans as "true"/"false", numbers as "42", lists as a comma-separated string, date ranges and relative dates as stringified JSON (see value formats).

Correct (compact JSON, whole value URL-encoded):

?filters=%7B%22groups%22%3A%5B%7B%22conditions%22%3A%5B%7B%22field%22%3A%22platform%22%2C%22operator%22%3A%22is%22%2C%22value%22%3A%22android%22%7D%5D%7D%5D%7D

Wrong (raw JSON, spaces, unencoded quotes/braces):

?filters={"groups": [{"conditions": [...]}]}

Encoding the rule

import json
from urllib.parse import quote

rule = {
    "groups": [
        {"conditions": [{"field": "platform", "operator": "is", "value": "android"}]},
    ]
}

print(quote(json.dumps(rule, separators=(",", ":")), safe=""))

Fields

The Audiences preview table shows only Customer, Subscription Status, Auto-Renewal Status, Spent, and Latest Purchase. Other attributes appear in the CSV from Export all, or on a customer's profile.

Use these exact field strings. See Audiences.

Text fields

Operators: is, isNot, contains, doesNotContain, isEmpty, isNotEmpty.

Enum fields

Operators: is, isNot, isAnyOf, isNotAnyOf, isEmpty, isNotEmpty.

Boolean fields

Operators: is, isNot. Value is exactly "true" or "false".

Number fields

Operators: equal, notEqual, greaterThan, greaterThanOrEqual, lessThan, lessThanOrEqual, isEmpty, isNotEmpty. Value is a numeric string, e.g. "50".

Date fields

Operators: before, beforeOrOn, on, after, afterOrOn, within, between, notBetween, isEmpty, isNotEmpty.

Custom attribute fields

Filter with customAttribute:{key} (e.g. customAttribute:favorite_team). They use the enum operators. Fetch known keys and values with get-audience-filter-options — never invent a key.

Value formats

• isEmpty / isNotEmpty — set "value": "" (the value is ignored).
• isAnyOf / isNotAnyOf — comma-separated string: "value": "US,CA,MX".
• before, beforeOrOn, on, after, afterOrOn — calendar date "value": "2026-01-31" (YYYY-MM-DD).
• between / notBetween — stringified JSON with exactly from and to: "value": "{\"from\":\"2026-01-01\",\"to\":\"2026-01-31\"}" (from ≤ to).
• within — stringified JSON with exactly direction, value, unit: "value": "{\"direction\":\"last\",\"value\":30,\"unit\":\"days\"}". direction is last or next; unit is minutes, hours, or days; value is a non-negative integer. before/beforeOrOn/after/afterOrOn also accept this relative format (not on).

Fetching project-specific values

Fields marked project-specific (mediaSource, campaign, adGroup, ad, keyword, creative, priceExperimentId, latestProduct) and custom attributes only match values that exist in the project's data. Fetch with get-audience-filter-options:

• project_id (required)
• fields (required, at least one) — any of the eight fields above, customAttribute:{key} for one custom attribute, or customAttribute to list every custom attribute key with its values.

A custom-attribute entry may come back with cardinality_exceeded: true — a value the user stated verbatim can still be valid even if it is not in the list.

Fixed-value fields (country, platform, status, …) are not served by this tool — use the tables above. Never guess project-specific values — a filter on a non-existent value silently matches zero customers.

Example: building a link

User wants: "Android customers acquired through Instagram" in project proj56965ae1.

Rule (both conditions in one group — AND):

{
  "groups": [
    {
      "conditions": [
        { "field": "platform", "operator": "is", "value": "android" },
        { "field": "mediaSource", "operator": "is", "value": "Instagram" }
      ]
    }
  ]
}

Link:

https://app.revenuecat.com/projects/56965ae1/customer-lists/all-customers?filters=%7B%22groups%22%3A%5B%7B%22conditions%22%3A%5B%7B%22field%22%3A%22platform%22%2C%22operator%22%3A%22is%22%2C%22value%22%3A%22android%22%7D%2C%7B%22field%22%3A%22mediaSource%22%2C%22operator%22%3A%22is%22%2C%22value%22%3A%22Instagram%22%7D%5D%7D%5D%7D

User wants: "customers on iOS or Android who are currently trialing and were first seen in the last 30 days".

{
  "groups": [
    {
      "conditions": [
        { "field": "platform", "operator": "isAnyOf", "value": "iOS,android" },
        { "field": "isCurrentlyTrialing", "operator": "is", "value": "true" },
        {
          "field": "firstSeenAt",
          "operator": "within",
          "value": "{\"direction\":\"last\",\"value\":30,\"unit\":\"days\"}"
        }
      ]
    }
  ]
}