Get App
get_appRead-only
Everything AppTail holds about one app, at the depth you ask for. The base answer is the store listing in one storefront — the localised title and subtitle a shopper in country actually reads, the price and its currency, version, category, release dates, the publisher's ids. include adds sections: prices (what it costs in every storefront), ratings (every storefront's rating and vote count, pooled honestly, plus a daily series and per-storefront movement with history_days), charts (the charts it currently ranks in), popularity (organic reach), developer (the publisher and its portfolio), versions (release cadence) and screenshots. Works for ANY app in the store, not only the user's own. It does NOT return impressions, downloads or revenue — get_performance does, and only for the user's own connected apps.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app_id | Yes | Apptail app id. get_account for the user's own apps, search_apps for any other app in the store. Not the numeric id in an App Store URL (that is apple_app_id). | |
| country | No | Storefront to read the listing in (e.g. US, GB, DE). Defaults to the app's primary storefront. Title, subtitle, price, rating and screenshots all differ per storefront, so this changes the answer rather than filtering it — the `name` you get back is the title as published *there*, which for a localised app is not the title in any other market. `ratings.overall`, `ratings.by_country`, `ratings.history` and the `prices` section ignore it — they are every storefront — and `charts` is returned for all of them regardless. | |
| include | No | Extra sections to read. Omit for the listing alone, which is the cheap answer. `ratings`, `charts` and `popularity` need a Starter or Pro plan and are refused by name without one — the rest are free. Ask for what the question needs and nothing else: each section is a query. | |
| history_days | No | With `include: ["ratings"]`, also return the rating and the vote count day by day, this many days back from today, **and how each storefront moved over that window** — `ratings_gained` and `rating_change` on every row of `ratings.by_country`. Capped at 365. Ask for it whenever the question is whether a rating is *moving* or *where* it is moving: an average slides for weeks before enough people write about it, and a cross-section cannot tell a market that has always been low from one that fell this month. Ignored without the `ratings` include. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| icon | No | Absolute URL of the app icon. | |
| name | No | The app's title **as published in `country`** — the string a shopper in that storefront reads, which is also the string Apple indexes. It is not a translation of one canonical name: an app localised for Mexico has a different title there, and `get_app(country: "mx")` returning the US one is what makes an agent report a localised app as "not localized". Falls back to the app's canonical name when this storefront has not been crawled yet, and is null only while a freshly imported app is still being processed. | |
| tier | No | Apptail activity tier for `country`: 1 = currently charting, 2 = shipped more than two updates in the last 180 days. | |
| price | No | Download price in `country`, in that storefront's own currency and in major units — 9.99, never 999. 0 means free, which is what most apps are; `currency` names the money. Null when this storefront has no listing on file. | |
| store | No | Which store the app belongs to. | |
| app_id | Yes | Apptail app ID. This is the `app_id` every other tool expects. | |
| charts | No | Charts the app currently ranks in, across all countries and categories. Present only with `include: ["charts"]`; empty means it charts nowhere. | |
| prices | No | What the app costs to download, per storefront. Present only with `include: ["prices"]`. This is the download price alone: `has_inapps` says whether there is more to pay after that, and get_app does not return in-app purchase tiers. | |
| country | No | Storefront the metrics below were read from. Defaults to `primary_country`. | |
| is_mine | No | True when this is one of the asking account's own apps. Null when the call carried no account — get_top_charts answers without a token — which is "not known here", not "no". | |
| ratings | No | Present only when `ratings` is in `include` — a section you did not ask for is absent from the answer entirely, which is not the same as it being empty. | |
| version | No | Latest published version string. | |
| currency | No | ISO code of the currency `price` is in, derived from `country`. A price without it is a number, not an amount — several storefronts print a "$" and mean different money. | |
| includes | Yes | The sections actually read. A section absent from this list is absent from the answer because nobody asked for it — which is not the same as it being empty. | |
| subtitle | No | The subtitle under the title in `country` — thirty characters Apple indexes as heavily as the title, and the field most competitors leave generic. Null when the storefront listing has none, which is itself worth saying: an empty subtitle is unspent keyword weight. | |
| versions | No | Release history. Present only with `include: ["versions"]`. Cadence is the one competitor signal readable straight off the store: four releases in six weeks then eight months of nothing is a team that moved on. | |
| bundle_id | No | Store bundle identifier, e.g. "com.burbn.instagram". | |
| developer | No | The publisher and its portfolio — with the cap on `top_apps` declared. Present only with `include: ["developer"]`; null there when AppTail holds no profile for the publisher. | |
| has_inapps | No | Whether the app offers in-app purchases. | |
| popularity | No | Organic reach in `country`. Present only with `include: ["popularity"]`, and **null there when no storefront could be resolved** — a key that is present and null means "asked for, nothing to read", which an absent key does not. | |
| seller_url | No | Publisher's marketing website. | |
| console_url | No | Where to open this app in the AppTail console — the owner's own dashboard when `is_mine`, the research view otherwise. Null where this environment serves no console. End an answer about an app with it. | |
| screenshots | No | Present only with `include: ["screenshots"]`, and null there when no storefront could be resolved. | |
| support_url | No | Support page URL. | |
| apple_app_id | No | Apple's own numeric app ID, as it appears in App Store URLs. Not interchangeable with `app_id`. | |
| developer_id | No | Apptail developer ID. Pass this as `developer_id` to get_developer_info. Null if we hold no profile for the publisher. | |
| rating_count | No | Number of ratings in `country`. | |
| release_date | No | Date the app first appeared in the store (YYYY-MM-DD). | |
| rating_average | No | Mean star rating (1-5) in `country`. Null if the app has no ratings there yet. | |
| primary_country | No | Lowercase ISO country code of the app's main storefront, e.g. "us". | |
| primary_category | No | Store category ID. Pass this as `category` to get_top_charts. | |
| privacy_policy_url | No | Privacy policy URL. | |
| store_developer_id | No | The store's own publisher ID, as it appears in store URLs. Not interchangeable with `developer_id`. | |
| listing_storefronts | No | One storefront per language the listing is localized in, `primary_country` first, e.g. ["ru", "us"]. An app published in two languages is searched for in two storefronts; keyword discovery and tracking are per storefront, so cover each of these rather than only `primary_country`. | |
| is_tracked_competitor | No | True when the account already tracks this app as a competitor of one of theirs. False on a high-ranking rival is a suggestion worth making: add_competitors starts watching it. Null when the call carried no account. | |
| primary_category_name | No | Human-readable name of `primary_category`, e.g. "Health Fitness". | |
| current_version_release_date | No | Date the current version shipped (YYYY-MM-DD). Useful as an update-cadence signal. |