Choose an access pattern
Choose the request type that matches how much data you need and whether you already know the entity IDs.
| Your goal | Use | How it works |
|---|---|---|
| Get countries, categories, or tags | Directories | Return the available collection. |
| Retrieve known apps, publishers, or SDKs | Entity lookups | Submit one id or repeated id[] parameters, up to 50 IDs. |
| Track known entities over time | Time series | Specify IDs, dates, and country where applicable. |
| Find entities by name or attributes | Search | POST a JSON query and use limit and offset to page results. |
| Iterate through a dataset | Discovery | Split the dataset into partitions and follow page tokens. |
| Ingest measurements across entities | Time series discovery | Combine partitioned discovery with a date range. |
| Download dataset snapshots | Bulk exports | Request download URLs, then fetch the file parts. |
Page through discovery results
Section titled “Page through discovery results”- Choose
total_partitionsbetween 100 and 10,000. Keep it unchanged throughout the discovery run. - Choose a
partitionbetween 1 andtotal_partitions. - Make the first request without
page_token. - If the response has
next_page_token, use its value aspage_tokenfor the next request to that same partition. - Continue until
next_page_tokenis absent.
You can process different partitions concurrently. Process pages within each partition sequentially. Page tokens belong to their partition and should not be reused across partitions.
Plan a larger ingestion
Section titled “Plan a larger ingestion”Use short date ranges to validate your request first. For history longer than 180 days, split time series discovery into smaller date windows. Follow your account’s rate limit across all concurrent workers.
For file exports, request a fresh set of URLs when you are ready to download. The documented download URL lifetime is 24 hours.