Audience filters and dashboard links

Use Audiences to filter the user's customers and to share a dashboard link to that set. The same filters answer "who" questions — they are not a full leaderboard sort.

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, totalRenewals (thresholds, not a 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. Reuse an existing audience from list-audiences if one already matches. Otherwise create-audience with the same groups/conditions rule shape as the filter rule. Body is only name and rules. create-audience persists a saved audience, so get explicit confirmation first.
3. get-audience with expand: ["customer_sample"]. Sample rows include total_spent, status, and latest product — not every filter field. Rank or name customers only from fields the sample returned.
4. Number fields like totalRenewals are filters, not sample columns. Filter on a high threshold and report the sample; do not invent a value that was not returned.
5. Say it is a sample of matches, not an exhaustive ranking of every customer. Filtering and a customer_sample cannot prove a global superlative (who renewed or spent the most). After you try the steps above, say that: you can show high-threshold matches, not name a unique maximum.
6. Share the dashboard link (constructing a link or linking to a saved audience).

Constructing a link

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

Link with customer_list_id — the field create-audience, get-audience, and list-audiences return 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\"}"
        }
      ]
    }
  ]
}