AIsa Sales

Query Analytics Report

post_apollo_reports_sync_report

Read-onlyIdempotent

Query analytics report. Requires a master API key.

Published reference price: $0.012 USD per successful request. Account-specific pricing and final settlement may differ.

Input Schema

Name	Required	Description	Default
`body`	Yes

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed9 schema fields changedOct 19, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / body

Added value: +{
+  "properties": {
+    "date_ranges": {
+      "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": {
+        "properties": {
+          "modality": {
+            "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>).",
+            "type": "string"
+          }
+        },
+        "required": [
+          "modality"
+        ],
+        "type": "object"
+      },
+      "maxItems": 1,
+      "type": "array"
+    },
+    "filters": {
+      "additionalProperties": true,
+      "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": {
+        "account_stage_ids": {
+          "description": "Filter to specific account stage IDs.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "contact_stage_ids": {
+          "description": "Filter to specific contact stage IDs.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "email_account_ids": {
+          "description": "Filter to specific sender mailbox IDs.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "emailer_campaign_ids": {
+          "description": "Filter to specific sequence IDs.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "opportunity_stage_ids": {
+          "description": "Filter to specific opportunity stage IDs.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "smart_datetime_range": {
+          "description": "Required when <code>date_ranges[].modality</code> is <code>custom_range</code>. Specifies the exact date window as ISO 8601 date strings.",
+          "properties": {
+            "max": {
+              "description": "End date (inclusive). Format: <code>YYYY-MM-DD</code>. <br><br>Example: <code>2024-03-31</code>",
+              "type": "string"
+            },
+            "min": {
+              "description": "Start date (inclusive). Format: <code>YYYY-MM-DD</code>. <br><br>Example: <code>2024-01-01</code>",
+              "type": "string"
+            }
+          },
+          "required": [
+            "min",
+            "max"
+          ],
+          "type": "object"
+        },
+        "smart_subteam_id": {
+          "description": "Filter to specific sub-team IDs.",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "smart_user_id": {
+          "description": "Filter to specific team member IDs. Use <code>\"current\"</code> for the authenticated user. <br><br>Example: <code>[\"current\"]</code>",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        }
+      },
+      "type": "object"
+    },
+    "group_by": {
+      "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": {
+        "properties": {
+          "limit": {
+            "description": "Maximum number of dimension values to return.",
+            "type": "integer"
+          },
+          "name": {
+            "description": "The dimension name. <br><br>Example: <code>smart_user_id</code>",
+            "type": "string"
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "type": "object"
+      },
+      "maxItems": 1,
+      "type": "array"
+    },
+    "group_by_totals_selected": {
+      "description": "When <code>true</code>, the response includes an aggregated totals row in addition to the per-dimension-value rows.",
+      "type": "boolean"
+    },
+    "metrics": {
+      "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": {
+        "properties": {
+          "display_name": {
+            "description": "Optional label override for this metric's column in the response.",
+            "type": "string"
+          },
+          "smart_datetime_reference": {
+            "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>",
+            "type": "string"
+          },
+          "smart_user_id_reference": {
+            "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>",
+            "type": "string"
+          },
+          "value": {
+            "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.",
+            "type": "string"
+          }
+        },
+        "required": [
+          "value",
+          "smart_datetime_reference",
+          "smart_user_id_reference"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "min_ratio_denominator": {
+      "default": 0,
+      "description": "Minimum denominator threshold for ratio metrics. Rows where the denominator falls below this value are excluded from ratio calculations.",
+      "type": "integer"
+    },
+    "pivot_group_by": {
+      "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": {
+        "properties": {
+          "limit": {
+            "description": "Maximum number of pivot column values to return.",
+            "type": "integer"
+          },
+          "name": {
+            "description": "The dimension name to pivot on. <br><br>Example: <code>emailer_campaign_id</code>",
+            "type": "string"
+          }
+        },
+        "required": [
+          "name"
+        ],
+        "type": "object"
+      },
+      "maxItems": 1,
+      "type": "array"
+    },
+    "pivot_group_by_totals_selected": {
+      "description": "When <code>true</code>, the pivot response includes an aggregated totals column in addition to the per-pivot-value columns.",
+      "type": "boolean"
+    },
+    "skip_group_by_values": {
+      "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"
+      },
+      "maxItems": 500,
+      "type": "array"
+    },
+    "sorts": {
+      "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": {
+        "properties": {
+          "asc": {
+            "description": "Sort ascending (<code>true</code>) or descending (<code>false</code>).",
+            "type": "boolean"
+          },
+          "metric": {
+            "description": "Sort by a metric column. Provide the same structure as a metric entry in the <code>metrics</code> array.",
+            "properties": {
+              "smart_datetime_reference": {
+                "type": "string"
+              },
+              "smart_user_id_reference": {
+                "type": "string"
+              },
+              "value": {
+                "type": "string"
+              }
+            },
+            "type": "object"
+          }
+        },
+        "required": [
+          "asc"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "metrics",
+    "group_by",
+    "sorts",
+    "filters",
+    "group_by_totals_selected",
+    "pivot_group_by_totals_selected",
+    "date_ranges"
+  ],
+  "type": "object"
+}

removedInput schema / properties / date_range

Removed value: -{
-  "description": "Date range filter (when supported).",
-  "type": "object"
-}

removedInput schema / properties / filters

Removed value: -{
-  "description": "Filter specs.",
-  "type": "string"
-}

removedInput schema / properties / group_by

Removed value: -{
-  "description": "Dimensions to group by.",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

removedInput schema / properties / metrics

Removed value: -{
-  "description": "Metrics to compute.",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

removedInput schema / properties / pivot_group_by

Removed value: -{
-  "description": "Optional pivot dimensions.",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

removedInput schema / properties / sorts

Removed value: -{
-  "description": "Sort specs.",
-  "items": {
-    "type": "string"
-  },
-  "type": "array"
-}

changedInput schema / required

Previous value: -[]New value: +[
+  "body"
+]

First observedSep 15, 2026

TDQS

C2.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds one genuinely useful fact not present in structured data — the master API key requirement — plus pricing, but says nothing about result volume, limits, or rate behavior beyond that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the action and followed by the auth requirement; nothing is wasted. The boilerplate pricing block is injected rather than authored, but it is clearly delimited.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a high-complexity tool with a deeply nested required body and a documented output schema, yet the description never mentions the reference-document dependency for valid metric/dimension names, the one-entry limits on group_by/date_ranges, or the custom_range interaction with filters. An agent would have to reverse-engineer all of that from the schema alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single top-level parameter (body) carries no description, but the nested schema is unusually thorough, documenting metrics, filters, group_by, pivot_group_by, date_ranges, sorts and their constraints. The description adds nothing about any parameter, so it neither compensates for the coverage gap nor contributes value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description says it queries an analytics report, which is a recognizable verb+resource, but it is essentially a restatement of the title and adds no scope detail (e.g. what kind of report, sync vs async). It does not distinguish this tool from siblings such as post_apollo_usage_stats_api_usage_stats or the various search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Requires a master API key" is a prerequisite, not usage guidance. There is no statement of when to use this tool versus the other reporting/search endpoints, and no exclusions or alternatives are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All AIsa Sales tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?