---
title: "Query Analytics Report"
method: POST
path: "/reports/sync_report"
tags: ["Analytics"]
---

# Query Analytics Report

`POST /reports/sync_report`

This endpoint doesn't consume Apollo credits. Learn more about [API pricing and credits](https://docs.apollo.io/docs/api-pricing).

Use the Query Analytics Report endpoint to programmatically query <a href="https://knowledge.apollo.io/hc/en-us/articles/33574373762317-Analytics-Overview" target="_blank">Apollo analytics</a> and retrieve aggregated sales activity data for your team.<br><br>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. <br><br>Three query modes are supported: flat totals (no <code>group_by</code>), grouped by one dimension such as user or sequence, and pivot cross-tab (one <code>group_by</code> dimension as rows + one <code>pivot_group_by</code> dimension as columns). Each array supports a maximum of one entry.<br><br>
<strong>Authentication:</strong> Requires an Apollo API key with access to the <code>api/v1/reports/sync_report</code> API. When creating or editing an API key in Apollo Settings, open the <strong>APIs</strong> tab and select <code>api/v1/reports/sync_report</code> from the list. Check out <a href="https://docs.apollo.io/docs/create-api-key">Create an API Key</a> for detailed instructions.<br><br><strong>Tip:</strong> The easiest way to discover valid metric and group_by combinations is to build a report interactively at <a href="https://app.apollo.io/#/analytics/reports/new" target="_blank">Apollo Analytics → Start from scratch</a>, then replicate that configuration in your API request.

## Request body

- object
  - `metrics` object[], 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 <code>smart_datetime_reference</code> and <code>smart_user_id_reference</code> values are metric-specific — using the wrong values will return no data. Refer to the <a href="https://docs.apollo.io/reference/sync-report-metrics" target="_blank">Metrics and Dimensions Reference</a> for valid metric names and the correct reference fields for each. <br><br>Pass an empty array <code>[]</code> to return a response with no metric columns.
    - `value` string, required — The metric identifier. For built-in metrics, use the metric name (e.g. <code>num_emails_sent</code>). For team-defined custom metrics, use the format <code>custom_metric_{id}</code> where <code>{id}</code> is the custom metric's id.
    - `smart_datetime_reference` string, required — The date column name to use for this metric time range. Valid values depend on the metric. See the smart reference field values table for supported values by metric type. Unsupported values may cause the related date or user filter not to apply. <br><br>Example: <code>activity_datetime</code>
    - `smart_user_id_reference` string, required — The user column name that filters per user. Many metrics use <code>user_id</code>. See the smart reference field values table for supported values by metric family. Unsupported values may cause the related date or user filter not to apply. <br><br>Example: <code>user_id</code>
    - `display_name` string — Optional label override for this metric's column in the response.
  - `group_by` object[], required — The dimension to group results by (row dimension). Pass one object to break results down by that dimension. Pass an empty array <code>[]</code> for flat totals with no grouping. <br><br>Only one entry is supported. Refer to the <a href="https://docs.apollo.io/reference/sync-report-metrics" target="_blank">Metrics and Dimensions Reference</a> for valid dimension names.
    - `name` string, required — The dimension name. <br><br>Example: <code>smart_user_id</code>
    - `limit` integer — Maximum number of dimension values to return.
  - `pivot_group_by` object[] — The dimension to pivot on (column dimension). Used together with <code>group_by</code> to produce a two-dimensional cross-tab table: <code>group_by</code> defines the row dimension and <code>pivot_group_by</code> defines the column dimension. Pass an empty array <code>[]</code> for non-pivot queries. <br><br>Only one entry is supported.
    - `name` string, required — The dimension name to pivot on. <br><br>Example: <code>emailer_campaign_id</code>
    - `limit` integer — Maximum number of pivot column values to return.
  - `sorts` object[], required — Sort order for the result rows. Only the first entry is applied. Pass an empty array <code>[]</code> to use the default order. <br><br>Sorting is supported by metric value — provide the <code>metric</code> field with the same structure as an entry in the <code>metrics</code> array. The <code>asc</code> field controls direction (<code>true</code> = ascending, <code>false</code> = descending). <br><br>Sorting by dimension value (e.g. alphabetically by user name) is not supported via the API.
    - `asc` boolean, required — Sort ascending (<code>true</code>) or descending (<code>false</code>).
    - `metric` object — Sort by a metric column. Provide the same structure as a metric entry in the <code>metrics</code> array.
      - `value` string
      - `smart_datetime_reference` string
      - `smart_user_id_reference` string
  - `filters` object, required — Key/value filter map to narrow the result set. Pass an empty object <code>{}</code> for no filters. Common filter keys are documented in the <code>properties</code> below; additional dimension-based filters may also be passed using the same key names as <code>group_by[].name</code> values. Refer to the <a href="https://docs.apollo.io/reference/sync-report-metrics" target="_blank">Metrics and Dimensions Reference</a> for a complete list.
    - `smart_user_id` string[] — Filter to specific team member IDs. Use <code>"current"</code> for the authenticated user. <br><br>Example: <code>["current"]</code>
    - `smart_subteam_id` string[] — Filter to specific sub-team IDs.
    - `emailer_campaign_ids` string[] — Filter to specific sequence IDs.
    - `contact_stage_ids` string[] — Filter to specific contact stage IDs.
    - `account_stage_ids` string[] — Filter to specific account stage IDs.
    - `opportunity_stage_ids` string[] — Filter to specific opportunity stage IDs.
    - `email_account_ids` string[] — Filter to specific sender mailbox IDs.
    - `smart_datetime_range` object — Required when <code>date_ranges[].modality</code> is <code>custom_range</code>. Specifies the exact date window as ISO 8601 date strings.
      - `min` string, required — Start date (inclusive). Format: <code>YYYY-MM-DD</code>. <br><br>Example: <code>2024-01-01</code>
      - `max` string, required — End date (inclusive). Format: <code>YYYY-MM-DD</code>. <br><br>Example: <code>2024-03-31</code>
  - `group_by_totals_selected` boolean, required — When <code>true</code>, the response includes an aggregated totals row in addition to the per-dimension-value rows.
  - `pivot_group_by_totals_selected` boolean, required — When <code>true</code>, the pivot response includes an aggregated totals column in addition to the per-pivot-value columns.
  - `date_ranges` object[], required — The time window for the query. Provide one object with a <code>modality</code> preset. For a custom date range, set <code>modality</code> to <code>custom_range</code> and add a <code>smart_datetime_range</code> key in <code>filters</code> with <code>{"min": "YYYY-MM-DD", "max": "YYYY-MM-DD"}</code>.
    - `modality` string, required — Date range preset. Valid values: <code>today</code>, <code>yesterday</code>, <code>current_week</code>, <code>current_month</code>, <code>current_quarter</code>, <code>current_year</code>, <code>last_7_days</code>, <code>last_2_weeks</code>, <code>last_30_days</code>, <code>last_3_months</code>, <code>last_6_months</code>, <code>last_12_months</code>, <code>last_4_quarters</code>, <code>last_2_years</code>, <code>previous_week</code>, <code>previous_month</code>, <code>previous_quarter</code>, <code>previous_year</code>, <code>all_time</code>, <code>custom_range</code> (requires <code>smart_datetime_range</code> in <code>filters</code>).
  - `skip_group_by_values` string[] — Exclude specific dimension values from the result rows. Values must match the raw <code>key</code> field returned in bucket responses for the active <code>group_by</code> dimension (e.g. a contact stage ID string, a user ID string, or a date string for datetime dimensions). Maximum 500 entries.
  - `min_ratio_denominator` integer — Minimum denominator threshold for ratio metrics. Rows where the denominator falls below this value are excluded from ratio calculations.

## Response `200`

200

- object
  - `response` object — The query result. Contains four sub-keys depending on query mode and flags. See response examples for each shape.
    - `table_response` object — Main aggregated data. Shape varies by query mode: a flat key/value object when <code>group_by</code> is empty (metric name → value); a bucketed object <code>{ "dimension": { "buckets": [...] } }</code> for grouped queries; a nested bucketed object for pivot queries where the outer key is the <code>pivot_group_by</code> dimension and each outer bucket contains a nested <code>group_by</code> dimension with its own <code>buckets</code>.
    - `group_by_total_response` object — Aggregated totals per <code>group_by</code> dimension value, without pivot breakdown. Same bucketed structure as <code>table_response</code>. Populated when <code>group_by_totals_selected</code> is <code>true</code>; otherwise <code>{}</code>.
    - `pivot_group_by_total_response` object — Aggregated totals per <code>pivot_group_by</code> dimension value, without group_by breakdown. Populated when <code>pivot_group_by_totals_selected</code> is <code>true</code>; otherwise <code>{}</code>.
  - `incompatible_filters` object — A map of filter keys that were incompatible with one or more requested metrics and were silently ignored. Keys are filter names; values are arrays of affected metric names. Inspect this field when results appear incomplete.
  - `goals` object[] — Goal attainment data. This field is unrelated to data querying — you can ignore it.

## Other responses

- `400` — 400
- `401` — 401
- `422` — 422
- `429` — 429

---

[API](https://skmtc.dev/apollo/apis/apollo-rest-api.md) · [All operations](https://skmtc.dev/apollo/apis/apollo-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/apollo/apollo-rest-api/revisions/c715a05fa6e2/schema)