> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics Reports

> Request and download App Store analytics — downloads, sessions, commerce, engagement

The Analytics Reports API gives you programmatic access to 140+ report types: App Downloads, App Sessions, Commerce, App Store Engagement, Framework Usage, and more. Data is split into segments with downloadable URLs (gzip TSV).

<Note>
  **Role required**: Admin, Finance, or Sales and Reports. New report requests may take **24–48 hours** before data is available.
</Note>

***

## Flow Overview

```
1. List/Create report request for your app
2. List reports for the request (e.g. "App Downloads Standard")
3. List instances for a report (daily, weekly, monthly granularity)
4. List segments for an instance
5. Download segment URL (gzip TSV with actual data)
```

***

## List Report Requests

```
GET /v1/connect/apps/:appId/analytics/report-requests
```

List analytics report requests for an app. If empty, create one first.

### Query Parameters

| Name       | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| accessType | string  | Filter: `ONGOING` or `ONE_TIME_SNAPSHOT` |
| limit      | integer | Max results (default 50)                 |

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "data": [
      {
        "type": "analyticsReportRequests",
        "id": "7e9b84a2-b441-49ce-a723-649fa483029c",
        "attributes": {
          "accessType": "ONGOING",
          "stoppedDueToInactivity": false
        }
      }
    ]
  }
}
```

***

## Create Report Request

```
POST /v1/connect/apps/:appId/analytics/report-requests
```

Create a new analytics report request. **ONGOING** generates daily reports; **ONE\_TIME\_SNAPSHOT** fetches historical data.

### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "accessType": "ONGOING"
}
```

| Field      | Type   | Description                                                   |
| ---------- | ------ | ------------------------------------------------------------- |
| accessType | string | `ONGOING` (daily reports) or `ONE_TIME_SNAPSHOT` (historical) |

***

## List Reports for Request

```
GET /v1/connect/analytics/report-requests/:requestId/reports
```

List available reports (140+ types). Filter by category to narrow down.

### Query Parameters

| Name     | Type    | Description                                                                       |
| -------- | ------- | --------------------------------------------------------------------------------- |
| category | string  | `APP_USAGE`, `COMMERCE`, `APP_STORE_ENGAGEMENT`, `FRAMEWORK_USAGE`, `PERFORMANCE` |
| limit    | integer | Max results (default 50)                                                          |

### Example Report Types

| Category               | Examples                                                |
| ---------------------- | ------------------------------------------------------- |
| COMMERCE               | App Downloads Standard, App Store Purchases, Pre-Orders |
| APP\_USAGE             | App Sessions, Installation and Deletion                 |
| APP\_STORE\_ENGAGEMENT | Discovery and Engagement                                |
| FRAMEWORK\_USAGE       | Home Screen Widgets, Spatial Audio, etc.                |
| PERFORMANCE            | App Install Performance                                 |

***

## List Report Instances

```
GET /v1/connect/analytics/reports/:reportId/instances
```

List instances for a report. Each instance represents a granularity (daily, weekly, monthly).

### Path Parameters

| Name     | Type   | Description                                                |
| -------- | ------ | ---------------------------------------------------------- |
| reportId | string | Report ID (e.g. `r3-7e9b84a2-b441-49ce-a723-649fa483029c`) |

***

## List Segments

```
GET /v1/connect/analytics/report-instances/:instanceId/segments
```

List segments for an instance. Each segment has a **URL** to download the actual data (gzip-compressed TSV).

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "data": [
      {
        "type": "analyticsReportSegments",
        "id": "...",
        "attributes": {
          "url": "https://...",
          "checksum": "...",
          "sizeInBytes": 1234
        }
      }
    ]
  }
}
```

### Download Report Data

1. Take the `url` from a segment
2. Fetch with your JWT (or the segment URL may be pre-signed by Apple)
3. Decompress the gzip response
4. Parse the TSV (tab-separated values)

***

## Get Segment Details

```
GET /v1/connect/analytics/report-segments/:segmentId
```

Get a single segment's details including the download URL.

***

## Code Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # 1. Create report request (if none exists)
  curl -X POST "https://api.appeeky.com/v1/connect/apps/6759740679/analytics/report-requests" \
    -H "X-API-Key: YOUR_APEEKY_KEY" \
    -H "X-ASC-Issuer-Id: YOUR_ISSUER_ID" \
    -H "X-ASC-Key-Id: YOUR_KEY_ID" \
    -H "X-ASC-Private-Key: YOUR_PRIVATE_KEY" \
    -H "Content-Type: application/json" \
    -d '{"accessType":"ONGOING"}'

  # 2. List reports (e.g. filter by COMMERCE)
  curl -X GET "https://api.appeeky.com/v1/connect/analytics/report-requests/7e9b84a2.../reports?category=COMMERCE" \
    -H "X-API-Key: YOUR_APEEKY_KEY" \
    -H "X-ASC-Issuer-Id: YOUR_ISSUER_ID" \
    -H "X-ASC-Key-Id: YOUR_KEY_ID" \
    -H "X-ASC-Private-Key: YOUR_PRIVATE_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  // Full flow: list requests → list reports → list instances → list segments
  const appId = "6759740679";
  const headers = {
    "X-API-Key": "YOUR_APEEKY_KEY",
    "X-ASC-Issuer-Id": "YOUR_ISSUER_ID",
    "X-ASC-Key-Id": "YOUR_KEY_ID",
    "X-ASC-Private-Key": process.env.ASC_PRIVATE_KEY,
  };

  const requests = await fetch(
    `https://api.appeeky.com/v1/connect/apps/${appId}/analytics/report-requests`,
    { headers }
  ).then((r) => r.json());

  const requestId = requests.data.data[0]?.id;
  const reports = await fetch(
    `https://api.appeeky.com/v1/connect/analytics/report-requests/${requestId}/reports`,
    { headers }
  ).then((r) => r.json());

  // Find "App Downloads Standard"
  const downloadReport = reports.data.data.find(
    (r) => r.attributes?.name === "App Downloads Standard"
  );
  const reportId = downloadReport?.id;
  ```
</CodeGroup>

***

## Credits

| Endpoint             | Credits |
| -------------------- | ------- |
| GET report-requests  | 2       |
| POST report-requests | 3       |
| GET reports          | 2       |
| GET instances        | 2       |
| GET segments         | 2       |
| GET segment          | 1       |