Where candidates come from
Competitors and reviews feed the home market only, because asobeast captures both for the home storefront.
One phrase found by several sources is listed once, under the source with the highest starting relevance. A phrase the app tracks in that market, active or paused, is left out, and so is a phrase you dismissed. Each market keeps the best 200 candidates, ordered by relevance and then popularity.
How the rank is found
When another search of the same phrase in the same storefront ran today or yesterday, for any workspace on the instance, its stored results answer for free. They hold the top 50, so a discovery read this way shows depth 50. A phrase whose stored results do not contain your app may still rank between 51 and 200, so it stays due for a search of its own. Otherwise one search reads the top 200 for the phrase. The rank column reads like the tracked table: a number is the position,>50 or >200 means checked and not found within that depth, and a dash means not checked yet.
A search of a phrase nobody tracks stores its results for everybody, exactly as a daily check does. A search of a phrase some workspace tracks stores nothing, because the daily run owns that day’s results. A discovery never writes a position history for your app until you track it.
The weekly cap
Each app gets at most 40 searches a week on the App Store and 20 on Google Play, where one search costs about eight requests. The week starts on Monday at 00:00 UTC. Refresh shares the same cap, so a refresh after the Monday run usually finds nothing left to search, though it still rebuilds the list and reads other searches for free. The cap applies on self hosted instances too, because it protects the address of the machine that runs asobeast. The weekly run starts onCRON_DISCOVERY, Monday 07:30 UTC by default; an empty value switches it off. See the configuration reference. Its searches queue behind the daily run and never delay it. A phrase is searched again after seven days.
Refresh spends one deep search of the plan’s on demand allowance, and only when it queues at least one search. See Rate limits and quotas.
States
Recommended marks the first 50 in list order.
Opportunity needs popularity and difficulty, and a discovery is never scored: a score costs several store requests and would spend the weekly budget many times over. Popularity and difficulty therefore come from a score some tracker of the phrase already produced, or, for an App Store term Apple lists, from Apple’s own popularity. Opportunities is often empty until keywords are scored. Tracking a discovery queues its first score.
Track, dismiss and auto track
Tracking a discovery spends the plan’s keyword room the way a manual add does. What does not fit stays a discovery, and the answer says how many did not fit your plan. A phrase another app of the workspace already tracks in that market costs no extra room. A position found today or yesterday becomes the first position of the tracked keyword; every other phrase gets its first check within minutes. The tracked keyword’s source is Suggested for review, popularity and other app phrases, and Title, Subtitle, Description or Competitor for the others. See Popularity, difficulty and opportunity. Dismiss is permanent for the phrase. If you stop tracking a phrase that came from discovery, it returns to the list with what discovery last observed. Auto track ranked tracks every ranked discovery that fits at once, and every later search that finds the app tracks its phrase too. Switching it off leaves tracked keywords alone.Through the API and MCP
A read scoped token can list, a write scoped token can also change. Agents read the list with the
keyword_discoveries tool; tracking is not an MCP write tool. See asobeast API and the MCP tool reference.
Cost and storage
GET /jobs/budget reports the weekly searches in a discovery block per store and in total, apart from the daily total. See Capacity. A discovery that no run has proposed for 60 days is removed, except a dismissed one, which is kept so the phrase stays dismissed. The search results a discovery stores cost about 5 MB per app once retention settles.
Troubleshooting
Nothing is listed
Nothing is listed
The listing of the app may not be captured yet, the store may no longer list the app, or none of the sources holds a phrase. A delisted app keeps its list but gets no searches, and neither does a market where the app is not sold or where you no longer track any keyword.
The last check date never moves
The last check date never moves
The weekly cap may be used, the workspace may be paused (suspended, or without a plan in force on a hosted instance), or
CRON_DISCOVERY may be empty.