Branch APIs

https://help.branch.io/apidocs
Admin
Branch APIs provide a comprehensive platform for mobile linking, deep linking, QR code generation,...
Tokens:263,411
Snippets:1,589
Trust Score:10
Update:5 months ago
Show doc for...
Tokens:
Raw
### 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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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":"<YOUR_BRANCH_KEY>",
                    "branch_secret":"<YOUR_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":"<YOUR_BRANCH_KEY>",
    "branch_secret":"<YOUR_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
}
```
```

--------------------------------

### 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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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": "<YOUR_CAMPAIGN_NAME_1>",
        "unique_count": 425
      },
      "timestamp": "2025-08-01T08:00:00.000Z"
    },
    {
      "result": {
        "last_attributed_touch_data_tilde_campaign": "<YOUR_CAMPAIGN_NAME_2>",
        "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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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": "<YOUR_BRANCH_KEY>",
  "branch_secret": "<YOUR_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": "<YOUR_CAMPAIGN_NAME_1>",
        "revenue": 220439.25,
        "name": "PURCHASE"
      }
    },
    {
      "timestamp": "2025-08-01T08:00:00.000Z",
      "result": {
        "last_attributed_touch_data_tilde_campaign": "<YOUR_CAMPAIGN_NAME_2>",
        "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 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: <YOUR_ACCESS_TOKEN>\"
```

--------------------------------

### 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"
  }
 ]
}
```
Tokens:
Raw