Get In-App event metadata from the App Store or Promotional Content metadata from Google Play
Using AppTweak API you can get In-App Event metadata that are appearing on a store listing page. AppTweak doesn't store data about events that are appearing elsewhere. You can refer to the following screenshot to see which In-App Event or LiveOps AppTweak gets data for.
AppTweak only collects In-App events or Promotional Content that are appearing on an app store listing page.
In-App Events List
Get a list of In-App Events or Promotional Content events for an app for a certain date-range.
Input parameters
You can pass the following query parameters: apps, country,device, start_date, end_date. The date parameters corresponds to the dates where the events are running.
All the In-App or Promotional Content events running during that date range will be returning by the endpoint.
Response format
The response is a JSON organised by app id and events. In the following table you can find the fields and their equivalence with the terms used in the AppTweak tool for In-App Events on iOS or LiveOps on Android.
| API field | iOS | Android |
|---|---|---|
| event_id | Unique event ID (number) | Unique event ID (number) |
| event | - | Event type |
| title | Event title | Tag line |
| subtitle | Short description | - |
| description | Description (detailed view) | Description |
| artwork_url | URL of the In-App Event image | URL of the Liveops image |
| event_start_date | The start date of the event in YYYY-MM-DD | The start date of the event in YYYY-MM-DD |
| event_end_date | The end date of the event as it is set-up in the App Store in YYYY-MM-DD | End date or Estimated end date in YYYY-MM-DD |
| promotion_start_date | The date when the event will start appearing on the App Store (which can be earlier than the start date of the event) | - |
| event_start_time | UTC time in hh:mm:ss | UTC time in hh:mm:ss |
| event_end_time | UTC time in hh:mm:ss | UTC time in hh:mm:ss |
| promotion_start_time | UTC time in hh:mm:ss | - |
| requirement | If anything is required in order to access the event - e.g a subscription | - |
| video_link | - | URL of the Video shown in the detailed view (once you've clicked on the event card). The video is optional when creating a Promotional Content |
Below you'll find a response example for an In-App Event on iOS in the US for the app HBO Max.
{
"result": {
"971265422": {
"events": [
{
"event_id": 6443959390, // Event id
"last_seen": "2022-12-07 02:00:58 +0000", // Last time AppTweak saw the event
"title": "Shaq", // Event title
"subtitle": "Stream this new HBO Original on HBO Max.", // Short description
"description": "The story of a basketball legend unlike any other, whose larger-than-life personality transcended the sport.", // Description (detailed view)
"artwork_url": "https://is5-ssl.mzstatic.com/image/thumb/kJTf9S8iEfFC6VN_IcXANQ/3840x2160bb.jpg", // Image url
"event_start_date": "2022-11-24", // Sart date
"event_end_date": "2022-12-07", // End date
"promotion_start_date": "2022-11-22", // Promotion Start Data
"event_start_time": "02:00:00", // UTC time
"event_end_time": "05:00:00", // UTC time
"promotion_start_time": "05:00:00", // UTC time
"requirement": null // No requirements
}
]
}
},
"metadata": {
"request": {
"path": "/api/public/store/apps/events",
"params": {
"device": "iphone",
"country": "us",
"language": "us",
"start_date": "2022-11-24",
"end_date": "2022-11-25",
"apps": [
"971265422"
]
},
"cost": 34,
"max_credit_cost": 34,
"status": 200
},
"response": null
}
}In-App Events Metadata
Get the In-App Event metadata for a given event id. This is especially helpful for the API endpoint App Store Connect by In-App Event where reporting analytics is provided for a given event id.
Input parameters
You can pass the following query parameters: event_ids, country,device, language.
Response format
The JSON is organised by event ids. Below you can find an example for the event id 6479404829 which was running for the app "adidas Running: Walk & Run App" in the US on iOS.
{
"result": {
"6479404829": // event_id
{
"last_seen": "2024-04-18T11:09:09.120+00:00", // Last time AppTweak saw the event
"title": "Join the Road to Records 5k", // Event title
"subtitle": "Start your running journey with a 5K virtual race",
"description": "Your first race or your fastest - April 27 is the day to break your own record.",
"artwork_url": "https://is1-ssl.mzstatic.com/image/thumb/mTP_tGrRoPctKgx52PVXwQ/1920x1080bb.jpg",
"event_start_date": "2024-03-26T23:00:00.000+00:00",
"event_end_date": "2024-04-26T22:00:00.000+00:00",
"promotion_start_date": "2024-03-26T23:00:00.000+00:00", // Only for iOS, date when the event appears in the store
"event_start_time": null,
"event_end_time": null,
"promotion_start_time": null,
"requirement": null
}
},
"metadata": {
"request": {
"path": "/api/public/store/in_app_events/metadata",
"params": {
"device": "iphone",
"country": "us",
"language": "us",
"event_ids": [
"6479404829"
]
},
"cost": 11,
"max_credit_cost": 11,
"status": 200
},
"response": null
}
}FAQs
How do I fetch the app store promotional events currently running for an app?
You can pull all in-app events or promotional content running for an app in a date range with AppTweak's App Store API, specifically the In-App Events List endpoint (GET /apps/events). Pass up to 5 app IDs in apps, the device (iphone or android), and a start_date/end_date window — the dates the events themselves are running, not when you're querying. The response returns every event live during that window, grouped by app ID, with each event's title, description, artwork, and start/end dates.
Can I track what in-app events or promotions a competitor's app is running?
Yes — you can query a competitor's app ID through the same In-App Events List endpoint AppTweak provides for your own app. Since apps accepts up to 5 comma-separated IDs per call, you can batch several competitors into one request rather than calling per app. Each result includes the event's title, subtitle, description, and artwork_url, enough to see what a competitor is promoting on their store listing (a tournament, a live stream, seasonal content) without opening the store manually.
What's the difference between the In-App Events List and Metadata endpoints?
List and Metadata answer different questions: List finds which events an app ran in a date range, while Metadata looks up the full details of specific events you already have IDs for. AppTweak's In-App Events List endpoint (GET /apps/events) takes apps and a date range and returns matching events per app. The In-App Events Metadata endpoint (GET /in_app_events/metadata) takes a comma-separated list of event_ids directly and returns their details — useful when you already have an event_id from another call, such as the App Store Connect by In-App Event report.
What's the difference between event_start_date and promotion_start_date?
event_start_date is when the event itself begins — the tournament, live stream, or content it advertises — while promotion_start_date is when that promotion first appears on the store listing page, which can be earlier. Both fields are returned by AppTweak's In-App Events List and Metadata endpoints, in YYYY-MM-DD format (Metadata returns full timestamps). promotion_start_date is iOS-only; Android's response has no equivalent field, since Google Play doesn't expose a separate promotion-visibility date for LiveOps content.
Does the in-app events data cover both iOS and Android?
Yes — AppTweak's In-App Events List and Metadata endpoints cover both iOS ("In-App Events") and Android ("LiveOps"), selected with the device parameter (iphone or android). Field coverage differs slightly by platform: iOS returns subtitle, requirement, and promotion_start_date/promotion_start_time, none of which Android provides; Android instead returns an event type field and an optional video_link, which iOS doesn't have. Only events appearing on the store listing page are captured — events shown elsewhere in the app aren't in scope for either platform.