Metrics and Dimensions Reference

This page lists the built-in metrics and group_by dimensions supported by the
Query Analytics Report endpoint. New metrics and dimensions are added over time — if you don't see a metric here, check the Apollo Analytics UI to confirm availability.

Important: Smart reference fields

Every metric object requires two fields beyond value that control which date and user fields the analytics engine uses when applying filters for that metric:

• smart_datetime_reference: Which date field to use for the date range filter
• smart_user_id_reference: Which user field to use for the team member filter

The tables on this page show the valid date and user field for each metric. Using the wrong value may return no data or unexpected results for that metric. The API does not validate reference field values against the metric type.

display_name is metadata only

You may include a display_name field on any metric object in the request. This is a UI label override and has no effect on the API response — bucket keys in the response always use the original metric value string (e.g. num_emails_sent), regardless of display_name.

Smart Reference Field Values

⚠️

Important

smart_datetime_range or smart_user_id are filter/grouping keys, not valid reference fields. These values are metric-specific. Use the smart_datetime_reference and smart_user_id_reference values listed under the table for the metric family you're reporting on.

smart_datetime_reference

smart_user_id_reference

Metrics

⚠️

Important

All metrics with names beginning with percent_ (e.g. percent_emails_replied, percent_phone_calls_connect, percent_win_rate) return decimal values between 0 and 1. They are not percentages. For example, 0.331 means 33.1%. Multiply by 100 to convert to a percentage for display.

Email metrics

Phone metrics

Meeting metrics

Task metrics

Contact metrics

Note: num_net_new_people does not use date or user reference fields — any values you pass for smart_datetime_reference and smart_user_id_reference are ignored. You must still include both keys in each metric object, as the API rejects a metric that is missing either key.

Account metrics

Note: num_net_new_companies does not use date or user reference fields — any values you pass for smart_datetime_reference and smart_user_id_reference are ignored. You must still include both keys in each metric object, as the API rejects a metric that is missing either key.

Opportunity metrics

Conversation Intelligence metrics

⚠️

Feature Required

These metrics require the Conversation Intelligence feature to be enabled on your Apollo plan and active call recording to be in use. Queries return no data if the feature is not active.

Custom metrics

You can query custom metrics defined by your team using the format custom_metric_{id}, where
{id} is the custom metric's id (e.g. custom_metric_507f1f77bcf86cd799439011).

Custom metric data is team-scoped; the API key you use must belong to the same Apollo team that
owns the custom metric. Group_by dimensions and filters must be compatible with the custom metric's
underlying metric type (same compatibility rules as the equivalent built-in metric).

Do not include the custom_metric_ prefix in the id portion. Use the full string including the prefix as the value:

{
  "value": "custom_metric_507f1f77bcf86cd799439011",
  "smart_datetime_reference": "smart_datetime_range",
  "smart_user_id_reference": "smart_user_id"
}

Group_by Dimensions

The following values are valid for group_by[].name and pivot_group_by[].name.

Note: Only one entry is supported in group_by and one in pivot_group_by per request.
group_by defines the row dimension; pivot_group_by defines the column dimension for pivot queries.

Pivot response structure: In pivot queries, table_response is keyed by the pivot_group_by dimension (columns), with the group_by dimension (rows) nested inside each column bucket. This is the inverse of the conceptual row/column model; iterate the outer buckets array to get columns, then each column's inner buckets array to get row values for that column.

Tip: Not all dimensions are compatible with all metrics. Build a report in
Apollo Analytics to verify which dimensions
are available for your chosen metrics before querying the API.

Time dimensions

Smart datetime dimensions: All smart_datetime_* dimensions automatically resolve to the correct underlying date field for each metric type. For absolute time series (one bucket per period), use smart_datetime_hour, smart_datetime_day, smart_datetime_week, smart_datetime_month, or smart_datetime_year. For recurring patterns aggregated across the range (e.g. "how does Monday compare to Friday?"), use smart_datetime_hour_of_day, smart_datetime_day_of_week, or smart_datetime_month_of_year.

Note: smart_datetime_quarter is not supported — it returns raw epoch timestamps instead of human-readable values.

User and team dimensions

Account dimensions

Contact dimensions

Email and sequence dimensions

Phone dimensions

Opportunity dimensions

Task dimensions

Conversation Intelligence dimensions

Calendar dimensions

Filters

Filters are passed as a flat key/value object. Most filter values are arrays of IDs for the
corresponding entity, or the special string "current" where noted.

Tip: The easiest way to discover filter IDs for your account is to open
Apollo Analytics → Start from scratch,
configure a report with the filters you want, then inspect the outgoing sync_report
network request in your browser's DevTools — the filters object in that payload contains
the exact IDs to use.

Custom date range filter

When you set date_ranges[0].modality to custom_range, you must also include a
smart_datetime_range filter that specifies the exact dates:

{
  "date_ranges": [
    { "modality": "custom_range" }
  ],
  "filters": {
    "smart_datetime_range": {
      "min": "2024-01-01",
      "max": "2024-03-31"
    }
  }
}

Totals Rows and Columns

Two boolean request fields control whether aggregated totals are appended to the response alongside per-dimension-value rows:

Both fields default to false and can be set independently.

Date Range Presets

Use one of the following values for date_ranges[].modality: