> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# Cross-Events Export API

Query and compare vast pools of data across multiple sources.

[Read the Cross-Events Export API overview](https://help.branch.io/apidocs/cross-events-export/overview.md)

## Get export download status

`GET https://api2.branch.io/v1/branch_aggregate/async/status/{job_id}`

Receive a status update on your aggregate export request, as well as a URL to the data.

### Parameters

- `app_id` (string, query, required) — The unique identifier for the app. Alternatively, provide `organization_id`.
- `job_id` (string, path, required) — The unique ID of the request. Obtained from the [export request](https://help.branch.io/apidocs/cross-events-export/overview.md#request-data-export).

### Responses

- `200` — Job successfully finished.
- `400` — Bad request—typically an invalid or missing credential or parameter.
- `404` — Job ID not found.
- `429` — Rate limit exceeded—reduce request frequency and retry.

### Returns

Job successfully finished. Returns `400`, `404`, and `429` on failure — see the response panel for the error shape.

### Example request

```bash
curl 'https://api2.branch.io/v1/branch_aggregate/async/status/a1b2c3d4?app_id=123456789012345680' \
  --request GET \
  --header 'Access-Token: <Access-Token>'
```

### Example responses

`200`

```json
{
  "code": 200,
  "status": "FINISHED",
  "response_url": "https://branch-exports-usw2.s3.amazonaws.com/partner-query/2023-05-12-2023-05-19-eo_install-day-{JOB_ID}.csv?Signature={SIGNATURE}&AWSAccessKeyId={AWS_KEY}&Expires={EXPIRATION}"
}
```

`400`

```json
{
  "error": {
    "message": "Authentication failed.",
    "code": 400
  }
}
```

`429`

```json
{
  "error": {
    "code": 429,
    "message": "Rate limit reached."
  }
}
```

## Request data export

`POST https://api2.branch.io/v1/branch_aggregate/async/analytics`

Initiate an export of your aggregate Branch data.

### Parameters

- `end_date` (string, required) — The end of the interval time range represented as an ISO-8601 complete date.
- `start_date` (string, required) — The start of the interval time range represented as an ISO-8601 complete date.
- `aggregations` (array of object) — An array where each element is an aggregation object. An aggregation object requires a field name, a display name, and a data source. See [schema](https://help.branch.io/apidocs/cross-events-export/overview.md) and [more](https://help.branch.io/apidocs/cross-events-export/overview.md#data-source-field-name).
- `dimensions` (array of enum) — An array representing the dimensions to group by. See the [dimensions](https://help.branch.io/apidocs/cross-events-export/overview.md#dimensions) section for more. One of `link_alias`, `link_archived`, `link_creation_source`, `link_dollar_sign_3p`, `link_dollar_sign_android_deeplink_path`, `link_dollar_sign_android_deepview`, `link_dollar_sign_android_passive_deepview`, `link_dollar_sign_android_url`, `link_dollar_sign_canonical_identifier`, `link_dollar_sign_canonical_url`, `link_dollar_sign_deeplink_path`, `link_dollar_sign_desktop_deeplink_path`, `link_dollar_sign_desktop_deepview`, `link_dollar_sign_desktop_passive_deepview`, `link_dollar_sign_desktop_url`, `link_dollar_sign_fallback_url`, `link_dollar_sign_ios_deeplink_path`, `link_dollar_sign_ios_deepview`, `link_dollar_sign_ios_passive_deepview`, `link_dollar_sign_ios_url`, `link_dollar_sign_marketing_title`, `link_dollar_sign_og_description`, `link_dollar_sign_og_image_url`, `link_dollar_sign_og_title`, `link_dollar_sign_og_type`, `link_dollar_sign_og_url`, `link_dollar_sign_uri_redirect_mode`, `link_dollar_sign_web_only`, `link_domain`, `link_id`, `link_tilde_campaign`, `link_tilde_channel`, `link_tilde_feature`, `link_tilde_quick_link_template_id`, `link_tilde_tags`, `link_type`, `last_op`, `name`, `origin`, `deep_linked`, `from_desktop`, `attributed`, `user_data_app_store`, `user_data_app_version`, `user_data_os`, `user_data_language`, `user_data_platform`, `user_data_environment`, `user_data_geo_dma_code`, `user_data_geo_country_code`, `user_data_country`, `user_data_geo_region_en`, `user_data_opted_in`, `user_data_opted_in_status`, `last_attributed_touch_type`, `last_attributed_touch_data_tilde_tags`, `last_attributed_touch_data_tilde_secondary_publisher`, `last_attributed_touch_data_tilde_campaign`, `last_attributed_touch_data_tilde_advertising_partner_name`, `last_attributed_touch_data_tilde_advertising_partner_id`, `last_attributed_touch_data_tilde_feature`, `last_attributed_touch_data_tilde_creative_name`, `last_attributed_touch_data_tilde_creative_id`, `last_attributed_touch_data_tilde_ad_name`, `last_attributed_touch_data_tilde_ad_id`, `last_attributed_touch_data_tilde_campaign_id`, `last_attributed_touch_data_tilde_placement`, `last_attributed_touch_data_tilde_stage`, `last_attributed_touch_data_tilde_channel`, `last_attributed_touch_data_tilde_ad_set_name`, `last_attributed_touch_data_tilde_ad_set_id`, `last_attributed_touch_data_tilde_keyword`, `last_attributed_touch_data_tilde_keyword_id`, `last_attributed_touch_data_tilde_journey_id`, `last_attributed_touch_data_tilde_view_name`, `last_attributed_touch_data_tilde_view_id`, `last_attributed_touch_data_tilde_agency`, `last_attributed_touch_data_tilde_agency_id`, `last_attributed_touch_data_tilde_customer_secondary_publisher`, `last_attributed_touch_data_tilde_customer_ad_set_name`, `last_attributed_touch_data_tilde_customer_ad_name`, `last_attributed_touch_data_tilde_customer_keyword`, `last_attributed_touch_data_tilde_customer_placement`, `last_attributed_touch_data_tilde_customer_sub_site_name`, `last_attributed_touch_data_tilde_customer_campaign`, `last_attributed_touch_data_plus_web_format`, `last_attributed_touch_data_plus_current_feature`, `last_attributed_touch_data_plus_via_features`, `last_attributed_touch_data_dollar_marketing_title`, `last_attributed_touch_data_dollar_3p`, `last_cta_view_data_tilde_ad_name`, `last_cta_view_data_tilde_secondary_publisher`, `last_cta_view_data_tilde_campaign`, `last_cta_view_data_tilde_advertising_partner_name`, `last_cta_view_data_tilde_feature`, `last_cta_view_data_tilde_ad_set_name`, `last_cta_view_data_tilde_ad_set_id`, `last_cta_view_data_tilde_campaign_id`, `last_cta_view_data_tilde_creative_name`, `last_cta_view_data_tilde_creative_id`, `last_cta_view_data_plus_via_features`, `last_cta_view_data_dollar_3p`, `last_cta_view_data_tilde_tags`, `last_cta_view_data_plus_web_format`, `last_cta_view_data_tilde_channel`, `last_cta_view_data_tilde_ad_id`, `last_cta_view_data_tilde_stage`, `body_ad_network_id`, `body_campaign_id`, `body_app_id`, `body_redownload`, `body_source_app_id`, `body_conversion_value`, `body_last_attributed_touch_data_tilde_creative_name`, `body_last_attributed_touch_data_tilde_ad_set_name`, `body_last_attributed_touch_data_tilde_creative_id`, `body_last_attributed_touch_data_tilde_ad_set_id`, `body_last_attributed_touch_data_tilde_ad_name`, `body_last_attributed_touch_data_tilde_ad_id`, `body_last_attributed_touch_data_tilde_campaign`, `body_last_attributed_touch_data_tilde_campaign_id`, `body_last_attributed_touch_data_tilde_campaign_name`, `annotation_dollar_3p`, `annotation_conversion_value_mapped_value`, `annotation_conversion_value_revision`, `annotation_campaign_id_mapped_value`, `annotation_campaign_id_revision`, `annotation_source_app_id_mapped_value`, `annotation_source_app_id_revision`, `annotation_customer_event_alias`, `days_from_last_attributed_touch_to_event`, `days_from_last_cta_view_to_event`, `event_data_product_categories`, `event_data_custom_param_1`, `event_data_custom_param_2`, `event_data_custom_param_3`, `first_event_for_user`, `customer_event_alias`.
- `filter` (object) — An object representing a filter or multiple filters. See filter [examples](https://help.branch.io/apidocs/cross-events-export/overview.md#filters).
- `granularity` (enum) — The time granularity that each band value will represent. One of `day`, `week`, `month`, `all`.
- `limit_sort_spec` (object) — An object describing column/row ordering and limiting. See [schema](https://help.branch.io/apidocs/cross-events-export/overview.md).
- `response_format` (enum) — Compression format to use for the data file. One of `parquet`, `csv`, `json`.
- `response_format_compression` (enum) — Compression method to use for the data file. One of `snappy`, `gz`.

### Responses

- `200` — Success.
- `400` — Bad request—typically an invalid or missing credential or parameter.
- `429` — Rate limit exceeded—reduce request frequency and retry.

### Returns

Success. Returns `400` and `429` on failure — see the response panel for the error shape.

### Example request

```bash
curl 'https://api2.branch.io/v1/branch_aggregate/async/analytics?app_id=%3Capp_id%3E' \
  --request POST \
  --header 'Access-Token: <Access-Token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "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"
      },
      {
        "field_name": "total_count",
        "display_name": "eo_click",
        "data_source": "eo_click"
      }
    ],
    "response_format_compression": "snappy",
    "response_format": "parquet"
  }'
```

### Example responses

`200`

```json
{
  "code": 200,
  "job_id": "XXXX-0000-xxxx",
  "status_url": "https://api2.branch.io/v1/branch_aggregate/async/status/a1b2c3d4"
}
```

`400`

```json
{
  "error": {
    "message": "Authentication failed.",
    "code": 400
  }
}
```

`429`

```json
{
  "error": {
    "code": 429,
    "message": "Rate limit reached."
  }
}
```