# REST API

> Read Tapll's numbers from your own scripts and tools with an organization API key: sessions, people, ASO, competitors, web traffic, crashes and revenue.

Source: https://tapll.com/docs/api · Updated 2026-11-03

The REST API gives scripts the same reads the panel shows, with the same definitions: a number you fetch is the number on the screen. It is read-only. It comes with the Pro and Studio plans.

## Create a key

Open **Settings → Organization → API keys** and create a key. It starts with `tapll_api_` and is shown once; store it as a secret. A key acts with its own role and on behalf of the person who created it: if they leave the organization, the key stops working.

Don't confuse it with the SDK's keys: `av_…` (client) and `sk_…` (server) send events in; `tapll_api_…` reads results out.

## Requests

```sh
curl https://tapll.com/api/v1/projects \
  -H "Authorization: Bearer tapll_api_…"
```

`GET /api/v1/projects` lists the organization's projects. Every other read is `GET /api/v1/projects/<project>/<read>`, where `<project>` is the slug from that list:

| Read | What it answers |
|---|---|
| `live` | People in the app now, with the latest sessions and events |
| `sessions_overview` | Sessions in a window against the previous one, by day, device, OS, country and version |
| `sessions` | The newest sessions (page with `before`; filter by `version`, `install`, `person`, `flag`, `traffic`, `f`) |
| `sessions/<sessionId>` | One session's timeline with purchases and subscription state |
| `people` | People using the app, grouped across devices |
| `people/<installId>/activity` | One install's activity |
| `screens` | Screens by views, time and exits |
| `retention` | Day-N return rates of install cohorts |
| `crashes` | Crash issues and the crash-free rate |
| `crashes/issues/<fingerprint>` | One crash issue in depth |
| `revenue` | Revenue and subscription movement per source |
| `revenue/mrr` | Recurring revenue movement |
| `revenue/transactions` | Newest transactions (`limit`, `source`) |
| `revenue/upcoming` | Upcoming renewals (`days` 7 or 30) |
| `revenue/examples` | Paid sessions behind the totals |
| `releases` | App versions with adoption and stability |
| `releases/<version>` | One version in depth |
| `features` | Features with their discovery → adoption → success funnel |
| `features/<id>` | One feature in depth |
| `data` | The event catalogue with counts |
| `data/events/<name>` | One event in depth |
| `search` | Palette search (`q` required) |
| `keywords` | Tracked ASO phrases in a storefront (`country`) |
| `keywords/<phraseId>` | One phrase: rank series, rivals, difficulty |
| `keywords/discover` | Long-tail candidates not tracked yet |
| `keywords/lookup` | Live look at one term (`term` required, writes nothing) |
| `keywords/changes` | Listing changes with search impact |
| `keywords/impact` | How search contributes sessions |
| `competitors` | Watched competitors in a storefront |
| `competitors/<appId>` | One competitor in depth |
| `competitors/updates` | Rival release feed |
| `competitors/feed` | Observed change stream (window, `kind`, `app`, `cursor`) |
| `competitors/<appId>/keywords` | Phrases where an app appears in observed results |
| `competitors/compare` | Own app vs watched apps in one storefront and window |
| `competitors/rankings` | Category chart observations, paged |
| `web/overview` | Website traffic in a window |
| `web/examples` | Newest website visits |
| `web/goals`, `web/goals/options` | Goals and what a goal can count |
| `store` | App Store performance in a storefront |
| `store/markets` | Per-storefront markets |
| `store/reviews` | Own reviews, filtered and paged |
| `store/referrers` | Where product page views came from |
| `store/products` | ASC product catalog snapshot (`product`, `page`) |
| `store/funnel` | Apple Search funnel with coverage |
| `keywords/export` | Daily phrase observations, JSON or CSV |

Query parameters, where the read takes them: `env` (`production` or `sandbox`), `days` (allowed values depend on the read: `1`, `7`, `28`, `30`, `90`, `180` or `365`), `platform` (`ios`, `android` or `web`), `before`, `f` (repeatable `dim:value` filters), `limit`, `country` (2-letter storefront), `term`/`q`, `channel`, `referrer`, `paid`, `period`, plus the id in the path (`sessionId`, `phraseId`, `appId`, …).

A `null` value means "not counted" (no data reached that day or window), never zero. The full description is at [`/api/v1/openapi.json`](/api/v1/openapi.json) (OpenAPI 3.1). Limits: 300 requests a minute per key.


## ASO and monetization reads

The public read route uses read names: `/api/v1/projects/<slug>/<read>`. New reads are `store_products`, `store_funnel`, `keywords_export`, `competitor_keywords`, `competitor_compare` and `competitor_rankings`, plus `competitor_feed` (the observed-change stream with a window and cursor).

For ASO reads use `country` (two-letter storefront), inclusive `from`/`to` calendar dates, and pagination. Export defaults to 28 days and allows at most 180 days. `keywords_export?format=csv` returns `text/csv` with `X-Next-Page`; JSON returns `nextPage`. Never interpret a missing observation as rank zero. Comparison accepts comma-separated `appIds` (two to six distinct own/watched apps).

Catalog snapshots distinguish unavailable, completed empty, fresh and stale data. Country filtering applies to price/offer details, while products remain listed. Funnel conversions include their effective reporting coverage; separate sources do not imply matched people.

Revenue reads accept `period`, repeatable `f=product:<id>` and `f=country:US` where supported. Responses identify sections that cannot apply a filter and keep provider/currency semantics. Churn and retention require evidence for their cohort and denominator.