> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asobeast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inspect any keyword

> Research one phrase in one storefront before any app tracks it: the top 50 search results, the store autocomplete, popularity, difficulty and opportunity with their source, a summary of the top 10 and the change since the last run.

A keyword inspection answers one question before you commit to a keyword: is this phrase worth tracking in this storefront? It reads the live store for any phrase, whether or not one of your apps tracks it, and keeps the answer in your workspace so you can come back to it and compare it with a later run.

Tracking a keyword is still how positions are collected every day. An inspection is a single reading you request, and nothing about it is tracked afterwards. See [Track keywords](https://docs.asobeast.com/guides/track-keywords.md) for the daily side.

## Run an inspection

Open **Keyword inspector** in the sidebar, type the phrase as a user would type it into store search, pick the store and the storefront, and start the inspection. The same request is `POST /keyword-inspections` on the API with `keyword`, `store` and `country`, and `inspect_keyword` for an agent connected over MCP with a write token.

The phrase is normalized the way a tracked keyword is: lower case, at most 80 characters and five words. A storefront is a lowercase two letter code the store serves, and the same phrase in two storefronts is two inspections. See [Countries and markets](https://docs.asobeast.com/concepts/countries.md).

The inspection runs as a store job, so the request answers at once with a pending inspection and the page fills in when the job finishes. The page checks every 15 seconds for ten minutes, and after that a **Check again** button reads the inspection on demand. That is usually within a minute, and longer when the store queue is busy with the daily run or the weekly scoring, because an inspection waits in the queue behind that work before it reads the store. An agent reads the result with `get_keyword_inspection`, and the API with `GET /keyword-inspections/{id}`. A phrase and storefront whose inspection is still pending answers that inspection instead of queuing a second one.

### What it costs

Each queued inspection spends one on demand score, the same allowance as scoring a tracked keyword, so on a metered instance it counts against the daily allowance of your plan. A request the validation refuses, a repeat of a pending inspection and an inspection the store queue would not take spend nothing. See [A spent on demand allowance names its action](https://docs.asobeast.com/api-reference/rate-limits.md#a-spent-on-demand-allowance-names-its-action).

Every inspection is one search plus a few autocomplete lookups, the same evidence the scoring job reads for a tracked keyword. Google Play adds a detail lookup for each of the top 10 results, which is where its ratings and update dates come from. The requests go through the same store rate limits as the daily run. See [The daily pipeline and rate limits](https://docs.asobeast.com/concepts/pipeline.md).

### When an inspection fails

A store that times out or blocks the request is retried like any other store job. When the last attempt fails, the inspection is marked failed with the reason the store gave, and you can start a new one.

The time an inspection waits in the queue never counts against it. Once its job starts reading the store, it has ten minutes to finish before it is marked failed. An inspection that has still not started a day after you requested it never reached the store, and it is marked failed so you can start a new one.

## Read the scores

An inspection carries the three keyword scores on the 0 to 100 scale: popularity as `volume`, difficulty as `difficulty100`, and opportunity, which weighs the two together. The scoring is the same as for a tracked keyword, so the numbers of an inspection and of a tracked keyword in the same storefront are comparable. See [What are the three scores?](https://docs.asobeast.com/concepts/scoring.md#what-are-the-three-scores) and [How is opportunity calculated?](https://docs.asobeast.com/concepts/scoring.md#how-is-opportunity-calculated)

Opportunity here is the keyword's own, without the relevance of any app, because an inspection belongs to no app.

The provenance names the source of the popularity and its confidence. `APPLE_ADS_POPULARITY` is Apple's own number, available when the instance has an Apple Ads connection, and every other source is an estimate from public signals. See [What evidence does a score carry?](https://docs.asobeast.com/concepts/scoring.md#what-evidence-does-a-score-carry) and [Can AsoBeast use Apple's own numbers?](https://docs.asobeast.com/concepts/scoring.md#can-asobeast-use-apples-own-numbers)

### Search results and autocomplete

The results list the top 50 apps the store returned, in order, with title, developer, rating, rating count and the date of the last update where the store reports it. Each title is graded against the phrase the same way as the search results of a tracked keyword: `phrase` holds the phrase, `words` holds every word in any order, `partial` holds some of the words and `none` holds none of them. The words of the phrase are marked in each title. Positions are 1 based. See [Positions and rank depth](https://docs.asobeast.com/concepts/positions.md).

The suggestions are what the store autocomplete offers for the phrase, up to ten, in the store's order. A phrase the autocomplete offers is one users type, and its longer suggestions are candidates for an inspection of their own.

### Competition summary

The summary reads the top 10 results, the first screen of answers a searcher sees:

| Figure | What it tells you |
| - | - |
| Median and strongest rating count | How established the apps you would have to pass are |
| Apps over 100,000 ratings | How many heavyweights hold the first page |
| Exact and full title matches | How many results target the phrase in their title |
| Median days since update and apps updated in the last 30 days | How actively the leaders are maintained |

A first page held by a few heavyweights with the phrase in their titles is hard to break into, however popular the phrase is. A page of results that only mention part of the phrase, or that have not been updated in months, is the opening the opportunity score looks for.

## Compare with the previous run

Every inspection of a phrase and storefront is kept for `RETENTION_KEYWORD_INSPECTIONS_DAYS`, 180 days by default, so running it again later shows how the search moved. The newest inspection compares itself with the last completed one of the same phrase and storefront: its popularity, difficulty and result count, and the apps that entered or left the top 10 in between. See the [configuration reference](https://docs.asobeast.com/configuration/reference.md).

The history lives on the keyword inspection page, which lists the newest 50 runs of the workspace. `GET /keyword-inspections` lists the same runs and filters them to one phrase, store or storefront, and an agent lists them with `list_keyword_inspections` and the same filters.

Inspections belong to your workspace. Another workspace on the same instance never sees them, even for the same phrase, and they are part of the workspace export and are erased with the workspace. Deleting an inspection removes that run only. See [Data model](https://docs.asobeast.com/concepts/data-model.md).

## Related

> [card] [Track keywords](https://docs.asobeast.com/guides/track-keywords.md)
>
> Collect positions every day for the phrases worth keeping.

> [card] [Keyword scoring](https://docs.asobeast.com/concepts/scoring.md)
>
> How popularity, difficulty and opportunity are calculated.

> [card] [MCP tool reference](https://docs.asobeast.com/mcp/tools.md)
>
> The inspection tools an agent can call.

> [card] [Rate limits](https://docs.asobeast.com/api-reference/rate-limits.md)
>
> The on demand allowance an inspection spends.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.