Skip to main content
When you finish this guide you have one tracked app, its first metadata snapshot and a set of keywords already tracking in its home storefront.

​
Import by name or store URL

The import dialog takes either the name of the app or its store URL in one field. A name searches the store you pick, App Store or Google Play, in the storefront you pick, and lists up to ten listings with their icon, developer and rating. Picking one imports it by its store id, exactly as if you had pasted its URL. Each name search reaches the store while you wait and spends one store lookup of the hourly allowance, so a search is only sent once you stop typing. A name can be up to 80 characters. A longer name is not sent: the field marks itself invalid and says how many characters it has, and the same rule applies to the name search of the competitor form. See Rate limits and quotas. A URL, a bare App Store id or a Google Play package name never searches. It imports as described below.
1

Type the app's name or copy its store URL

Any public listing URL works, for either store.
The import dialog accepts four forms of the same thing:An App Store id with leading zeros names the same listing, so 0123456789 imports 123456789.
2

Paste it into the import dialog

asobeast parses the store and the storefront from the URL.
3

Confirm the home storefront

The country segment in the URL becomes the home storefront. apps.apple.com/de/... imports a de home market. A bare id, or a URL with no country segment, falls back to DEFAULT_COUNTRY, which defaults to us. The dialog lets you override it before importing.
The home storefront is not just a label. It decides where the first snapshot, category ranks and reviews are collected; market listings are added for the markets you track keywords in. See Countries and markets.

​
What happens on import?

Four things, in order.
  1. The listing is fetched and snapshotted. asobeast stores the parsed fields and the raw payload, so a later parser fix can reprocess history rather than recollect it. The App Store subtitle is read from the public product page, and when Apple does not answer that page in time, the snapshot is stored without it and a backfill fills it in within a few minutes.
  2. Keywords are extracted from the indexed fields and auto tracked. Each one carries the source it came from, and each one is queued for its first popularity and difficulty score. Spaceless languages are split into words first. See How are auto tracked keywords chosen?
  3. A review backfill is queued. The first three pages of reviews are collected so ratings history starts with something in it.
  4. The first pass is scheduled. Every auto tracked keyword is queued for a rank check. The action queue for your workspace is generated when those first rank checks finish, so the first recommendations read real positions instead of an empty database.
The import then opens the guided setup, which walks through competitors, keywords and countries. See Complete the guided setup. The first pass is what fills the listing. Positions and scores arrive as the queue drains rather than waiting for the next scheduled run, so a fresh instance with an empty queue shows real numbers within minutes on the App Store and within tens of minutes on Google Play. See The daily pipeline and rate limits for the throughput those waits come from.

​
Importing twice costs nothing extra

Each piece of first pass work carries an identifier, so importing the same app twice collects nothing twice. Each import waits for its own first rank checks before it generates actions, so importing a second app never leaves that app out of its first recommendations. Generate now joins a run that is still waiting or running, and starts a new run once the last one has finished. The rank check identifier names the app on purpose. Keywords are shared: two apps tracking the same phrase in the same storefront are one keyword row, and one search records positions for every app tracking it. That sharing is what makes a scheduled run cheap, but it only helps while the search is still queued. A search that already ran cannot record a position for an app that started tracking afterwards, so a first pass that deduplicated against it would be dropped in silence and the new app would show nothing until the next daily run. Naming the app keeps each import’s promise, and costs at most one extra search per shared keyword on the day it is imported. The nightly pipeline builds its own daily~ prefixed identifiers so its flow can keep track of its own children, and it regenerates actions in place rather than queueing a job, so it is not on that list either. Auto tracked sources differ by store, because the stores index different fields. See App Store and Google Play for the full field comparison.

​
Refresh a listing

Refreshing fetches the listing again, writes a new snapshot and returns the difference against the previous one, so the response is meant to be read rather than discarded. It lists every field the refresh recorded in the changes feed, replaced or reordered screenshots, the icon, the price and What’s New included. Edited screenshot captions are not in it, because captions are read after the refresh answers; they appear in the changes feed once the new screenshots are read. See Screenshot captions. In a storefront that defaults to English, an import and a refresh also read the native localizations of the listing and a refresh lists their changes with the language. See Countries and markets. A refresh that cannot read the App Store product page keeps the subtitle from the previous snapshot instead of storing an empty one, so a throttled page never shows up as a removed subtitle in the changes feed or fires a change alert. Refresh is the only way to ask for a listing on demand, and it is rate limited per plan. Refresh while a market is selected on the metadata, overview or changes page refreshes that market’s listing instead, and the API takes ?country= for the same. Importing a url you already track returns the app you have without reaching the store: a second import would otherwise write a snapshot that quietly became the new baseline, and the change it captured would never appear in the changes feed. Field level changes also land in the changes feed, where they are kept alongside changes asobeast detected on its own schedule. See Watch listing changes.

​
Troubleshooting

  • The URL is rejected. The parser accepts App Store listing URLs, Google Play details URLs, bare App Store ids and bare Google Play package names. A search result URL, a developer page, an album, a bundle, an editorial story or a shortened link is refused at once with the input echoed back, before any store request. Open the listing in a browser and copy the address bar.
  • The import answers 422. The App Store listing is not available on iPhone, so it can never rank in the search asobeast reads. That covers apps sold only on iPad, the Mac App Store, Apple Watch or Apple Vision Pro. The same applies when you add it as a competitor. See App Store and Google Play.
  • The import answers that the store did not answer. The App Store or Google Play did not answer within 20 seconds, so nothing was imported. Try again in a few minutes. Importing an app that is already in the workspace returns it instead of importing it twice, so a retry is always safe.
  • The app exists in one storefront but not another. Storefronts carry different catalogs. Import using a URL for a storefront where the app is actually published, then track keywords in the other market.
  • The import fails with a parse error. A store response shape changed. The job fails and BullMQ retries it with backoff, so check the queue dashboard at /admin/queues for the retry state. Request handling is unaffected. See The daily pipeline and rate limits.
  • Positions are empty right after importing. Expected for a moment. The rank checks are queued at import and drain at the store rate limit, so watch the first run panel on the app overview page, or the run pill beside Run daily, rather than the clock. If they stay empty, check the queue dashboard at /admin/queues for failed jobs.
  • The subtitle is empty right after importing. Apple sometimes answers the App Store product page with HTTP 429, and the subtitle only exists on that page. The import still succeeds, the API logs subtitle scrape failed, and a resolve-subtitle job retries for up to about eight minutes. The first run panel shows Listing captured as waiting until it lands, and the overview reloads the listing when it does. If the job exhausts its retries, it shows as failed on /admin/queues and the next refresh fills the subtitle.
  • The first pass did not run at all. The import itself succeeds even when the queue refuses the work, because the listing, its snapshot and its keywords are already stored and only the head start is missing. The API logs why, and the next daily run collects what the first pass would have. Check /admin/queues if it keeps happening.
  • Trend based actions stay thin for the first week. Expected. The rules that compare a before and an after need several days of captures before they can fire at all, so the action queue grows over the first week rather than arriving full.

Track keywords

Add keywords, import a list and add markets.

Track competitors

Competitors cost no extra store requests on keywords you already track.
Last modified on October 17, 2026