Skip to main content
Glama
Sign In
zackscriven

ghl-mcp-server-v2

by zackscriven
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

ghl_workflow_get_log_statistics

Read-onlyIdempotent

Count workflow log records grouped by status, step, type, removal reason, or time to reveal enrollments, completions, failures, and trends.

Instructions

WORKFLOW API — limited availability: enabled for selected sub-accounts only; others get 403 WORKFLOW_API_NOT_ENABLED_FOR_LOCATION (not a token or scope problem). Suggested order: get step types -> build the definition -> validate (validate_workflow_definition, read-only) -> create (always lands in draft) -> publish via update status. Rate limits: integration daily quota + 10s burst (X-RateLimit-* headers) AND a per-sub-account budget per 10s window with reads and writes counted separately; no Retry-After is sent. Logs: default and max range 30 days; retained 60 days. Get Workflow Log Statistics Limited availability. The workflow API is currently enabled for selected sub-accounts only; any other sub-account receives 403 WORKFLOW_API_NOT_ENABLED_FOR_LOCATION.

Count the log records of one workflow, grouped by one or more dimensions. It answers how many: enrollments, completions, failures per step, why contacts left, and trends over time. To answer who, use Get Workflow Logs.

Before you call it. Get workflowId from Search Workflows. Never pass a workflow name.

Grouping. Each row holds one value for every dimension in groupBy, plus count. Grouping by week, day or hour adds bucket, the start of each interval in timezone. startDate and endDate always stay UTC. Rows are sorted by the grouped values in ascending order (status, then type, stepId, removedReason and bucket), not by count.

Finding filter values. Group by a dimension to see which values this workflow has, then filter on them. For example, groupBy=removedReason lists the reasons present, and those values work in removedReasons.

Steps. Rows grouped by stepId also carry stepName, the name of that step on its most recent log record in the date range. stepId matches actions[].id in Get Workflow Definition. A step count includes the remove_from_workflow record written when a contact leaves the workflow at that step, so group by stepId and type together to count how often the step itself ran.

Common questions.

  • Enrollments: `statuses=added_ Endpoint: GET /workflows/{workflowId}/logs/aggregate (Version header: v3; source: v3/workflows-v3.json) OAuth scopes: workflows.logs Pagination params: limit — pass them to page through full result sets.

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum number of grouped rows. A grouping that produces more is refused with 422 rather than truncated. Default 1000, maximum 5000
typesNoCount only these step types: a step `type` key, as listed by Get Step Types or in `actions[].type` of Get Workflow Definition. Unlike Get Workflow Logs, `if_else` and `drip` match only those exact keys here. New values can appear. Group by `type` first to see the types this workflow has
endDateNoEnd of the range, ISO 8601. A plain date includes the whole day. At most 30 days after startDate. Defaults to now
groupByNoDimensions to group the counts by. Repeat the parameter or send a comma-separated list. `status` is the step outcome, `type` the step type, `stepId` the step, `removedReason` why the contact left the workflow, and `week`, `day` or `hour` a time bucket (one at most). Defaults to `status`
statusesNoCount only these step outcomes. Values: `added_to_workflow` (the contact entered the workflow), `success` (the step ran), `error` and `failed` (the step did not complete), `failed_retry_limit_reached` (the step gave up after its retries), `retry` (the step will run again), `skipped` (the step did not run, for example because of DND, a time window or missing data), `waiting` (the contact is waiting at the step), `wait_finished` (a wait ended), `finished` (the contact left the workflow, see removedReason), `paused_due_to_draft_mode` (the workflow was unpublished while the contact was in it), `contact_merged` (the contact was merged into another contact), `drip_queued` (the contact is waiting in a drip step for its batch), `drip_resume` (the batch was released and the contact moved on), `processing` (the step has started and has not finished yet), and `winner_declared` (an A/B test step picked its winning path; the record has no contact). New values can appear. Group by `status` first to see the values this workflow has
timezoneNoIANA timezone for the week, day and hour buckets. It does not move startDate and endDate, which stay UTC. Defaults to UTC
startDateNoStart of the range, ISO 8601: a plain date (start of that day, UTC) or a full timestamp. Send it together with endDate. Defaults to 30 days ago. Logs are available for the last 60 days, so it cannot be earlier than that
locationIdYesSub-account (location) ID. It must be the sub-account the token belongs to, otherwise the request is refused with 403
workflowIdYesWorkflow ID. Get it from Search Workflows. Never pass a workflow name
removedReasonsNoCount only records removed for these reasons. Values: `end_of_workflow` (the contact reached the end), `contact_deleted` (the contact was deleted), `deleted_workflow` (the workflow was deleted), `record_deleted` (the record was deleted), `goal_action` (a goal step removed the contact), `contact_reply_stop_response` (the contact replied and the workflow stops on reply), `contact_merge` (the contact was merged), `appointment-change`, `invoice-change` and `service-booking-change` (the appointment, invoice or booking changed and the workflow restarted for the contact), `attendee-change` (the Events attendee or their event changed, and the run for that attendee ended), `rental-booking-change` (the rental booking that started the workflow was deleted or cancelled), `wait_step_window_in_past` (a wait step time window pointed to a time in the past, so the contact left), and `missing-data` (the step the contact was on was deleted from the workflow). Values are exact, including the ones with hyphens. New values can appear. Group by `removedReason` first to see the values this workflow has

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv2.1.0

TDQS

A4.7/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint, but the description adds substantial operational context: the 403 WORKFLOW_API_NOT_ENABLED_FOR_LOCATION limitation, daily plus 10-second burst rate limits, per-sub-account budget, absence of Retry-After, 30-day default/max query range, 60-day retention, and 422 refusal instead of truncation. It also discloses sorting behavior and timezone handling for time buckets.

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

Conciseness3/5

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

The actual purpose appears only after a long preamble about workflow API availability, call order, and rate limits, and the limited-availability warning is repeated again immediately after the title. There is also a visibly truncated fragment ('Enrollments: `statuses=added_'), which adds noise despite the otherwise useful section headings.

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

Completeness5/5

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

For a complex aggregation tool with 10 parameters and no output schema, the description covers the necessary context: scope, prerequisites, filter discovery, grouping behavior, row shape, pagination refusal semantics, date retention limits, rate limits, and the limited-availability 403 condition.

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

Parameters4/5

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

Schema coverage is 100%, so the schema already documents each parameter in detail and sets a baseline of 3. The description adds meaningful semantics beyond the schema: rows contain one value per groupBy dimension plus count, time groupings add bucket, rows are sorted by grouped values rather than count, stepId rows carry stepName and match actions[].id, and step counts include remove_from_workflow records.

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

Purpose5/5

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

It states a specific verb and resource: 'Count the log records of one workflow, grouped by one or more dimensions.' It also explains the questions it answers (how many enrollments, completions, failures, why contacts left, trends) and explicitly distinguishes itself from Get Workflow Logs, which answers 'who.'

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

Usage Guidelines5/5

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

The description names the alternative server tool and the condition that selects it: 'To answer who, use Get Workflow Logs.' It also gives a workflow API call order, says to get workflowId from Search Workflows rather than using a workflow name, and explains how to discover filter values by grouping before filtering.

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

Deploy Server

Other Tools