tools / history

history

read-only

Rank history report

The daily rank series, read back — including “what dropped?” in one call.

history reads the server-side rank series your daily managed run and track snapshots have been writing: one series per keyword × app × storefront, with snapshot count, current/previous/best/worst rank, the time range covered, and optionally the last N raw records.

The flag that earns its keep is dropsOnly: true: only series whose newest snapshot is worse than the one before — fell in position, or fell out of the top 200 entirely. That makes “did anything drop overnight?” a single cheap call an agent can run every morning and act on.

Reads are pure database — no Apple traffic, no meaningful latency — so filtering by app, keyword, country or since and re-querying is free. Per-series stats cover the newest 365 snapshots.

worked example

Read one tracked series with its last 3 raw records.

tools/call → history

{
  "name": "history",
  "arguments": {
    "keyword": "music",
    "records": 3
  }
}

history → structuredContent (excerpt)

{
  "series": [
    {
      "keyword": "music",
      "appId": 324684580,
      "country": "US",
      "snapshots": 11,
      "current": 3,
      "best": 1,
      "worst": 3,
      "previous": 3,
      "firstTs": "2026-07-23T17:21:24.758Z",
      "lastTs": "2026-07-29T06:57:49.665Z",
      "records": [
        { "ts": "2026-07-28T06:00:05.509Z", "rank": 1 },
        { "ts": "2026-07-29T06:00:08.008Z", "rank": 3 },
        { "ts": "2026-07-29T06:57:49.665Z", "rank": 3 }
      ]
    }
  ]
}

real response, captured 2026-07-29 — trimmed only where marked with …

Eleven snapshots in six days without anyone polling: the 06:00 UTC timestamps are the managed daily run doing its job.
The series caught real movement — rank 1 on July 28, rank 3 the next morning. best: 1 / worst: 3 brackets the whole window.
With dropsOnly: true this series *would* be returned today (3 is worse than the previous 1 across the last two daily runs) — the morning drop-check is one call, not a spreadsheet.

when to use it

The morning question, automated: dropsOnly: true after each daily run, and an agent that opens an investigation only when something actually fell.
Attributing movement to releases: since scoped to a ship date shows before/after per keyword and market.
Reporting: best/worst/current per series is the ASO progress summary stakeholders actually read.
It only knows what was tracked — series exist from the day a combination enters track_config, so register targets before you need their history.

description — as served to agents

Read this account's server-side rank history (written by track and the daily managed run): one series per (keyword, app, storefront) with snapshot count, current/previous/best/worst rank and time range. dropsOnly=true returns only series whose latest snapshot is worse than the previous one (rank-drop check). Filterable; no network. Series stats cover each series' most recent 365 snapshots.

input

keyword

string

Only series for this exact keyword

appId

integer

Only series for this app

country

string

Only series for this storefront

since

string

Only records at/after this ISO date/timestamp (date-only values are interpreted as UTC midnight)

records

integer

Include the last N raw records per series

dropsOnly

boolean

Only series that dropped (rank got worse, or fell out of the top 200)(default false)

output

series *

object[]

keyword *

string

appId *

integer

country *

string

snapshots *

integer

current *

integer | null

rank in the latest snapshot

integer | null

rank in the snapshot before the latest; absent with one snapshot

best *

integer | null

best (lowest) rank ever; null if never ranked

worst *

integer | null

firstRank *

integer | null

firstTs *

string

lastTs *

string

records

object[]

most recent raw records, oldest first; only when records > 0 was requested

ts *

string

keyword *

string

appId *

integer

country *

string

rank *

integer | null

pairs with

track_configno tracked set, no history›trackadd a snapshot right now instead of waiting›rankinvestigate a drop with a live look at the term›

endpoint https://mcp.openaso.ai/mcp · auth Authorization: Bearer <key> · get a key