### Installs (eo_install) Source: https://help.branch.io/apidocs/query-api-recipes This example demonstrates how to query for install events. It includes dimensions for user platform and desktop origin, and filters. ```APIDOC ## POST /v1/query/analytics ### Description Queries for install event analytics data. ### Method POST ### Endpoint http://api.branch.io/v1/query/analytics?limit=100 ### Request Body - **branch_key** (string) - Required - Your Branch API key. - **branch_secret** (string) - Required - Your Branch API secret. - **start_date** (string) - Required - The start date for the query (ISO 8601 format). - **end_date** (string) - Required - The end date for the query (ISO 8601 format). - **data_source** (string) - Required - The data source identifier, e.g., "eo_install". - **granularity** (string) - Optional - The granularity of the data (e.g., "all", "daily"). - **dimensions** (array) - Optional - An array of dimensions to group the data by. - **filters** (object) - Optional - An object containing filters to apply to the query. - **aggregation** (string) - Required - The type of aggregation to perform (e.g., "unique_count"). ### Request Example ```json { "branch_key": "", "branch_secret": "", "start_date": "2017-12-07T00:00:00-08:00", "end_date": "2017-12-13T23:59:59-08:00", "data_source": "eo_install", "granularity": "all", "dimensions": [ "user_data_platform", "from_desktop" ], "filters": { "user_data_platform": [ "IOS_APP", "ANDROID_APP" ], "!days_from_last_attributed_touch_to_event": [ null ] }, "aggregation": "unique_count" } ``` ### Response #### Success Response (200) - **results** (array) - An array of result objects, each containing a timestamp and the aggregated data. - **timestamp** (string) - The timestamp for the data point. - **result** (object) - The aggregated data for the given dimensions and filters. - **user_data_platform** (string) - The user data platform. - **from_desktop** (string) - Indicates if the traffic was from desktop. - **unique_count** (integer) - The unique count for the aggregation. - **paging** (object) - Pagination information. - **total_count** (integer) - The total number of results. #### Response Example ```json { "results": [ { "timestamp": "2017-12-07T08:00:00.000Z", "result": { "user_data_platform": "ANDROID_APP", "from_desktop": "false", "unique_count": 657 } }, { "timestamp": "2017-12-07T08:00:00.000Z", "result": { "user_data_platform": "IOS_APP", "from_desktop": "false", "unique_count": 473 } }, { "timestamp": "2017-12-07T08:00:00.000Z", "result": { "user_data_platform": "ANDROID_APP", "from_desktop": "true", "unique_count": 49 } }, { "timestamp": "2017-12-07T08:00:00.000Z", "result": { "user_data_platform": "IOS_APP", "from_desktop": "true", "unique_count": 46 } } ], "paging": { "total_count": 4 } } ``` ``` -------------------------------- ### Total Installs Query (cURL) Source: https://help.branch.io/apidocs/query-api Example of a cURL request to get the total number of installs per day, split by attribution. The results are limited to 5. ```json curl -X POST -H "Content-Type: application/json" -d '{ "branch_key":"", "branch_secret":"", "start_date": "2022-03-01", "end_date": "2022-03-07", "data_source": "eo_install", "dimensions": [ "attributed" ], "enable_install_recalculation": true, "granularity": "day", "aggregation": "total_count" }' "https://api2.branch.io/v1/query/analytics?limit=5" ``` -------------------------------- ### Total Installs Query Source: https://help.branch.io/apidocs/query-api This example demonstrates how to query the total number of installs per day, split by attribution, and limited to 5 results. ```APIDOC ## POST /v1/query/analytics ### Description Retrieves analytics data based on specified parameters, such as total installs. ### Method POST ### Endpoint https://api2.branch.io/v1/query/analytics?limit=5 ### Request Body - **branch_key** (string) - Required - Your Branch API key. - **branch_secret** (string) - Required - Your Branch API secret. - **start_date** (string) - Required - The start date for the query (YYYY-MM-DD). - **end_date** (string) - Required - The end date for the query (YYYY-MM-DD). - **data_source** (string) - Required - The data source to query (e.g., "eo_install"). - **dimensions** (array of strings) - Optional - Dimensions to split the data by (e.g., ["attributed"]). - **enable_install_recalculation** (boolean) - Optional - Whether to enable install recalculation. - **granularity** (string) - Optional - The granularity of the data (e.g., "day"). - **aggregation** (string) - Optional - The aggregation method (e.g., "total_count"). ### Request Example ```json { "branch_key":"", "branch_secret":"", "start_date": "2022-03-01", "end_date": "2022-03-07", "data_source": "eo_install", "dimensions": [ "attributed" ], "enable_install_recalculation": true, "granularity": "day", "aggregation": "total_count" } ``` ### Response #### Success Response (200) - **results** (List of Objects) - A list of JSON objects containing result information. - **result** (Object) - A JSON object containing the queried values (e.g., `attributed` or `total_count`). - **timestamp** (Date) - The date and time when the data related to the `result` was created. - **paging** (Object) - A JSON object that includes the total number of results from the query (`total_count`) and pagination information (`next_url`). #### Response Example ```json { "results": [{ "result": { "attributed": "false", "total_count": 44 }, "timestamp": "2022-03-05T00:00:00.000Z" }, { "result": { "attributed": "false", "total_count": 23 }, "timestamp": "2022-03-07T00:00:00.000Z" }, { "result": { "attributed": "true", "total_count": 14 }, "timestamp": "2022-03-05T00:00:00.000Z" }, { "result": { "attributed": "false", "total_count": 12 }, "timestamp": "2022-03-03T00:00:00.000Z" }, { "result": { "attributed": "false", "total_count": 10 }, "timestamp": "2022-03-02T00:00:00.000Z" }], "paging": { "next_url": "/v1/query/analytics?limit=5&after=5", "total_count": 13 } } ``` ``` -------------------------------- ### Response for Daily Installs by Ad Partner Source: https://help.branch.io/apidocs/query-api-recipes Example response showing daily install counts per ad partner. ```json { "results": [ { "result": { "last_attributed_touch_data_tilde_advertising_partner_name": "Taptica", "unique_count": 40 }, "timestamp": "2017-12-05T08:00:00.000Z" }, { "result": { "last_attributed_touch_data_tilde_advertising_partner_name": "Taptica", "unique_count": 37 }, "timestamp": "2017-12-01T08:00:00.000Z" }, ... ], "paging": { "total_count": 20 } } ``` -------------------------------- ### Total Installs Response (JSON) Source: https://help.branch.io/apidocs/query-api Example JSON response for a query requesting total installs per day, split by attribution, with results limited to 5. ```json { "results": [{ "result": { "attributed": "false", "total_count": 44 }, "timestamp": "2022-03-05T00:00:00.000Z" }, { "result": { "attributed": "false", "total_count": 23 }, "timestamp": "2022-03-07T00:00:00.000Z" }, { "result": { "attributed": "true", "total_count": 14 }, "timestamp": "2022-03-05T00:00:00.000Z" }, { "result": { "attributed": "false", "total_count": 12 }, "timestamp": "2022-03-03T00:00:00.000Z" }, { "result": { "attributed": "false", "total_count": 10 }, "timestamp": "2022-03-02T00:00:00.000Z" }], "paging": { "next_url": "/v1/query/analytics?limit=5&after=5", "total_count": 13 } } ``` -------------------------------- ### Enable Install Recalculation Example Source: https://help.branch.io/apidocs/postquery Set this boolean field to true to de-duplicate unattributed installs caused by duplicate events from non-opt-in users coming from paid ads. Defaults to false. ```json { "enable_install_recalculation": true } ``` -------------------------------- ### Installs Query Response Source: https://help.branch.io/apidocs/query-api-recipes This is a sample response for an installs query. It shows the unique count of installs per user data platform. ```json { "results": [ { "result": { "user_data_platform": "ANDROID_APP", "unique_count": 435 }, "timestamp": "2017-12-07T08:00:00.000Z" }, { "result": { "user_data_platform": "IOS_APP", "unique_count": 393 }, "timestamp": "2017-12-07T08:00:00.000Z" } ], "paging": { "total_count": 2 } } ``` -------------------------------- ### Compare Facebook SKAdNetwork and Non-SKAdNetwork Installs Source: https://help.branch.io/apidocs/unified-analytics-export This example shows how to compare SKAdNetwork (`skan_count`) and non-SKAdNetwork (`non_skan_unique_count`) install counts specifically for Facebook, using the `skan_unified_view` data source. ```APIDOC ## POST /v1/branch_aggregate/async/analytics ### Description Exports aggregated analytics data, comparing SKAdNetwork and non-SKAdNetwork metrics for specific dimensions like advertising partners and event names. This is useful for understanding the performance breakdown across different attribution methods. ### Method POST ### Endpoint `https://api2.branch.io/v1/branch_aggregate/async/analytics?app_id={app_id}` ### Parameters #### Query Parameters - **app_id** (string) - Required - Your Branch App ID. #### Request Body - **filter** (object) - Required - Defines the criteria for filtering the data. This example uses an `and` filter to combine conditions for advertising partner and event name. - **type** (string) - Required - Type of filter (`selector`, `and`, `or`). - **fields** (array) - Required (if type is `and` or `or`) - An array of filter objects. - **type** (string) - Required - Type of filter (`selector`). - **dimension** (string) - Required - The dimension to filter on (e.g., `last_attributed_touch_data_tilde_advertising_partner_name`, `name`). - **value** (string) - Required - The value to match for the dimension (e.g., `Facebook`, `INSTALL`). - **granularity** (string) - Required - The time granularity for the aggregation (e.g., `all`, `daily`, `hourly`). - **response_format_compression** (string) - Required - The compression format for the response (e.g., `gz`). - **response_format** (string) - Required - The format of the response data (e.g., `json`). - **start_date** (string) - Required - The start date for the data export in `YYYY-MM-DD` format. - **end_date** (string) - Required - The end date for the data export in `YYYY-MM-DD` format. - **dimensions** (array) - Required - An array of strings specifying the dimensions to include in the results (e.g., `name`, `last_attributed_touch_data_tilde_advertising_partner_name`). - **aggregations** (array) - Required - An array of objects, where each object defines an aggregation to perform. - **field_name** (string) - Required - The field to aggregate (e.g., `skan_count`, `non_skan_unique_count`). - **data_source** (string) - Required - The data source to use for the aggregation (e.g., `skan_unified_view`). - **display_name** (string) - Required - A custom name for the aggregated field in the response. ### Request Example ```json { "filter": { "type": "and", "fields": [ {"type":"selector","dimension":"last_attributed_touch_data_tilde_advertising_partner_name","value":"Facebook"}, {"type":"selector","dimension":"name","value":"INSTALL"} ] }, "granularity": "all", "response_format_compression": "gz", "response_format": "json", "start_date": "2024-04-28", "end_date": "2024-05-05", "dimensions": [ "name", "last_attributed_touch_data_tilde_advertising_partner_name" ], "aggregations": [ { "field_name": "skan_count", "data_source": "skan_unified_view", "display_name": "SKAN_Count" }, { "field_name": "non_skan_unique_count", "data_source": "skan_unified_view", "display_name": "Non_SKAN_Count" } ] } ``` ### Response #### Success Response (200) - **name** (string) - The name of the event (e.g., 'INSTALL'). - **last_attributed_touch_data_tilde_advertising_partner_name** (string) - The name of the advertising partner. - **SKAN_Count** (number) - The count of installs attributed via SKAdNetwork. - **Non_SKAN_Count** (number) - The count of installs not attributed via SKAdNetwork. #### Response Example ```json { "name": "INSTALL", "last_attributed_touch_data_tilde_advertising_partner_name": "Facebook", "Non_SKAN_Count": 706086, "SKAN_Count": 29 } ``` ``` -------------------------------- ### Get Export Download Status API Example Source: https://help.branch.io/apidocs/getexportdownloadstatus-2 This example shows how to query the status of an export job using its unique job ID. Ensure you have the necessary API key for authentication. ```bash curl -X GET \"https://api2.branch.io/v2/analytics/{job_id}\" \ -H \"Access-Token: \" ``` -------------------------------- ### Query API: Get Web Session Starts (eo_web_session_start) Source: https://help.branch.io/apidocs/query-api-recipes Retrieve the count of web session starts attributed to advertising partners. This query is useful for understanding web-to-app attribution. ```bash curl -X POST -H "Content-Type: application/json" -d '{ "branch_key": "", "branch_secret": "", "start_date": "2017-12-07T00:00:00-08:00", "end_date": "2017-12-13T23:59:59-08:00", "data_source": "eo_web_session_start", "granularity": "all", "dimensions": [ "last_attributed_touch_data_tilde_advertising_partner_name" ], "filters": { "last_attributed_touch_data_tilde_feature": [ "paid advertising" ], "!user_data_platform": [ "ROBOT" ], "!days_from_last_attributed_touch_to_event": [ null ] }, "aggregation": "unique_count" }' "http://api.branch.io/v1/query/analytics?limit=100" ``` -------------------------------- ### Installs (eo_install) Source: https://help.branch.io/apidocs/query-api-recipes This request retrieves install data attributed to campaigns. It aggregates unique installs and filters by platform and days from last attributed touch. ```APIDOC ## POST /v1/query/analytics ### Description Retrieves unique install counts attributed to campaigns, with options for platform and days from last attributed touch filtering. ### Method POST ### Endpoint http://api.branch.io/v1/query/analytics?limit=100 ### Parameters #### Request Body - **branch_key** (string) - Required - Your Branch API key. - **branch_secret** (string) - Required - Your Branch API secret. - **start_date** (string) - Required - The start of the date range for the query (ISO 8601 format). - **end_date** (string) - Required - The end of the date range for the query (ISO 8601 format). - **data_source** (string) - Required - Specifies the data source, 'eo_install' for installs. - **granularity** (string) - Required - The time granularity for the results ('all' for no aggregation). - **dimensions** (array) - Required - An array of dimensions to group the data by, e.g., ['last_attributed_touch_data_tilde_campaign']. - **filters** (object) - Optional - An object containing filters to apply to the query. - **user_data_platform** (array) - Optional - Filters by user data platform (e.g., ['IOS_APP', 'ANDROID_APP']). - **!days_from_last_attributed_touch_to_event** (array) - Optional - Filters by days from last attributed touch to event (e.g., [null] to include all). - **aggregation** (string) - Required - The type of aggregation to perform, 'unique_count' for unique users. ### Request Example ```json { "branch_key": "", "branch_secret": "", "start_date": "2025-08-01T00:00:00-08:00", "end_date": "2025-08-07T23:59:59-08:00", "data_source": "eo_install", "granularity": "all", "dimensions": [ "last_attributed_touch_data_tilde_campaign" ], "filters": { "user_data_platform": [ "IOS_APP", "ANDROID_APP" ], "!days_from_last_attributed_touch_to_event": [ null ] }, "aggregation": "unique_count" } ``` ### Response #### Success Response (200) - **results** (array) - An array of result objects. - **result** (object) - Contains the aggregated data. - **last_attributed_touch_data_tilde_campaign** (string) - The campaign name. - **unique_count** (integer) - The count of unique installs. - **timestamp** (string) - The timestamp for the result. - **paging** (object) - Contains pagination information. - **total_count** (integer) - The total number of items matching the query. #### Response Example ```json { "results": [ { "result": { "last_attributed_touch_data_tilde_campaign": "", "unique_count": 425 }, "timestamp": "2025-08-01T08:00:00.000Z" }, { "result": { "last_attributed_touch_data_tilde_campaign": "", "unique_count": 328 }, "timestamp": "2025-08-01T08:00:00.000Z" } ], "paging": { "total_count": 58 } } ``` ``` -------------------------------- ### IDFA Example for tvOS Source: https://help.branch.io/apidocs/desktop-over-the-top-ott-attribution This example shows how to include the IDFA (Identifier for Advertisers) for tvOS devices in the advertising_ids parameter. ```json "advertising_ids": { "idfa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274" } ``` -------------------------------- ### LG IFA Example Source: https://help.branch.io/apidocs/desktop-over-the-top-ott-attribution This example shows how to include the LG Identifier for Advertising (IFA) for LG webOS devices. ```json "advertising_ids": { "lg_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274" } ``` -------------------------------- ### Installs (eo_install) Source: https://help.branch.io/apidocs/query-api-recipes This request retrieves install event data, aggregated by advertising partner, for paid advertising features, excluding robot traffic and installs that occurred on the same day as the last attributed touch. ```APIDOC ## POST /v1/query/analytics ### Description Retrieves install event data aggregated by advertising partner. ### Method POST ### Endpoint http://api.branch.io/v1/query/analytics?limit=100 ### Parameters #### Request Body - **branch_key** (string) - Required - Your Branch API key. - **branch_secret** (string) - Required - Your Branch API secret. - **start_date** (string) - Required - The start date for the query (ISO 8601 format). - **end_date** (string) - Required - The end date for the query (ISO 8601 format). - **data_source** (string) - Required - The data source to query, e.g., "eo_install". - **granularity** (string) - Required - The granularity of the data, e.g., "all". - **dimensions** (array) - Required - An array of dimensions to group the data by, e.g., ["last_attributed_touch_data_tilde_advertising_partner_name"]. - **filters** (object) - Optional - An object containing filters to apply to the query. - **last_attributed_touch_data_tilde_feature** (array) - Optional - Filters by feature, e.g., ["paid advertising"]. - **!user_data_platform** (array) - Optional - Excludes specific platforms, e.g., ["ROBOT"]. - **!days_from_last_attributed_touch_to_event** (array) - Optional - Excludes events based on days from last attributed touch, e.g., [null]. - **aggregation** (string) - Required - The aggregation method, e.g., "unique_count". ### Request Example ```json { "branch_key": "", "branch_secret": "", "start_date": "2017-12-07T00:00:00-08:00", "end_date": "2017-12-13T23:59:59-08:00", "data_source": "eo_install", "granularity": "all", "dimensions": [ "last_attributed_touch_data_tilde_advertising_partner_name" ], "filters": { "last_attributed_touch_data_tilde_feature": [ "paid advertising" ], "!user_data_platform": [ "ROBOT" ], "!days_from_last_attributed_touch_to_event": [ null ] }, "aggregation": "unique_count" } ``` ### Response #### Success Response (200) - **results** (array) - An array of result objects, each containing a result and a timestamp. - **result** (object) - Contains the aggregated data. - **last_attributed_touch_data_tilde_advertising_partner_name** (string) - The name of the advertising partner. - **unique_count** (integer) - The unique count for the specified aggregation. - **timestamp** (string) - The timestamp for the data point. - **paging** (object) - Contains pagination information. - **total_count** (integer) - The total number of results. #### Response Example ```json { "results": [ { "result": { "last_attributed_touch_data_tilde_advertising_partner_name": "Taptica", "unique_count": 425 }, "timestamp": "2017-12-07T08:00:00.000Z" }, { "result": { "last_attributed_touch_data_tilde_advertising_partner_name": "A4G", "unique_count": 328 }, "timestamp": "2017-12-07T08:00:00.000Z" } ], "paging": { "total_count": 4 } } ``` ``` -------------------------------- ### Installs Source: https://help.branch.io/apidocs/query-api-recipes Retrieve data for installs. This query uses the `eo_install` data source and filters by app platform and touch data. ```APIDOC ## POST /v1/query/analytics ### Description Retrieve analytics data for installs. ### Method POST ### Endpoint http://api.branch.io/v1/query/analytics?limit=100 ### Request Body - **branch_key** (string) - Required - Your Branch key. - **branch_secret** (string) - Required - Your Branch secret. - **start_date** (string) - Required - The start date for the query (ISO 8601 format). - **end_date** (string) - Required - The end date for the query (ISO 8601 format). - **data_source** (string) - Required - The data source to query, e.g., `eo_install`. - **granularity** (string) - Optional - The granularity of the data (e.g., `all`, `daily`). - **dimensions** (array) - Optional - Array of dimensions to group the data by, e.g., `["user_data_platform"]`. - **filters** (object) - Optional - Object containing filters to apply to the query. - **user_data_platform** (array) - Optional - Filter by user data platform (e.g., `["IOS_APP", "ANDROID_APP"]`). - **last_attributed_touch_data_plus_via_features** (array) - Optional - Filter by touch data (e.g., `["MOBILE_DEEPVIEWS"]`). - **!days_from_last_attributed_touch_to_event** (array) - Optional - Filter by days from last attributed touch to event (e.g., `[null]`). - **aggregation** (string) - Optional - The aggregation method to use, e.g., `unique_count`. ### Request Example ```json { "branch_key": "", "branch_secret": "", "start_date": "2017-12-07T00:00:00-08:00", "end_date": "2017-12-13T23:59:59-08:00", "data_source": "eo_install", "granularity": "all", "dimensions": [ "user_data_platform" ], "filters": { "user_data_platform": [ "IOS_APP", "ANDROID_APP" ], "last_attributed_touch_data_plus_via_features": [ "MOBILE_DEEPVIEWS" ], "!days_from_last_attributed_touch_to_event": [ null ] }, "aggregation": "unique_count" } ``` ### Response #### Success Response (200) - **results** (array) - An array of result objects. - **result** (object) - Contains the aggregated data. - **user_data_platform** (string) - The platform. - **unique_count** (integer) - The unique count for the platform. - **timestamp** (string) - The timestamp of the data point. - **paging** (object) - Pagination information. - **total_count** (integer) - The total number of results. #### Response Example ```json { "results": [ { "result": { "user_data_platform": "ANDROID_APP", "unique_count": 435 }, "timestamp": "2017-12-07T08:00:00.000Z" }, { "result": { "user_data_platform": "IOS_APP", "unique_count": 393 }, "timestamp": "2017-12-07T08:00:00.000Z" } ], "paging": { "total_count": 2 } } ``` ``` -------------------------------- ### Get Attributed Installs Per Day Source: https://help.branch.io/apidocs/query-api-recipes Retrieves the number of attributed installs per day. Useful for understanding how many installs are driven by marketing efforts. ```curl curl -X POST -H "Content-Type: application/json" -d '{ "branch_key": "", "branch_secret": "", "start_date": "2017-11-29T00:00:00-08:00", "end_date": "2017-12-05T23:59:59-08:00", "data_source": "eo_install", "granularity": "day", "dimensions": [ "timestamp" ], "filters": { "!user_data_platform": [ "ROBOT" ], "!days_from_last_attributed_touch_to_event": [ "null" ] }, "aggregation": "total_count" }' "http://api.branch.io/v1/query/analytics?limit=100" ``` ```json { "results": [ { "timestamp": "2017-12-05T08:00:00.000Z", "result": { "total_count": 248 } }, { "timestamp": "2017-12-04T08:00:00.000Z", "result": { "total_count": 296 } }, { "timestamp": "2017-12-03T08:00:00.000Z", "result": { "total_count": 284 } }, ... ], "paging": { "total_count": 7 } } ``` -------------------------------- ### Get External ID API Response Example Source: https://help.branch.io/apidocs/getexternalidbranch This is an example of a successful response when retrieving the external ID for your Branch app. ```json "external_id": "XXXX-0000-xxxx" ``` -------------------------------- ### Query Installs (eo_install) Source: https://help.branch.io/apidocs/query-api-recipes This snippet shows how to query install data. Replace the placeholder values with your actual Branch key and secret. ```curl curl -X POST -H "Content-Type: application/json" -d '{ "branch_key": "", "branch_secret": "", "start_date": "2025-08-01T00:00:00-08:00", "end_date": "2025-08-07T23:59:59-08:00", "data_source": "eo_install", "granularity": "all", "dimensions": [ "last_attributed_touch_data_tilde_campaign" ], "filters": { "user_data_platform": [ "IOS_APP", "ANDROID_APP" ], "!days_from_last_attributed_touch_to_event": [ null ] }, "aggregation": "unique_count" }' "http://api.branch.io/v1/query/analytics?limit=100" ``` -------------------------------- ### Get Total Installs Per Day Source: https://help.branch.io/apidocs/query-api-recipes Retrieves the total number of installs per day over a specified time period. Useful for a high-level overview of app install trends. ```curl curl -X POST -H "Content-Type: application/json" -d '{ "branch_key": "", "branch_secret": "", "start_date": "2017-11-29T00:00:00-08:00", "end_date": "2017-12-05T23:59:59-08:00", "data_source": "eo_install", "granularity": "day", "dimensions": [ "timestamp" ], "filters": { "!user_data_platform": [ "ROBOT" ] }, "aggregation": "unique_count" }' "http://api.branch.io/v1/query/analytics?limit=100" ``` ```json { "results": [ { "timestamp": "2017-12-05T08:00:00.000Z", "result": { "unique_count": 246 } }, { "timestamp": "2017-12-04T08:00:00.000Z", "result": { "unique_count": 302 } }, { "timestamp": "2017-12-03T08:00:00.000Z", "result": { "unique_count": 277 } }, { "timestamp": "2017-12-02T08:00:00.000Z", "result": { "unique_count": 300 } }, { "timestamp": "2017-12-01T08:00:00.000Z", "result": { "unique_count": 264 } }, { "timestamp": "2017-11-30T08:00:00.000Z", "result": { "unique_count": 208 } }, { "timestamp": "2017-11-29T08:00:00.000Z", "result": { "unique_count": 225 } } ], "paging": { "total_count": 7 } } ``` -------------------------------- ### Get Attributed Installs by Campaign Source: https://help.branch.io/apidocs/query-api-recipes Retrieves the number of attributed installs, broken down by campaign. Useful for comparing the performance of different campaigns. ```curl curl -X POST -H "Content-Type: application/json" -d '{ "branch_key": "", "branch_secret": "", "start_date": "2017-11-29T00:00:00-08:00", "end_date": "2017-12-05T23:59:59-08:00", "data_source": "eo_install", "granularity": "day", "dimensions": [ "last_attributed_touch_data_tilde_campaign" ], "filters": { "!user_data_platform": [ "ROBOT" ], "!days_from_last_attributed_touch_to_event": [ "null" ] }, "aggregation": "unique_count" }' "http://api.branch.io/v1/query/analytics?limit=100" ``` ```json { "results": [ { "result": { "last_attributed_touch_data_tilde_campaign": null, "unique_count": 171 }, "timestamp": "2017-12-01T08:00:00.000Z" }, { "result": { "last_attributed_touch_data_tilde_campaign": null, "unique_count": 158 }, "timestamp": "2017-12-04T08:00:00.000Z" }, { "result": { "last_attributed_touch_data_tilde_campaign": null, "unique_count": 157 }, "timestamp": "2017-12-02T08:00:00.000Z" }, ... ], "paging": { "total_count": 56 } } ``` -------------------------------- ### Installs API Request Source: https://help.branch.io/apidocs/query-api-recipes This `curl` command shows how to query for install data. It filters by platform and specific features, and aggregates by unique count. ```curl curl -X POST -H "Content-Type: application/json" -d '{ "branch_key": "", "branch_secret": "", "start_date": "2017-12-07T00:00:00-08:00", "end_date": "2017-12-13T23:59:59-08:00", "data_source": "eo_install", "granularity": "all", "dimensions": [ "user_data_platform" ], "filters": { "user_data_platform": [ "IOS_APP", "ANDROID_APP" ], "last_attributed_touch_data_plus_via_features": [ "MOBILE_DEEPVIEWS" ], "!days_from_last_attributed_touch_to_event": [ null ] }, "aggregation": "unique_count" }' "http://api.branch.io/v1/query/analytics?limit=100" ``` -------------------------------- ### Get Export Request - Example Status URL Source: https://help.branch.io/apidocs/getdownloadexportrequest This is an example of a status URL that might be returned in a successful response, pointing to the location of the exported data. ```string https://branch-exports-web-usw2.s3.us-west-1.amazonaws.com/v2/y%3D2023/m%3D05/d%3D17/app_id%3D{APP_ID_HERE}/job_id%3D{JOB_ID_HERE}/task_id%3D{TASK_ID_HERE}/unique-csv-file-name-here.csv?X-Amz-Algorithm={AMZ_ALGORITHM_HERE}&X-Amz-Date={AMZ_DATE_HERE}&X-Amz-SignedHeaders={AMZ_SIGNED_HEADERS_HERE}&X-Amz-Expires={AMZ_EXPIRATION_HERE}&X-Amz-Credential={AMZ_CREDENTIAL_HERE}&X-Amz-Signature={AMZ_SIGNATURE_HERE} ``` -------------------------------- ### Request Open API - Install Referrer Extras Source: https://help.branch.io/apidocs/requestopen Provides the install referrer extras for tracking attribution. Ensure the format is correctly encoded. ```json "install_referrer_extras": "utm_source=some_source&utm_medium=preload&utm_campaign=null&gclid=Cj0KCQiA7IDiBRCLARIsABIPohhqdEU00f-Obte_OIVTbjPo-iLDBjkhj8ov=", ``` -------------------------------- ### Opens (eo_open) Source: https://help.branch.io/apidocs/query-api-recipes This example shows how to query for open events. It includes dimensions for user platform and desktop origin, and filters. ```APIDOC ## POST /v1/query/analytics ### Description Queries for open event analytics data. ### Method POST ### Endpoint http://api.branch.io/v1/query/analytics?limit=100 ### Request Body - **branch_key** (string) - Required - Your Branch API key. - **branch_secret** (string) - Required - Your Branch API secret. - **start_date** (string) - Required - The start date for the query (ISO 8601 format). - **end_date** (string) - Required - The end date for the query (ISO 8601 format). - **data_source** (string) - Required - The data source identifier, e.g., "eo_open". - **granularity** (string) - Optional - The granularity of the data (e.g., "all", "daily"). - **dimensions** (array) - Optional - An array of dimensions to group the data by. - **filters** (object) - Optional - An object containing filters to apply to the query. - **aggregation** (string) - Required - The type of aggregation to perform (e.g., "unique_count"). ### Request Example ```json { "branch_key": "", "branch_secret": "", "start_date": "2017-12-07T00:00:00-08:00", "end_date": "2017-12-13T23:59:59-08:00", "data_source": "eo_open", "granularity": "all", "dimensions": [ "user_data_platform", "from_desktop" ], "filters": { "user_data_platform": [ "IOS_APP", "ANDROID_APP" ], "!days_from_last_attributed_touch_to_event": [ null ] }, "aggregation": "unique_count" } ``` ### Response #### Success Response (200) - **results** (array) - An array of result objects, each containing a timestamp and the aggregated data. - **timestamp** (string) - The timestamp for the data point. - **result** (object) - The aggregated data for the given dimensions and filters. - **user_data_platform** (string) - The user data platform. - **from_desktop** (string) - Indicates if the traffic was from desktop. - **unique_count** (integer) - The unique count for the aggregation. - **paging** (object) - Pagination information. - **total_count** (integer) - The total number of results. #### Response Example ```json { "results": [ { "timestamp": "2017-12-07T08:00:00.000Z", "result": { "user_data_platform": "IOS_APP", "from_desktop": "false", "unique_count": 436 } }, { "timestamp": "2017-12-07T08:00:00.000Z", "result": { "user_data_platform": "ANDROID_APP", "from_desktop": "false", "unique_count": 395 } } ], "paging": { "total_count": 2 } } ``` ``` -------------------------------- ### Querying Purchase Data Source: https://help.branch.io/apidocs/query-api-recipes This example shows how to query purchase data, including revenue and campaign attribution. ```json { "results": [ { "timestamp": "2025-08-01T08:00:00.000Z", "result": { "last_attributed_touch_data_tilde_campaign": "", "revenue": 220439.25, "name": "PURCHASE" } }, { "timestamp": "2025-08-01T08:00:00.000Z", "result": { "last_attributed_touch_data_tilde_campaign": "", "revenue": 182050.36, "name": "PURCHASE" } } ], "paging": { "total_count": 32 } } ``` -------------------------------- ### MAC Address Example for MAC OS Source: https://help.branch.io/apidocs/desktop-over-the-top-ott-attribution This example shows how to include the MAC address for MAC OS devices in the advertising_ids parameter for session measurement. ```json "advertising_ids": { "mac_address": "88:66:5a:2f:81:fa" } ``` -------------------------------- ### Get Export Status URL Source: https://help.branch.io/apidocs/getexportdownloadstatus This example shows the structure of the response when the export job is found, providing a status URL to check the job's progress. ```json "status_url": "https://api2.branch.io/v2/analytics/{JOB_ID_HERE}" ``` -------------------------------- ### Samsung IFA Example Source: https://help.branch.io/apidocs/desktop-over-the-top-ott-attribution This example demonstrates how to pass the Samsung Identifier for Advertising (IFA) for Samsung Smart TVs (Tizen OS). ```json "advertising_ids": { "samsung_ifa": "ea31e5e0-1aa5-4181-91d7-0b56524e0274" } ``` -------------------------------- ### Request Data Export - JSON Body Example Source: https://help.branch.io/apidocs/requestcrosseventsdataexport This JSON object demonstrates the structure for requesting a data export. It includes start and end dates, dimensions, filters, granularity, and aggregation specifications. ```json { "start_date": "2023-05-15", "end_date": "2023-05-16", "dimensions": [ "user_data_os" ], "filter": { "type": "in", "dimension": "name", "values": [ "x", "y" ] }, "granularity": "all", "limit_sort_spec": { "sort_columns": [] }, "aggregations": [ { "field_name": "sketch_unique_count", "display_name": "unique_lifecycle_events_count", "data_source": "eo_user_lifecycle_event" } ] } ```