GuidesAPI DocsChangelogMy AppsSeismic Exchange
API Docs

Group tasks by specified attributes

get
https://api.seismic.com/programs/v2/spaces//tasks/groupby

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.

Path Params
string
required
length between 7 and 22

The unique identifier of the space containing the target entity. This determines the scope of entity queries and ensures proper access control. The space must be accessible to the authenticated user with appropriate permissions. It can be the unique identifier (GUID) of the space or the word "default" to indicate the default programs space. Common values include "default" and "rkr83lapKkyCJuLLWqLqzB".

Query Params
date-time

filter by task "plannedEndDate/DueDate" (inclusive)

date-time

filter by task "plannedEndDate/DueDate" (exclusive)

date-time

filter by task "plannedStartDate/StartDate" (inclusive)

date-time

filter by task "plannedStartDate/StartDate" (exclusive)

date-time

filter by task "createdAt" (inclusive)

date-time

filter by task "createdAt" (exclusive)

date-time

filter by task "updatedAt" (inclusive)

date-time

filter by task "updatedAt" (exclusive)

assigneeIds
array of strings

A list of assignees' user Ids to filter by

assigneeIds
priorities
array of strings

A list of priority values, Available values : critical, high, medium, low

priorities
assignerIds
array of strings

A list of assigners' user Ids to filter by.

assignerIds
stepIds
array of int32s

A list of step IDs to filter by.

stepIds
string

statusSchema ID to filter by

string

A token used to guide the next page window

int32

Number of items to return per page, default: 50

programIds
array of strings

Filter by program IDs

programIds
boolean

whether the task is associated with a program

followerIds
array of strings

A list of followers' user id

followerIds
associatedNodeIds
array of strings

A list of Associated node ids to filter by

associatedNodeIds
string

The custom property to group by

string
enum

Field to group by. Allowed values are priority, status, assigneeId, and creatorId.

Allowed:
aggregations
array of strings

Aggregations to apply to each group

aggregations
customProperties
object

Filter by custom properties using property ID and value criteria.

Filter Syntax:

  • customProperties[{propertyId}][operator]={operator} - Comparison operator (Equal, Contains, etc.)
  • customProperties[{propertyId}][id]=%22{valueId}%22 - Filter by value ID (URL-encoded with %22)
  • customProperties[{propertyId}][value]=%22{value}%22 - Filter by value directly (URL-encoded with %22)

Example: Filter tasks by custom property:

customProperties[FTFcbnlcfkKZCmnew-bGxw][operator]=Equal&customProperties[FTFcbnlcfkKZCmnew-bGxw][id]=%22DJF4u1C75kiTpwFV350Frg%22
string

Keyword values to search for on task titles

creatorIds
array of strings

A list of creating user IDs to filter by.

creatorIds
Responses

Updated 1 day ago

Language
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 1 day ago