Retrieves tasks from a workspace grouped and aggregated by a specified attribute such as priority, status, assignee, creator, or custom property, enabling statistical analysis and categorized reporting of task data. This endpoint returns grouped results with counts, optional aggregations (min/max/sum of dates or numeric fields), and cursor-based pagination for efficient data retrieval. Use this to generate task distribution reports, analyze workload by assignee, track status breakdowns, calculate date-based metrics, or visualize task categorization by custom properties. The response includes group metadata, item counts per group, aggregated values, and supports extensive filtering by dates, assignees, priorities, programs, custom properties, and search keywords to narrow analysis scope.
Key Features:
-
Groups tasks by standard fields (priority, status, assigneeId, creatorId) or any custom property for flexible categorization
-
Returns counts of tasks in each group enabling quick distribution analysis and reporting dashboards
-
Supports aggregations parameter for computing min/max/sum/count on date fields (createdAt, updatedAt, plannedStartDate, plannedEndDate) per group
-
Combines grouping with powerful filtering (date ranges, assignees, priorities, programs, status, custom properties, title search) to analyze specific task subsets
-
Uses cursor-based pagination for efficient retrieval of large grouped datasets without performance degradation
-
Enables drill-down analysis by filtering grouped results to specific criteria and time windows
Authorization Logic:
-
User must have view or manage permissions for the specified space (seismic.programs.view or seismic.programs.manage)
-
Only tasks visible to the authenticated user based on space access and task permissions are included in grouping
-
Returns 403 if user lacks required view permissions for the space
-
Returns 404 if space does not exist or user has no access
Usage Examples:
Example 1: Group tasks by priority to analyze workload distribution
Call GET /v2/spaces/w5PmrE9p0kicqqRSVJ3VBQ/tasks/groupby?groupBy=priority&limit=50 to retrieve task counts grouped by priority levels (critical, high, medium, low, noPriority). Response shows how many tasks fall into each priority category enabling workload prioritization.
Example 2: Group by assignee with date aggregations to track team capacity
Call GET /v2/spaces/w5PmrE9p0kicqqRSVJ3VBQ/tasks/groupby?groupBy=assigneeId&aggregations=plannedEndDate:min&aggregations=plannedEndDate:max&limit=50 to see task counts per assignee along with earliest and latest due dates. Use this to identify overloaded team members and upcoming deadline pressures.
Example 3: Group by custom property for categorical analysis
Call GET /v2/spaces/w5PmrE9p0kicqqRSVJ3VBQ/tasks/groupby?groupByCustomPropertyId=FTFcbnlcfkKZCmnew-bGxw&limit=50 to group tasks by a custom property like Department or Program Phase. Combine with filters to analyze specific segments.
Example 4: Filtered grouping by status for Q1 tasks only
Call GET /v2/spaces/w5PmrE9p0kicqqRSVJ3VBQ/tasks/groupby?groupBy=status&plannedEndDateFrom=2025-01-01T00:00:00Z&plannedEndDateTo=2025-04-01T00:00:00Z to see status distribution (In Progress, Complete, etc.) for Q1 tasks only.