For agents: the documentation index is llms.txt. Append .md to a page URL for Markdown.

// DOCS

AppHitlist MCP tools

Purpose, parameters and an example call for each tool on the AppHitlist MCP server.

AppHitlist registers these 9 MCP tools on POST /api/mcp. Each example is a JSON-RPC tools/call. Send the API key as a bearer token. Leave a parameter out to use its default. An argument that fails the schema comes back as the text "Internal error. Try again later." A JSON object with an error field is a named error, not a list of apps. The arguments below are values the input schema accepts. They are not sample results.

  • MCP server — Server URL, call limits and client setup.
  • API key — Create the bearer token these calls send.

find_chart_movers

Daily App Store chart movement: apps that climbed the most places and apps that entered the list since an earlier day. Pick the country (36 App Store countries), the list (grossing, free or paid), an optional category (for example fitness or Finance) and an optional date; days=1 compares with the day before, days=7 with a week earlier. Each riser shows its previous rank, new rank and change; each new entry shows its rank. Free keys get revenue and downloads as ranges (revenueRange, downloadsRange); subscribers get each app's monthly revenue and downloads as one figure instead (latestRevenueUsd, latestDownloads).

An unknown category returns error "category_not_found" and a categories array of the names to try again. A list that is not collected returns error "chart_not_available" with country, chart, category, date, latestChartDate and this hint: Daily lists cover 36 App Store countries. Overall lists exist for every kind in every country. Category lists: us, gb and de have grossing, free and paid; fr, ca, au, jp, kr, br, tr, es, it, mx, tw, nl, se, ch and sg have grossing and free; the other countries have grossing only. Raw daily lists are kept for 35 to 60 days. When there is no earlier chart, the warning is: No earlier chart to compare with yet, so there are no risers or new entries. Outside us, gb, de, the warning is: Only apps already in AppHitlist's catalog are recorded for this country, so an app that was added to the catalog recently can show up as a new entry.

Parameters

  • country — Optional. One of us, gb, de, fr, ca, au, jp, kr, br, tr, es, it, mx, tw, nl, se, ch, sg, hk, ae, sa, no, dk, pl, ru, in, id, th, nz, ie, at, be, za, il, cl, co. Default "us". Two-letter App Store country code, for example us, gb, de, jp, tr or br
  • chart — Optional. One of grossing, free, paid. Default "grossing". Which daily list: grossing (top grossing, by revenue), free (top free) or paid (top paid)
  • category — Optional. String, 1 to 60 characters. Optional category list, for example fitness or Finance. Leave it out for the overall list across all categories.
  • date — Optional. String matching ^\d{4}-\d{2}-\d{2}$. Chart day as YYYY-MM-DD (UTC). Leave it out for the latest day.
  • days — Optional. Integer from 1 to 28. Default 1. Compare with the newest chart at least this many days earlier: 1 for day over day, 7 for week over week
  • limit — Optional. Integer from 1 to 50. Default 20. Maximum risers and, separately, new entries to return

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_chart_movers",
    "arguments": {
      "country": "us",
      "chart": "grossing",
      "category": "Finance",
      "days": 7
    }
  }
}

find_longest_running_ads

List active Meta (Facebook and Instagram) ads that have been running the longest, in one category (for example Food & Drink) or across all categories. Long-running ads usually mean the ad pays for itself. Subscriber only.

A key that is not a subscriber returns error "subscription_required" and upgradeUrl, the AppHitlist origin plus /#pricing. An unknown category returns error "category_not_found" and a categories array of the names to try again.

Parameters

  • category — Optional. String, 1 to 60 characters. App Store category: a name such as "Health & Fitness", "Finance" or "Food & Drink", a short name such as "fitness" or "puzzle games", or a numeric genre id. Valid names: Business, Weather, Utilities, Travel, Sports, Social Networking, Reference, Productivity, Photo & Video, News, Navigation, Music, Lifestyle, Health & Fitness, Games, Finance, Entertainment, Education, Books, Medical, Magazines & Newspapers, Food & Drink, Shopping, Developer Tools, Graphics & Design, Action, Adventure, Casual, Board, Card, Casino, Family, Puzzle, Racing, Role Playing, Simulation, Strategy, Trivia, Word.
  • limit — Optional. Integer from 1 to 20. Default 10

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_longest_running_ads",
    "arguments": {
      "category": "Food & Drink"
    }
  }
}

find_new_winning_apps

List App Store apps released in the last 6 months that already earn $10K or more per month, highest first. Pass a category (for example fitness or Finance) to stay inside one category. Free keys get revenue and downloads as ranges (revenueRange, downloadsRange); subscribers get each app's monthly revenue and downloads as one figure instead (latestRevenueUsd, latestDownloads).

An unknown category returns error "category_not_found" and a categories array of the names to try again.

Parameters

  • category — Optional. String, 1 to 60 characters. App Store category: a name such as "Health & Fitness", "Finance" or "Food & Drink", a short name such as "fitness" or "puzzle games", or a numeric genre id. Valid names: Business, Weather, Utilities, Travel, Sports, Social Networking, Reference, Productivity, Photo & Video, News, Navigation, Music, Lifestyle, Health & Fitness, Games, Finance, Entertainment, Education, Books, Medical, Magazines & Newspapers, Food & Drink, Shopping, Developer Tools, Graphics & Design, Action, Adventure, Casual, Board, Card, Casino, Family, Puzzle, Racing, Role Playing, Simulation, Strategy, Trivia, Word.
  • limit — Optional. Integer from 1 to 50. Default 20

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_new_winning_apps",
    "arguments": {
      "category": "Finance"
    }
  }
}

find_top_earning_apps

List the highest-earning App Store apps by monthly revenue, in one category (for example fitness or Finance) or across all categories. Use this for questions like 'what earns the most in Health & Fitness'. Free keys get revenue and downloads as ranges (revenueRange, downloadsRange); subscribers get each app's monthly revenue and downloads as one figure instead (latestRevenueUsd, latestDownloads), plus price and ratings.

An unknown category returns error "category_not_found" and a categories array of the names to try again.

Parameters

  • category — Optional. String, 1 to 60 characters. App Store category: a name such as "Health & Fitness", "Finance" or "Food & Drink", a short name such as "fitness" or "puzzle games", or a numeric genre id. Valid names: Business, Weather, Utilities, Travel, Sports, Social Networking, Reference, Productivity, Photo & Video, News, Navigation, Music, Lifestyle, Health & Fitness, Games, Finance, Entertainment, Education, Books, Medical, Magazines & Newspapers, Food & Drink, Shopping, Developer Tools, Graphics & Design, Action, Adventure, Casual, Board, Card, Casino, Family, Puzzle, Racing, Role Playing, Simulation, Strategy, Trivia, Word.
  • limit — Optional. Integer from 1 to 50. Default 20

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_top_earning_apps",
    "arguments": {
      "category": "fitness"
    }
  }
}

get_app

Get one app by App Store URL, numeric id or name. Free keys get revenue and downloads as ranges (revenueRange, downloadsRange); subscribers get one monthly figure instead (latestRevenueUsd, latestDownloads), plus price, ratings and a 30-day chart rank summary.

An unknown app returns error "app_not_found". The app value in the example is the shape from this tool's input schema, not a live App Store id.

Parameters

  • app — Required. String, 1 to 200 characters. App Store URL (https://apps.apple.com/.../id123456789), numeric App Store id, or app name

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_app",
    "arguments": {
      "app": "https://apps.apple.com/.../id123456789"
    }
  }
}

get_app_ads

Active Meta (Facebook and Instagram) ads for the app, longest running first. Subscriber only.

A key that is not a subscriber returns error "subscription_required" and upgradeUrl, the AppHitlist origin plus /#pricing. An unknown app returns error "app_not_found". The app value in the example is the shape from this tool's input schema, not a live App Store id.

Parameters

  • app — Required. String, 1 to 200 characters. App Store URL (https://apps.apple.com/.../id123456789), numeric App Store id, or app name
  • limit — Optional. Integer from 1 to 20. Default 10

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_app_ads",
    "arguments": {
      "app": "https://apps.apple.com/.../id123456789"
    }
  }
}

get_app_complaints

Top complaint themes from the app's 1 and 2 star reviews. Subscriber only.

A key that is not a subscriber returns error "subscription_required" and upgradeUrl, the AppHitlist origin plus /#pricing. An unknown app returns error "app_not_found". The app value in the example is the shape from this tool's input schema, not a live App Store id.

Parameters

  • app — Required. String, 1 to 200 characters. App Store URL (https://apps.apple.com/.../id123456789), numeric App Store id, or app name

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_app_complaints",
    "arguments": {
      "app": "https://apps.apple.com/.../id123456789"
    }
  }
}

get_category_complaints

The most common complaint topics from 1 and 2 star reviews across all apps in one category (for example Finance). Each topic shows how many reviews and apps mention it, plus example apps. Optionally only product, billing or price complaints. Subscriber only.

A key that is not a subscriber returns error "subscription_required" and upgradeUrl, the AppHitlist origin plus /#pricing. An unknown category returns error "category_not_found" and a categories array of the names to try again.

Parameters

  • category — Required. String, 1 to 60 characters. App Store category: a name such as "Health & Fitness", "Finance" or "Food & Drink", a short name such as "fitness" or "puzzle games", or a numeric genre id. Valid names: Business, Weather, Utilities, Travel, Sports, Social Networking, Reference, Productivity, Photo & Video, News, Navigation, Music, Lifestyle, Health & Fitness, Games, Finance, Entertainment, Education, Books, Medical, Magazines & Newspapers, Food & Drink, Shopping, Developer Tools, Graphics & Design, Action, Adventure, Casual, Board, Card, Casino, Family, Puzzle, Racing, Role Playing, Simulation, Strategy, Trivia, Word.
  • kind — Optional. One of product, billing, price. Only complaints about the product itself, about billing, or about price
  • limit — Optional. Integer from 1 to 30. Default 15

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_category_complaints",
    "arguments": {
      "category": "Finance",
      "kind": "product"
    }
  }
}

search_apps

Search App Store apps by app or developer name. Returns name, category, release date and revenue and downloads as ranges (revenueRange, downloadsRange); subscribers get one monthly figure instead (latestRevenueUsd, latestDownloads), plus price and ratings.

Parameters

  • query — Required. String, 2 to 80 characters. App or developer name
  • limit — Optional. Integer from 1 to 10. Default 5

Example call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_apps",
    "arguments": {
      "query": "Finance"
    }
  }
}

// START

See the data for yourself

Start discovering winning apps.

Upgrade to Pro