API Reference
My API token 🔑

Build with AppTweak data

If your goal is a dashboard, a script, or an internal tool, the most effective way to use the MCP is as a map, not a pipe: let the agent read the documentation and write the code, then run that code yourself against the API.

Why not just let the agent fetch everything?

You can, and for a quick question you should. But for anything you'll run more than once, generating code beats streaming data through the model:

  • The agent's context is small; your disk isn't. A year of daily metrics for fifty apps won't fit in a conversation. It fits in a CSV without complaint.
  • Models do judgment well and arithmetic badly. Summing 500 numbers is what a script is for. Deciding which 500 numbers matter is what the model is for.
  • You pay agent tokens once per turn, forever. Data that enters a conversation is re-read on every subsequent turn. Data in a file is read when your code reads it.
  • Discovery is free. Documentation tools cost no credits and need no API key. The agent can design the whole integration before you spend anything.
  • Your data can stay out of the model. If the generated script pulls the data, the raw rows never reach an LLM. That matters if you have an opinion about what leaves your infrastructure.

The shape of the workflow:

  1. Ask the agent for what you want, in plain language.
  2. It calls start-here-guide, then search-endpoints and get-endpoint to find the right calls and their exact parameters. Zero credits so far.
  3. It optionally runs one execute-request with a tiny limit, to confirm the response shape against a real payload.
  4. It writes you a script — Python, TypeScript, whatever you asked for — that calls the API directly with your key.
  5. You run the script. From here on, the cost is plain API cost with no agent in the loop.

Worked example 1 — Keyword rank and installs, last 30 days

Prompt

Using the AppTweak MCP: I track five keywords for my iOS app in the US. Build me a Python script that pulls daily keyword rank and daily installs-per-keyword for the last 30 days and writes one CSV, one row per keyword per day. Read the endpoint docs first and tell me what the call will cost in credits before you run anything.

What the agent should land on

GET /apps/keywords-rankings/history.json on apptweak-store-api, for rank, and the keyword-metrics history endpoint for installs. One important constraint it will find in the docs: the rankings endpoint accepts a maximum of five keywords per call, so more than five keywords means batching.

What it costs

Historical endpoints charge the datapoint's base price for the first available day and 10% of it for each additional day. Keyword rank and installs are both 10 credits base, 1 per extra day:

per keyword, per datapoint:  10 + (29 × 1)          =  39
5 keywords × 2 datapoints × 39                      = 390
+ 1 credit for the request itself                   = 391 credits

Run that script daily for a month and you're at roughly 11,700 credits. Worth knowing before you schedule it.

The lever. One historical call over a 30-day range costs 39 credits per series. Thirty separate "current" calls cost 10 credits each — 300. Always ask for a range, never loop over days.

Worked example 2 — Top keywords by installs, grouped branded / generic / competitor

Prompt

Using the AppTweak MCP: for my Android app, get the top 20 keywords driving installs from Google Play Console over the last 90 days, and group them into branded, generic and competitor. Use whatever guide tool exists for this rather than assembling it from raw endpoints.

What the agent should land on

The gpc-keyword-installs-guide tool. This workflow needs a dedicated guide because it spans the Console Data API and the store dataset, and assembling it from raw endpoint calls is where people get it wrong. Tell the agent to use the guide; don't let it improvise.

Two things it needs to know:

  • Google Play Console data comes from apptweak-integrations-api and only exists if the Play Console account is already connected to AppTweak. A clean 200 with no data means the connection is missing, not that the app has no installs.
  • The branded / generic classification uses the is_branded keyword-metrics datapoint (10 credits per keyword, current value only).

What it costs

Console Data API calls bill differently from the store datapoint table, so don't estimate — run the first call with a small limit and read metadata.request.cost from the response. Then scale.

Worked example 3 — App Store Connect versus Apple Search Ads

Prompt

Using the AppTweak MCP: build me a dashboard comparing my App Store Connect impressions and conversion rate against my Apple Search Ads keyword bids for the same keywords, over the last 12 months. Check the endpoint docs for date-range gotchas before you write the query.

What the agent should land on

App Store Connect metrics from apptweak-integrations-api, and paid keyword bids from GET /apps/keywords/bids.json on apptweak-store-api.

The trap this example exists to teach. bids.json defaults to a 30-day window, and for most apps that window returns empty — no error, just no data. You need a 12-month range with aggregated=true. Its sibling /keywords/apps/bids.json (which apps bid on keyword X) has the same shape and very likely the same trap.

This is the general lesson for builders: the OpenAPI default values in our specs are not reliable. Several endpoints' schema defaults disagree with their own prose descriptions — the sharpest case being /apps/reviews/search.json, where the prose says the limit default is 100 and the schema says 10. Trusting the schema silently under-fetches by 10×. Always set date ranges and limits explicitly rather than omitting them, and read the prose description, not just the schema.

Practices that pay off

Give the agent the gotchas up front. Drop the list from Agent context files into your repo as AGENTS.md. It stops the agent rediscovering the same traps every session.

Ask for the cost before the call. "Tell me what this will cost in credits before running it" is a good habit and the agent can answer it from the pricing docs without spending anything.

Smoke-test with limit=1. One real response confirms the shape and costs almost nothing. Read metadata.request.cost, then scale up deliberately.

Check country and language codes against the source. Those parameters are free text, not enums, and every store endpoint links to a static docs page rather than the live list. If a code is rejected, call the countries and languages endpoints on apptweak-api.

Write your custom skills, then reference them in future runs.
Whenever you got a workflow right, or you agent find the information it was looking for, ask it do condense this information in a skill that can be reused on future runs.

Next

Updated 1 day ago

Updated 1 day ago