Get Workflow Rule Usage Report
Purpose
To retrieve the usage report of a specific Workflow Rule in your Zoho CRM organization. It provides a count of how many times the workflow was triggered and the success or failure metrics for each associated action within a specified date range.
Endpoints
- GET /settings/automation/workflow_rules/{workflow_rule_ID}/actions/usage?executed_from={from_date}&executed_till={to_date}
Request Details
Request URL
{api-domain}/crm/{version}/settings/automation/workflow_rules/{workflow_rule_ID}/actions/usage
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Scope
ZohoCRM.settings.workflow_rules.ALL
(or)
ZohoCRM.settings.workflow_rules.READ
Parameters
- executed_fromstring, mandatory
The start date for fetching usage data in ISO 8601 format (yyyy-mm-dd).
- executed_tillstring, mandatory
The end date for fetching usage data in ISO 8601 format (yyyy-mm-dd).
Note:
The executed_from and executed_till parameters support a maximum range of 90 days from the current date. Requests with a wider range will return a INVALID_REQUEST error.
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v8/settings/automation/workflow_rules/4876876000011230001/actions/usage?executed_from=2025-06-01&executed_till=2025-08-01"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-X GETNote:
- The trigger_count value is available only for the following triggers: Create, Edit, Create or Edit, and Delete. For all other triggers, the value of this field will be a - (hyphen).
- The related_details key is specific to email_notifications actions where bulk_mail is false. When bulk_mail is true, only success_count and failure_count will be returned in the response.
- The email notification count and report apply only to emails sent to email fields in the record, excluding the Owner field. Emails sent to internal users or additional recipients are not included in the count.
- Changing the condition type (for example, from Create to Edit or Delete) resets the report. Data will be recomputed from the last modified date.
- Editing a condition resets the record count for the entire report. For actions, the count starts from when the action was associated with the workflow.
- queue_count is available for Email notifications, Functions, Webhooks, and Tasks.
Response JSON
- trigger_countinteger
The total number of times the workflow rule was triggered in the specified date range.
- namestring
Name of the Workflow rule.
- idstring
The unique ID of the workflow rule.
- conditionsJSON array
The set of condition blocks defined in the workflow rule, each with its own usage statistics.
- instant_actionsJSON object
Includes details of the actions that were executed immediately when the workflow rule was triggered.
- actionsJSON array
Includes usage details of the individual actions.
- queue_countinteger
Represents the number of action instances currently waiting in the execution queue. This is applicable only for asynchronous actions like Tasks, Emails, Webhooks, and Functions.
- namestring
Represents the name of the specific action.
- success_countinteger
Indicates the total number of successful executions for this action.
- failure_countinteger
Indicates the total number of execution failures for this action.
- idstring
The unique ID of the specific action.
- typestring
Specifies the category of the action, such as schedule_call, task, email, webhook, functions, etc.
- associated_timestring
Represents the ISO 8601 formatted timestamp of the time the action was associated with the workflow rule.
- related_detailsJSON object
Provides email delivery metrics for email_notifications actions. This object is specific to email notification actions, and only when the emails are not sent as a single mass email.
- bulk_mailBoolean
Indicates whether the email was sent as a bulk email.
- unopenedinteger
Shows the count of emails sent but not opened by recipients.
- openedinteger
Shows the count of emails that recipients opened.
- deliveredinteger
Indicates the number of successfully delivered emails.
- unsentinteger
The number of emails that could not be sent.
- bouncedinteger
Specifies the number of emails that bounced during delivery.
- clickedinteger
Represents the number of times recipients clicked links in the email.
- sentinteger
The total number of emails sent.
- tag_idstring
Unique identifier of the tag. This key is specific to add_tags and remove_tags action types.
- scheduled_actionsJSON object
Contains scheduled action groups configured for the workflow rule. Each group has a unique ID and contains actions with the same structure as instant_actions.
- idstring
Provides the unique ID of the scheduled action group. Each scheduled action group may contain multiple actions configured to execute at a specific time or delay.
- usage_countinteger
Represents the number of times this specific condition satisfied its criteria, triggering its associated actions.
- idstring
Represents the unique ID of the specific condition within the workflow rule.
- reset_timestring
Indicates the date and time when the usage statistics for this workflow rule were last reset. If the usage data has never been reset, the value will be null.
Possible Errors
- INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: This API supports only the GET method. Retry the request using the GET method. - REQUIRED_PARAM_MISSINGHTTP 400
A required parameter is missing in the request.
Resolution: The details object in the response contains information about the missing parameter. Ensure all required and dependent parameters are included. Refer to the Parameters section for details. - INVALID_DATAHTTP 400
You have specified the parameters in a wrong format.
Resolution: Specify the execute_from and execute_till parameter values in ISO Time format. - OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: Client does not have the required OAUTH SCOPE. Create a new token with valid scope. Refer to the Scope section for more details. - INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to request URL section for more details. - INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in Server. Contact support team.
Sample Response
Copied{
"workflow_rules": [
{
"trigger_count": 3,
"name": "High Value Lead Rule",
"id": "4876876000013248001",
"conditions": [
{
"instant_actions": {
"actions": [
{
"queue_count": 0,
"related_details": {
"bulk_mail": false,
"unopened": 0,
"sent_percentage": 100,
"opened": 1,
"delivered": 1,
"unsent": 0,
"bounced": 0,
"clicked": 0,
"sent": 1
},
"name": "High revenue Lead added",
"success_count": 1,
"failure_count": 0,
"id": "4876876000016390103",
"type": "email_notifications",
"associated_time": "2025-10-16T16:19:58+05:30"
},
{
"name": "To users : Patricia Boyle",
"success_count": 2,
"failure_count": 0,
"id": "4876876000013248016",
"type": "assign_owner",
"associated_time": "2025-08-08T22:40:00+05:30"
}
]
},
"scheduled_actions": [
{
"id": "4876876000016390118",
"actions": [
{
"queue_count": 0,
"related_details": {
"bulk_mail": false,
"unopened": 0,
"sent_percentage": 100,
"opened": 1,
"delivered": 1,
"unsent": 0,
"bounced": 0,
"clicked": 0,
"sent": 1
},
"name": "High revenue Lead added",
"success_count": 1,
"failure_count": 0,
"id": "4876876000016390103",
"type": "email_notifications",
"associated_time": "2025-10-16T16:19:58+05:30"
}
]
}
],
"usage_count": 2,
"id": "4876876000013248002"
},
{
"instant_actions": {
"actions": [
{
"name": "P1",
"success_count": 0,
"tag_id": "4876876000011037076",
"failure_count": 0,
"id": "4876876000013248015",
"type": "add_tags",
"associated_time": "2025-08-08T22:40:00+05:30"
}
]
},
"scheduled_actions": [],
"usage_count": 0,
"id": "4876876000013248004"
}
],
"reset_time": "2025-10-16T16:23:04+05:30"
}
]
}