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 from a store URL

1

Copy the 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 snapshots, category ranks and reviews are collected. 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.
  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 traffic and difficulty score.
  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 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. Refresh is the only way to ask for a listing on demand, and it is rate limited per plan. 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 or iPad, for example an app sold only on the Mac App Store, Apple Watch or Apple Vision Pro. asobeast reads iPhone and iPad search, where such an app never ranks, so it refuses the listing before storing anything. The same applies when you add it as a competitor.
  • 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 rather than the clock. If they stay empty, check the queue dashboard at /admin/queues for failed jobs.
  • 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, add markets and paste the iOS keyword field.

Track competitors

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