GuidesAPI DocsChangelogMy AppsSeismic Exchange
API Docs

Group programs by specified attributes

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

Groups programs by various attributes (manager, creator, custom properties, program type, etc.) and applies
aggregations to calculate metrics for each group. This endpoint is useful for analytics, reporting, and
understanding program distribution across different dimensions.

Key Features:

  • Groups programs by multiple attributes including managers, creators, audiences, topics, and program types
  • Supports custom property grouping for flexible categorization
  • Applies aggregations (min, max, count, sum) to calculate metrics per group
  • Enables advanced filtering before grouping for targeted analysis
  • Returns paginated results with cursor support for large datasets

Authorization Logic:

  1. User must have a valid JWT token with viewing or management scopes
  2. Valid token is required for querying
  3. Programs are filtered based on user's access permissions before grouping

Usage Example:

Group programs by manager to see workload distribution, or group by program type to analyze portfolio composition
and resource allocation across different initiative types.

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

Optional filter from planned end date (inclusive) applied before grouping.

date-time

Optional filter to planned end date (exclusive) applied before grouping.

date-time

Optional filter from planned start date (inclusive) applied before grouping.

date-time

Optional filter to planned start date (exclusive) applied before grouping.

managerIds
array of strings

Optional array of manager user IDs to filter by before grouping.

managerIds
creatorIds
array of strings

Optional array of creator user IDs to filter by before grouping.

creatorIds
string

Optional cursor for pagination of grouped results.

int32

Optional number of groups to return per page. Defaults to 50.

followerIds
array of strings

Optional array of follower user IDs to filter by before grouping.

followerIds
associatedNodeIds
array of strings

Optional array of associated node IDs to filter programs by their associations (tasks, content, or requests) before grouping.

associatedNodeIds
string

Optional custom property ID to group programs by custom property values.

string
enum

Required field to group by. Available values: creatorId, managerId, audience, pages, trackers, topics,
programType, programTypes, onboardingGroup, outcomeKpiFirst, outcomeKpiSecond, outcomeKpiThird.

aggregations
array of strings

Optional aggregations to apply to each group (e.g., count, sum, min, max on specific fields).

aggregations
customProperties
object

Optional dictionary of custom property filters applied before grouping. Filter by custom property ID and value.

Filter Syntax:

  • customProperties[{propertyId}][operator]={operator} - Comparison operator
  • 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: customProperties[FTFcbnlcfkKZCmnew-bGxw][operator]=Equal&customProperties[FTFcbnlcfkKZCmnew-bGxw][id]=%22DJF4u1C75kiTpwFV350Frg%22

string

Optional keyword to search within program titles before grouping.

boolean

Boolean filter to include only archived programs (true), only active non-archived programs (false), or all programs regardless of archive status (omit parameter). Archived programs are those that have been moved to historical storage and are typically read-only. Use true to retrieve historical programs for reporting or audit purposes, false to show only currently active programs in operational use, or omit to see all programs. Defaults to including non-archived programs when not specified. This filter affects the result set before grouping occurs.

string
enum

[DEPRECATED] ProgramType enum to filter by. This parameter is deprecated. Use programTypes instead.

Allowed:
string
enum

Optional filter for the primary success metric assigned to programs, restricting results to programs tracking the specified outcome KPI as their first metric. Valid values include WinRate (percentage of won opportunities), WonOpportunities (count of closed-won deals), InfluencedRevenue (revenue attributed to program), FirstDealAverageCloseTime, SecondDealAverageCloseTime, ThirdDealAverageCloseTime (sales cycle metrics), and InfluencedActiveOpportunities (open pipeline opportunities). When combined with outcomeKpiSecond and outcomeKpiThird, acts as an AND filter—programs must match all specified metrics. Useful for filtering programs by their primary success measurement approach. Omit to include programs regardless of first KPI configuration.

Allowed:
string
enum

Optional filter for the secondary success metric assigned to programs, restricting results to programs tracking the specified outcome KPI as their second metric. Valid values include WinRate, WonOpportunities, InfluencedRevenue, FirstDealAverageCloseTime, SecondDealAverageCloseTime, ThirdDealAverageCloseTime, and InfluencedActiveOpportunities. Programs often track multiple KPIs to measure success from different dimensions—this parameter filters by the second priority metric. When used with outcomeKpiFirst and/or outcomeKpiThird, all specified metrics must match (AND logic). Useful for finding programs with specific multi-metric tracking configurations. Omit to include programs regardless of second KPI setting.

Allowed:
string
enum

Optional filter for the tertiary success metric assigned to programs, restricting results to programs tracking the specified outcome KPI as their third metric. Valid values include WinRate, WonOpportunities, InfluencedRevenue, FirstDealAverageCloseTime, SecondDealAverageCloseTime, ThirdDealAverageCloseTime, and InfluencedActiveOpportunities. This parameter enables filtering by the third priority KPI for programs measuring success across multiple dimensions. When combined with outcomeKpiFirst and/or outcomeKpiSecond, all specified metrics must match (AND logic). Useful for identifying programs with comprehensive three-metric tracking strategies. Omit to include programs regardless of third KPI configuration.

Allowed:
currentPhases
array of strings

Optional array of phase identifiers to filter programs by their current workflow stage, returning only programs whose currentPhase matches one of the specified phase IDs. Each phase ID is a stable string identifier (e.g., ['phase-planning', 'phase-execution']) referencing phases defined in the workspace or program configuration. Acts as an OR filter—programs in any of the listed phases will be included. Useful for generating phase-specific reports, workload distribution analysis, or progress tracking across multiple workflow stages. Omit to include programs regardless of current phase. Empty array returns no results.

currentPhases
boolean
Defaults to false

Indicator to include deactivated programs in results. Ignored when the archived parameter is provided.

Responses

Updated about 21 hours ago

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