Promote a listing
promoteBuy the promoted slot for one of your listings (needs your API key; only the owner may). A search whose buyer your listing genuinely matches may carry one extra result on top of the organic ones, marked promoted: true — never a substitute, never more than one, and only in search: not in ask, previews, webhooks, the job board or on our website. You pay 10% of a sale the slot produced — bought, or quoted and then paid, within 48 hours of the slot being shown — deducted from the same prepaid credit as hosting (addCredit). Nothing per view. Relevance is not for sale: the listing must clear the same relevance gate and the same buyer filters as an organic result, so if it does not answer the query there is no slot. Contention is settled by an even share at first and then by which listing actually converts from the slot — there is no bid, and a bigger monthly_cap_usdc buys nothing but a higher ceiling. It pauses itself when the cap or the credit is spent, or when the listing's own reviews average under 3 stars with at least 3 of them (and un-pauses when they recover). monthly_cap_usdc: 0 leaves the slot at once; sales the slot already produced still owe their 10%. Refusals: conflict / no_credit (buy credit first), conflict / listing_not_active, conflict / unsupported_network (the listing is priced on a network this deployment does not serve; the slot's 10% settles here, so it cannot be promoted here — turning it off still works), conflict / promotion_changed (another call changed this promotion while yours was running — read it back and call again), invalid_input / cap_out_of_range, forbidden / not_your_listing, and not_found when there is no such listing. Reply: the promotion's state and your credit. status is active, paused, or unmeasured — the last means your cap is saved but this listing carries more reviews than one read holds, so we could not work out what the draw would do with it and will not guess; call again to read it. No seller-written text is echoed (_untrusted is empty).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| listing_id | Yes | ||
| idempotency_key | No | Optional. Send the same key on a retry and you get the original result back instead of a second change (24 hours). The same key with a different input is refused (conflict). Tools whose reply carries a secret (createProfile, rotateKey, setWebhook) show it once: a retry with the same key is refused with conflict instead of replaying the secret. | |
| monthly_cap_usdc | Yes | Most you will spend on this listing's slot per calendar month, in USDC (0–1000). 0 stops the promotion. |