Skip to main content
WorkflowsVersion: v3

Get Workflow Log Statistics

GET/workflows/{workflowId}/logs/aggregate

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_to_workflow
  • Completions: removedReasons=end_of_workflow. Divide by enrollments for a completion rate
  • Failures per step: statuses=error,failed,failed_retry_limit_reached&groupBy=stepId
  • Why contacts left: types=remove_from_workflow&groupBy=removedReason
  • Stopped because the contact replied: removedReasons=contact_reply_stop_response
  • Goal reached: types=workflow_goal&statuses=success
  • Enrollment trend: statuses=added_to_workflow&groupBy=week (or day)
  • Change over time: call twice with back-to-back windows of equal length and compare

Completions in a window can include contacts who enrolled before it, so a completion rate can exceed 100%. With fewer than about 30 enrollments, rates swing widely. Zero is a real answer. A workflowId that does not exist in the sub-account returns 404.

Limits. The range defaults to the last 30 days and must not exceed 30 days. Logs are available for the last 60 days. A grouping that produces more rows than limit is refused with 422 rather than truncated, because a truncated count reports wrong totals.

Compatibility. New optional fields and new values of status, type and removedReason can appear at any time. Ignore fields you do not know, and treat an unknown value as other.

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your access token.

Scope:workflows.logs
Auth methods:OAuthPrivate Integration
Token type:Sub-Account Token

Request​

Headers

Versionstringrequired

API Version. Send v3.

Available optionsv3
Example:v3

Path Parameters

workflowIdstringrequired

Workflow ID. Get it from Search Workflows. Never pass a workflow name

Example:a7321e66-8b68-4c10-afc7-4cc9744f17af

Query Parameters

locationIdstringrequired

Sub-account (location) ID. It must be the sub-account the token belongs to, otherwise the request is refused with 403

Example:ve9EPM428h8vShlRW1KT
startDatestring

Start 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

Example:2026-06-01
endDatestring

End of the range, ISO 8601. A plain date includes the whole day. At most 30 days after startDate. Defaults to now

Example:2026-06-30
groupBystring[]

Dimensions 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

Available optionsstatustypestepIdremovedReasonweekdayhour
Example:["type","status"]
statusesstring[]

Count 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

Example:["error","failed"]
typesstring[]

Count 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

Example:["email"]
removedReasonsstring[]

Count 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

Example:["end_of_workflow"]
timezonestring

IANA timezone for the week, day and hour buckets. It does not move startDate and endDate, which stay UTC. Defaults to UTC

Example:America/New_York
limitnumber

Maximum number of grouped rows. A grouping that produces more is refused with 422 rather than truncated. Default 1000, maximum 5000

Example:1000

Response

application/json

Successful response

countnumberrequired

Number of rows in this response

Example:3
statisticsobject[]required

The grouped counts