Avatar catalog search returns few results: auto_expand explained

If POST /v1/avatar-catalog/search returns fewer avatars than you filtered for, check data.relaxed_filters in the response. auto_expand is on by default, and when results are thin, Sume relaxes the search in a fixed order: soft text first, then product_category, then best_for. Language, visibility and ownership are never relaxed. Send auto_expand: false to keep strict filtering.

When does a search count as thin?

The min_results field is the threshold, default 5 and range 1 to 100. The schema says secondary filters may relax until at least that many results are available when possible. Setting min_results to 1 makes expansion rarer; a higher number makes it more likely.

How do I know what was relaxed?

The response carries relaxed_filters, an array of the filters or matching rules that auto-expand relaxed; it is empty when nothing was relaxed. It also returns candidate_count, the number of candidates loaded before scoring, and filters, the filters the request used.

Log relaxed_filters next to the query. If your UI promises "beauty creators" and the list contains product_category, the grid is showing a wider set than the label says.

{
  "query": "creator",
  "filters": {
    "status": "ready",
    "product_category": "beauty",
    "use_case": "beauty_ugc",
    "language": "ko"
  },
  "min_results": 3,
  "auto_expand": false,
  "limit": 10
}

Which filters can I send?

These are the filters in the request schema; each one narrows the candidate set.

• status: processing, ready, failed or archived; default ready.
• visibility: public or private; private results are limited to your workspace.
• product_category (string) or product_categories (up to 20), use_case, language.
• best_for: a string or up to 20 strings.