Query Analytics Report

post

https://api.apollo.io/api/v1/reports/sync_report

Use the Query Analytics Report endpoint to programmatically query Apollo's analytics engine and retrieve aggregated sales activity data for your team.

This endpoint accepts a flexible payload specifying which metrics to measure, how to group and filter results, and which date range to apply — returning the same data that powers Apollo's built-in Analytics dashboards.

Three query modes are supported: flat totals (no group_by), grouped by one dimension such as user or sequence, and pivot cross-tab (one group_by dimension as rows + one pivot_group_by dimension as columns). Each array supports a maximum of one entry.

Authentication: Requires an Apollo API key with access to the api/v1/reports/sync_report API. When creating or editing an API key in Apollo Settings, open the APIs tab and select api/v1/reports/sync_report from the list. Refer to Create API Keys for detailed instructions.

Tip: The easiest way to discover valid metric and group_by combinations is to build a report interactively at Apollo Analytics → Start from scratch, then replicate that configuration in your API request.

Body Params

metrics

array of objects

required

The metrics to query. Each object specifies which metric to measure and which date and user columns the engine should use for that metric. The smart_datetime_reference and smart_user_id_reference values are metric-specific — using the wrong values will return no data. Refer to the Metrics and Dimensions Reference for valid metric names and the correct reference fields for each.

Pass an empty array [] to return a response with no metric columns.

metrics*

group_by

array of objects

required

length ≤ 1

The dimension to group results by (row dimension). Pass one object to break results down by that dimension. Pass an empty array [] for flat totals with no grouping.

Only one entry is supported. Refer to the Metrics and Dimensions Reference for valid dimension names.

group_by*

pivot_group_by

array of objects

length ≤ 1

The dimension to pivot on (column dimension). Used together with group_by to produce a two-dimensional cross-tab table: group_by defines the row dimension and pivot_group_by defines the column dimension. Pass an empty array [] for non-pivot queries.

Only one entry is supported.

pivot_group_by

sorts

array of objects

required

Sort order for the result rows. Only the first entry is applied. Pass an empty array [] to use the default order.

Sorting is supported by metric value — provide the metric field with the same structure as an entry in the metrics array. The asc field controls direction (true = ascending, false = descending).

Sorting by dimension value (e.g. alphabetically by user name) is not supported via the API.

sorts*

filters

object

required

Key/value filter map to narrow the result set. Pass an empty object {} for no filters. Common filter keys are documented in the properties below; additional dimension-based filters may also be passed using the same key names as group_by[].name values. Refer to the Metrics and Dimensions Reference for a complete list.

group_by_totals_selected

boolean

required

When true, the response includes an aggregated totals row in addition to the per-dimension-value rows.

pivot_group_by_totals_selected

boolean

required

When true, the pivot response includes an aggregated totals column in addition to the per-pivot-value columns.

date_ranges

array of objects

required

length ≤ 1

The time window for the query. Provide one object with a modality preset. For a custom date range, set modality to custom_range and add a smart_datetime_range key in filters with {"min": "YYYY-MM-DD", "max": "YYYY-MM-DD"}.

date_ranges*

skip_group_by_values

array of strings

length ≤ 500

Exclude specific dimension values from the result rows. Values must match the raw key field returned in bucket responses for the active group_by dimension (e.g. a contact stage ID string, a user ID string, or a date string for datetime dimensions). Maximum 500 entries.

skip_group_by_values

min_ratio_denominator

integer

Defaults to 0

Minimum denominator threshold for ratio metrics. Rows where the denominator falls below this value are excluded from ratio calculations.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200200

400400

401401

422422

429429