Apollo.io Analytics API
The Query Analytics Report endpoint — metrics, dimensions and filters over engagement data. 1 operation(s) from the published Apollo OpenAPI.
OpenAPI Specification
openapi: 3.1.0
info:
title: Apollo.io Analytics API
version: '1.0'
summary: Programmatic access to Apollo's sales intelligence and engagement platform — data enrichment,
prospect and company search, and go-to-market workflow management.
description: 'The Apollo API provides programmatic access to [Apollo](https://www.apollo.io/), the all-in-one
sales intelligence and engagement platform. Use it to enrich people and company data (individually
or in bulk), search Apollo''s database of over 240 million contacts and 30 million companies, and
manage accounts, contacts, deals, sequences, tasks, calls, and conversations in your go-to-market
workflows.
## Base URL
All API requests are made to `https://api.apollo.io/api/v1`.
## Authentication
- **Apollo users** authenticate with an API key passed in the `x-api-key` request header. See [Create
API Keys](https://docs.apollo.io/docs/create-api-key).
- **Apollo partners** building integrations on behalf of mutual users authenticate with the [OAuth
2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).
## Rate limits & credits
Rate limits and credit consumption depend on your [Apollo pricing plan](https://docs.apollo.io/docs/api-pricing).
Check your current limits and usage with the [View API Usage Stats and Rate Limits](https://docs.apollo.io/reference/view-api-usage-stats)
endpoint. For more details, see [Rate Limits](https://docs.apollo.io/reference/rate-limits) and the
[API FAQs](https://docs.apollo.io/docs/apollo-api-faqs).
New to the API? Start with the [Apollo API overview](https://docs.apollo.io/reference/apollo-api).'
termsOfService: https://www.apollo.io/terms/api
contact:
name: Apollo API Support
url: https://docs.apollo.io/
servers:
- url: https://api.apollo.io/api/v1
tags:
- name: Analytics
description: Query saved analytics reports.
security:
- apiKey: []
- bearerAuth: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: '[Recommended] API key, passed in the `x-api-key` request header.
See [Create API Keys](https://docs.apollo.io/docs/create-api-key).'
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'OAuth 2.0 access token, used by Apollo partners building integrations.
See the [OAuth 2.0 authorization flow](https://docs.apollo.io/docs/use-oauth-20-authorization-flow-to-access-apollo-user-information-partners).'
paths:
/reports/sync_report:
post:
summary: Query Analytics Report
description: '## Endpoint essentials
**API key access:** `api/v1/reports/sync_report` or `Master API key`
**OAuth scopes:** `report_sync`
**Credit usage:** `0 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.'
tags:
- Analytics
operationId: sync-report
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- metrics
- group_by
- sorts
- filters
- group_by_totals_selected
- pivot_group_by_totals_selected
- date_ranges
properties:
metrics:
type: array
description: 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.
items:
type: object
required:
- value
- smart_datetime_reference
- smart_user_id_reference
properties:
value:
type: string
description: 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:
type: string
description: '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:
type: string
description: '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:
type: string
description: Optional label override for this metric's column in the response.
group_by:
type: array
maxItems: 1
description: 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.
items:
type: object
required:
- name
properties:
name:
type: string
description: 'The dimension name. <br><br>Example: <code>smart_user_id</code>'
limit:
type: integer
description: Maximum number of dimension values to return.
pivot_group_by:
type: array
maxItems: 1
description: '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.'
items:
type: object
required:
- name
properties:
name:
type: string
description: 'The dimension name to pivot on. <br><br>Example: <code>emailer_campaign_id</code>'
limit:
type: integer
description: Maximum number of pivot column values to return.
sorts:
type: array
description: 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.
items:
type: object
required:
- asc
properties:
asc:
type: boolean
description: Sort ascending (<code>true</code>) or descending (<code>false</code>).
metric:
type: object
description: Sort by a metric column. Provide the same structure as a metric entry
in the <code>metrics</code> array.
properties:
value:
type: string
smart_datetime_reference:
type: string
smart_user_id_reference:
type: string
filters:
type: object
description: 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.
properties:
smart_user_id:
type: array
description: 'Filter to specific team member IDs. Use <code>"current"</code> for
the authenticated user. <br><br>Example: <code>["current"]</code>'
items:
type: string
smart_subteam_id:
type: array
description: Filter to specific sub-team IDs.
items:
type: string
emailer_campaign_ids:
type: array
description: Filter to specific sequence IDs.
items:
type: string
contact_stage_ids:
type: array
description: Filter to specific contact stage IDs.
items:
type: string
account_stage_ids:
type: array
description: Filter to specific account stage IDs.
items:
type: string
opportunity_stage_ids:
type: array
description: Filter to specific opportunity stage IDs.
items:
type: string
email_account_ids:
type: array
description: Filter to specific sender mailbox IDs.
items:
type: string
smart_datetime_range:
type: object
description: Required when <code>date_ranges[].modality</code> is <code>custom_range</code>.
Specifies the exact date window as ISO 8601 date strings.
required:
- min
- max
properties:
min:
type: string
description: 'Start date (inclusive). Format: <code>YYYY-MM-DD</code>. <br><br>Example:
<code>2024-01-01</code>'
max:
type: string
description: 'End date (inclusive). Format: <code>YYYY-MM-DD</code>. <br><br>Example:
<code>2024-03-31</code>'
additionalProperties: true
group_by_totals_selected:
type: boolean
description: When <code>true</code>, the response includes an aggregated totals row
in addition to the per-dimension-value rows.
pivot_group_by_totals_selected:
type: boolean
description: When <code>true</code>, the pivot response includes an aggregated totals
column in addition to the per-pivot-value columns.
date_ranges:
type: array
description: '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>.'
items:
type: object
required:
- modality
properties:
modality:
type: string
description: '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>).'
maxItems: 1
skip_group_by_values:
type: array
maxItems: 500
description: 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.
items:
type: string
min_ratio_denominator:
type: integer
default: 0
description: Minimum denominator threshold for ratio metrics. Rows where the denominator
falls below this value are excluded from ratio calculations.
examples:
Flat totals — email performance:
value:
metrics:
- value: num_emails_sent
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
- value: num_emails_opened
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
- value: percent_emails_opened_tracked
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
group_by: []
pivot_group_by: []
sorts: []
filters: {}
group_by_totals_selected: false
pivot_group_by_totals_selected: false
date_ranges:
- modality: last_30_days
Grouped — email activity by user:
value:
metrics:
- value: num_emails_sent
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
- value: num_emails_replied
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
- value: percent_emails_replied
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
group_by:
- name: smart_user_id
pivot_group_by: []
sorts:
- metric:
value: num_emails_sent
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
asc: false
filters: {}
group_by_totals_selected: true
pivot_group_by_totals_selected: false
date_ranges:
- modality: current_month
Grouped — email volume by month:
value:
metrics:
- value: num_emails_sent
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
group_by:
- name: smart_datetime_month
pivot_group_by: []
sorts: []
filters: {}
group_by_totals_selected: false
pivot_group_by_totals_selected: false
date_ranges:
- modality: last_12_months
Pivot — emails sent by user x contact stage:
value:
metrics:
- value: num_emails_sent
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
group_by:
- name: smart_user_id
pivot_group_by:
- name: contact_stage_id
sorts: []
filters: {}
group_by_totals_selected: true
pivot_group_by_totals_selected: true
date_ranges:
- modality: last_30_days
Sorted — top 5 reps by reply rate:
value:
metrics:
- value: num_emails_sent
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
- value: num_emails_replied
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
- value: percent_emails_replied
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
group_by:
- name: smart_user_id
limit: 5
pivot_group_by: []
sorts:
- metric:
value: percent_emails_replied
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
asc: false
filters: {}
group_by_totals_selected: false
pivot_group_by_totals_selected: false
date_ranges:
- modality: current_quarter
Custom date range — call activity for Q1:
value:
metrics:
- value: num_phone_calls
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
- value: num_phone_calls_connect
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
- value: percent_phone_calls_connect
smart_datetime_reference: activity_datetime
smart_user_id_reference: user_id
group_by:
- name: smart_user_id
pivot_group_by: []
sorts: []
filters:
smart_datetime_range:
min: '2024-01-01'
max: '2024-03-31'
group_by_totals_selected: true
pivot_group_by_totals_selected: false
date_ranges:
- modality: custom_range
responses:
'200':
description: '200'
content:
application/json:
schema:
type: object
properties:
response:
type: object
description: The query result. Contains four sub-keys depending on query mode and
flags. See response examples for each shape.
properties:
table_response:
type: object
description: '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>.'
additionalProperties: true
group_by_total_response:
type: object
description: 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>.
additionalProperties: true
pivot_group_by_total_response:
type: object
description: 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>.
additionalProperties: true
incompatible_filters:
type: object
description: 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.
additionalProperties:
type: array
items:
type: string
goals:
type: array
description: Goal attainment data. This field is unrelated to data querying — you
can ignore it.
items:
type: object
examples:
Flat totals — email performance:
value:
response:
table_response:
num_emails_sent: 1240
num_emails_opened: 410
percent_emails_opened_tracked: 0.331
percent_emails_opened_tracked_denominator: 1240
group_by_total_response: {}
pivot_group_by_total_response: {}
incompatible_filters: {}
goals: []
Grouped — email activity by user:
value:
response:
table_response:
smart_user_id:
buckets:
- key: 60a5c0b8e4b0c7001c4f1234
readable_key: Alice Smith
num_emails_sent: 320
num_emails_replied: 48
percent_emails_replied: 0.15
percent_emails_replied_denominator: 320
- key: 60a5c0b8e4b0c7001c4f5678
readable_key: Bob Jones
num_emails_sent: 280
num_emails_replied: 56
percent_emails_replied: 0.2
percent_emails_replied_denominator: 280
group_by_total_response:
smart_user_id:
buckets:
- key: total
readable_key: Total
num_emails_sent: 600
num_emails_replied: 104
percent_emails_replied: 0.173
percent_emails_replied_denominator: 600
pivot_group_by_total_response: {}
incompatible_filters: {}
goals: []
Grouped — email volume by month:
value:
response:
table_response:
smart_datetime_month:
buckets:
- key: '2024-01-01'
readable_key: Jan 2024
num_emails_sent: 840
- key: '2024-02-01'
readable_key: Feb 2024
num_emails_sent: 920
- key: '2024-03-01'
readable_key: Mar 2024
num_emails_sent: 1105
- key: '2024-04-01'
readable_key: Apr 2024
num_emails_sent: 980
group_by_total_response: {}
pivot_group_by_total_response: {}
incompatible_filters: {}
goals: []
Pivot — emails sent by user x contact stage:
value:
response:
table_response:
contact_stage_id:
buckets:
- key: 5f9a1b2c3d4e5f6a7b8c9d0e
readable_key: New
smart_user_id:
buckets:
- key: 60a5c0b8e4b0c7001c4f1234
readable_key: Alice Smith
num_emails_sent: 120
- key: 60a5c0b8e4b0c7001c4f5678
readable_key: Bob Jones
num_emails_sent: 95
- key: 5f9a1b2c3d4e5f6a7b8c9d1f
readable_key: Contacted
smart_user_id:
buckets:
- key: 60a5c0b8e4b0c7001c4f1234
readable_key: Alice Smith
num_emails_sent: 85
- key: 60a5c0b8e4b0c7001c4f5678
readable_key: Bob Jones
num_emails_sent: 110
group_by_total_response: {}
pivot_group_by_total_response: {}
incompatible_filters: {}
goals: []
Sorted — top 5 reps by reply rate:
value:
response:
table_response:
smart_user_id:
buckets:
- key: 60a5c0b8e4b0c7001c4f9abc
readable_key: Carol Lee
num_emails_sent: 215
num_emails_replied: 47
percent_emails_replied: 0.219
percent_emails_replied_denominator: 215
- key: 60a5c0b8e4b0c7001c4f5678
readable_key: Bob Jones
num_emails_sent: 280
num_emails_replied: 56
percent_emails_replied: 0.2
percent_emails_replied_denominator: 280
- key: 60a5c0b8e4b0c7001c4f1234
readable_key: Alice Smith
num_emails_sent: 320
num_emails_replied: 48
percent_emails_replied: 0.15
percent_emails_replied_denominator: 320
group_by_total_response: {}
pivot_group_by_total_response: {}
incompatible_filters: {}
goals: []
Custom date range — call activity for Q1:
value:
response:
table_response:
smart_user_id:
buckets:
- key: 60a5c0b8e4b0c7001c4f1234
readable_key: Alice Smith
num_phone_calls: 185
num_phone_calls_connect: 62
percent_phone_calls_connect: 0.335
percent_phone_calls_connect_denominator: 185
- key: 60a5c0b8e4b0c7001c4f5678
readable_key: Bob Jones
num_phone_calls: 140
num_phone_calls_connect: 53
percent_phone_calls_connect: 0.379
percent_phone_calls_connect_denominator: 140
group_by_total_response:
smart_user_id:
buckets:
- key: total
readable_key: To
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/apollo-io/refs/heads/main/openapi/apollo-io-analytics-api-openapi.yml