Add Keywords
add_keywordsStart tracking search terms for one of your apps, in one storefront. Send terms, or keyword_ids for suggestions returned by discover_keywords — a suggestion MUST be added by id, because re-resolving its term can land on a different keyword row. Counts against the plan's per-app keyword limit; dry_run reports what would happen without writing anything. Terms already in the corpus come back under already_tracked rather than as an error — that is the state the caller asked for.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| app_id | Yes | Apptail app id for one of YOUR apps — get it from get_account. Not the numeric id in an App Store URL (that is apple_app_id). Keywords are tracked per app. | |
| country | Yes | Storefront to track these terms in, ISO 3166-1 alpha-2 (e.g. US, GB, DE). Required and not defaulted: a term tracked in the wrong storefront is a wasted keyword slot. Ranks are per storefront — the same term ranks differently in each. | |
| dry_run | No | Report what would be added, and how many slots are left, without tracking anything. Nothing is written and nothing counts against the plan. | |
| keywords | No | Search terms to start tracking, as a user would type them into the App Store (e.g. ["fitness tracker", "workout app"]). Send the whole batch in one call rather than one term per call. Terms we have never seen are created. Every added term whose results are more than a day old is crawled straight away, and positions usually land within a few minutes: a get_keywords read made immediately after this call shows those terms as unmeasured, which means not crawled yet and not that the app is missing from the results. Either this or `keyword_ids` is required. | |
| keyword_ids | No | Apptail keyword ids to start tracking — the `keyword_id` on a discover_keywords row. Use this rather than the term whenever you have an id: a term is re-resolved and can land on a different keyword row than the one you were shown. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| added | Yes | Terms now being tracked. Under `dry_run` this is what would be added and nothing was written. | |
| limit | Yes | Keywords this plan allows per app. -1 means unlimited. | |
| app_id | Yes | The app these terms are tracked for. | |
| country | Yes | The storefront they were tracked in. | |
| dry_run | Yes | True when nothing was written. | |
| skipped | Yes | Everything not added: the union of `already_tracked` and the terms that could not be resolved in that storefront or that ran out of plan room. Do not report this count as a failure without reading `already_tracked` first. | |
| remaining | No | Keyword slots left for this app on this plan after the call. Null when the plan is unlimited. Zero means the next add is refused. | |
| added_count | Yes | Size of `added`. | |
| limit_reached | No | Set when the account's plan limit stopped the run before the whole list was added. A ceiling, not a fault — say what was capped rather than retrying. | |
| skipped_count | Yes | Size of `skipped`, both reasons together. Subtract `already_tracked` before calling anything a problem. | |
| already_tracked | Yes | The subset of `skipped` that the app was already tracking. **This is the end state that was asked for, not a fault** — a term already in the corpus needs no retry and no apology. What is in `skipped` but not here is the half worth mentioning: a term that does not exist in that storefront, or one the plan had no room for (see `limit_reached`). |