Ask a question about one of your segments
Asking about a Custom Segment used to mean naming every brand or product in it in the question, which worked until the list got long or the model dropped one. Now you pass the segment's id and ask for the plain metric. Membership gets resolved on the server and written into the query as a filter before it runs, so the answer covers that segment and nothing else.
**Finding one.** `list_custom_segments` returns your account's segments and what each one is a list of: brands, products, subcategories, sellers, or search terms. It answers instantly, with no query behind it. Pass the `collectionId` you want as `segmentId` on `query_analytics`, phrase the question as just the metric ("monthly revenue by brand"), and leave the members out of it. The response comes back with the segment it used and how many members that covered. If you want the member list itself rather than an answer, `resolve_custom_segment` hands it over.
**Narrowing inside it.** A filter already in your question gets intersected with the segment instead of replacing it. Ask about one brand inside a segment and you get that brand if it's a member, and no rows if it isn't, rather than quietly widening back out to the whole marketplace.
**Big segments.** Members come back largest first, 1,000 by default and 5,000 at most. Past that you get the largest members plus a flag and a note saying the list is partial, so a total doesn't end up presented as the segment's own when it only covers part of it. Some search-term segments run to millions of members, and those can't be scoped this way yet.
**Empty ones.** A segment whose criteria don't match anything right now is reported as empty rather than as a zero, since those two mean very different things.
Membership isn't a stored list. It's the segment's saved criteria, evaluated when you ask, so a scoped answer reflects the segment as it stands at that moment, the same as the app shows it.
Segment ids are scoped per marketplace, so an id from one won't resolve under another. And a segment is only ever readable by the account that owns it: one belonging to someone else looks exactly like one that doesn't exist.
