recommend_service
Choose WHICH plan option to order, once you know what to buy and for how many. Use it instead of comparing options yourself from search_catalog or get_service. Takes a service (or a platform plus a goal), a quantity, an audience and a preference. Returns one recommended option plus the cheapest, highest-tier and fastest-listed alternatives. Each pick carries the price per 1000, the total for this quantity, the quantity range it accepts, its quality tier, typed axes such as country or watch length, the listed delivery speed and start window, a sensitive flag marking a deliberate product such as a negative reaction, and short reasons written for the buyer. Branch on the typed fields; the reasons are prose in the requested locale and state only what an option gives, so their absence is never a drawback. One reason states how many independent delivery pools can serve the option, when two or more can: it is a count of the ways we can deliver it, not a promise about any one order, and a pick without it is not worse. The response also says how many options were considered, how many fit, and why the rest fell out (rejected: audience_mismatch, quantity_below_min, quantity_above_max, dominated). It carries quoted_at and catalog_version: the version fingerprints the option data the answer came from, so if you recommend, ask the user, then order, re-call and compare catalog_version to know whether the card changed in between. Prices are live at order time; placing an order re-prices from the same data get_quote does, so treat quoted_at as when this answer was computed, not as a price hold. tradeoffs compares each alternative with the lead as data (price and total deltas, quality steps, listed speed ratio, start bucket delta, max quantity delta, plus gives and costs naming the dimensions it wins and loses on; null means one side lists nothing). Use it to CHOOSE and to explain a choice as what each option gives ("$18.60 less for one tier lower and twice the listed rate"); never present a pick to the user as a percentage more expensive than another. Identify the service by service_id (from search_catalog) OR by platform + goal (the deliverable, e.g. platform "youtube" and goal "short-views" or "followers"). Read-only: it places no order. Pass the returned option_id as service_option_id to get_quote and create_paid_order (this endpoint lists it while the accountless x402 payment channel is on), or create_checkout when a person will pay in their own wallet instead (listed while checkout sessions are on).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| goal | No | The deliverable metric key (followers, likes, views, short-views, members, comments, ...). Used with platform when service_id is omitted. | |
| locale | No | Language of the option labels and the reasons: en (default), fa, ru, uz or id. The typed fields are locale-independent, so pass the user's language freely. | |
| audience | No | "worldwide" (default) for untargeted delivery, or "<axis>:<value>" such as "country:usa" or "emoji:❤️". On a vote service the poll answer is an audience too ("answer:option-2", "answer:yes"): ask the user which answer, never assume one. The response lists the audiences the service serves. | |
| platform | No | Platform key (telegram, instagram, tiktok, youtube, ...). Used with goal when service_id is omitted. | |
| priority | No | "balanced" (default), "cheapest", "quality" or "fastest": which pick leads. fastest ranks on the LISTED delivery rate then start window (the listing's own claims); when no eligible option lists either it falls back to balanced. | |
| quantity | Yes | The quantity the user wants to order; every pick accepts it. | |
| service_id | No | The service id from search_catalog. Optional when platform and goal are given. |