Managing Reports

Overview

All report endpoints follow a shared POST /query pattern. You parameterize each request with promotedObjectType: either apps for App Store app campaigns or business-brands for Apple Maps campaigns. The request body, response objects, available groupBy dimensions, and supported options differ between the two promoted object types.

Choose a Reporting Endpoint

Query one of the following endpoints based on your promoted object type and the entity level you want to report on:

Build the Request

Every report request uses either AppsReportingRequest or BrandsReportingRequest as the request body. Both share the same top-level fields:

• The timeRange field defines the reporting window via TimeRange: start date, end date, timeZone (UTC or ORTZ), and optional granularity (HOURLY, DAILY, WEEKLY, MONTHLY).

• The filters field is an array of Filter conditions that narrow results by field, operator, and value.

• The sorting field is an array of Sorting objects that order rows by field and direction.

• The pagination field uses RequestPagination, with offset and pageSize (maximum 5000, default 100).

• The fields field is an optional list of field names to return. Omit it to receive all fields.

• The groupBy field is an optional dimensional breakdown. Supported values differ between Apps and Brands, and additional restrictions apply at the keyword and search term entity levels. When you omit groupBy, the response returns one aggregate row per entity with no dimensional breakdown. We recommend providing at least one groupBy value to get meaningful segmented data in most reporting use cases.

• The options field sets row inclusion flags via AppsOptions or BrandsOptions.

Read the Response

All report responses share the same envelope: a result object containing a rows array of report rows and a summary.grandTotal object, plus a pagination object and an error field. Each row contains:

• The totalMetrics field holds aggregate metrics for the row over the full time range.

• The granularMetrics field breaks out metrics by the requested granularity period, and it appears only when you specify granularity in the request.

• The metadata field holds entity attributes (campaign name, status, targeting, and so on) plus any groupBy dimension values applied to the row.

When you include GRAND_TOTAL in options.includeRows, the response also includes a summary row with totals across all result rows.

Apply Granularity Constraints

Granularity is an optional time-series breakdown that applies to granularMetrics. The following constraints apply to all entities and both promoted object types unless noted:

To request a single day of data, omit granularity entirely. For a single-day request, the response returns results in totalMetrics only, since there’s no granularMetrics breakdown to compute.

Compare Apps and Brands Reporting

Apps and Brands campaigns measure different coverage: app installs and engagement versus brand visibility and map interactions. Their reporting reflects this distinction. The two promoted object types use separate request and response objects and differ in the following ways:

Include Additional Rows

The options.includeRows field controls which additional rows appear in the response:

• The GRAND_TOTAL value adds a summary row with aggregate totals across all result rows. Both Apps and Brands support it.

• The EMPTY_METRICS value includes rows for entities that have no metric activity during the requested period. Only Apps supports it, and you can’t combine it with groupBy.

See Also

Related Documentation

• Insights Endpoints
• Recommendations Endpoints
• Suggestions Endpoints
• Change History Endpoints

Reports

• App Store Reports Endpoints
• Brands Reports Endpoints
• Apps Data Objects
• Brands Data Objects
• Shared Objects