> ## Documentation Index > Fetch the complete documentation index at: https://docs.siftstack.com/llms.txt > Use this file to discover all available pages before exploring further. # families > sift/families/v1/families.proto ## Services *RPC methods exposed by this API.* ### FamilyService | Method | Request | Response | Description | | :-------------------------- | :------------------------------------------------------------------------ | :-------------------------------------------------------------------------- | :---------- | | GetFamily | [GetFamilyRequest](#getfamilyrequest) | [GetFamilyResponse](#getfamilyresponse) | | | GetFamilies | [GetFamiliesRequest](#getfamiliesrequest) | [GetFamiliesResponse](#getfamiliesresponse) | | | GetFamilyVersion | [GetFamilyVersionRequest](#getfamilyversionrequest) | [GetFamilyVersionResponse](#getfamilyversionresponse) | | | CreateFamily | [CreateFamilyRequest](#createfamilyrequest) | [CreateFamilyResponse](#createfamilyresponse) | | | UpdateFamily | [UpdateFamilyRequest](#updatefamilyrequest) | [UpdateFamilyResponse](#updatefamilyresponse) | | | GetFamilyCandidateRuns | [GetFamilyCandidateRunsRequest](#getfamilycandidaterunsrequest) | [GetFamilyCandidateRunsResponse](#getfamilycandidaterunsresponse) | | | GetFamilyCandidateRunCount | [GetFamilyCandidateRunCountRequest](#getfamilycandidateruncountrequest) | [GetFamilyCandidateRunCountResponse](#getfamilycandidateruncountresponse) | | | ListFamilyCandidateRuns | [ListFamilyCandidateRunsRequest](#listfamilycandidaterunsrequest) | [ListFamilyCandidateRunsResponse](#listfamilycandidaterunsresponse) | | | ListFamilies | [ListFamiliesRequest](#listfamiliesrequest) | [ListFamiliesResponse](#listfamiliesresponse) | | | ListFamilyVersions | [ListFamilyVersionsRequest](#listfamilyversionsrequest) | [ListFamilyVersionsResponse](#listfamilyversionsresponse) | | | ListFamilyMembers | [ListFamilyMembersRequest](#listfamilymembersrequest) | [ListFamilyMembersResponse](#listfamilymembersresponse) | | | ListFamilyAlignments | [ListFamilyAlignmentsRequest](#listfamilyalignmentsrequest) | [ListFamilyAlignmentsResponse](#listfamilyalignmentsresponse) | | | ListFamilyAlignmentPoints | [ListFamilyAlignmentPointsRequest](#listfamilyalignmentpointsrequest) | [ListFamilyAlignmentPointsResponse](#listfamilyalignmentpointsresponse) | | | ImportFamily | [ImportFamilyRequest](#importfamilyrequest) | [ImportFamilyResponse](#importfamilyresponse) | | | ImportUpdateFamily | [ImportUpdateFamilyRequest](#importupdatefamilyrequest) | [ImportUpdateFamilyResponse](#importupdatefamilyresponse) | | | ExportFamily | [ExportFamilyRequest](#exportfamilyrequest) | [ExportFamilyResponse](#exportfamilyresponse) | | | ValidateFamilyName | [ValidateFamilyNameRequest](#validatefamilynamerequest) | [ValidateFamilyNameResponse](#validatefamilynameresponse) | | | ValidateFamilyClientKey | [ValidateFamilyClientKeyRequest](#validatefamilyclientkeyrequest) | [ValidateFamilyClientKeyResponse](#validatefamilyclientkeyresponse) | | | GetFamilyStat | [GetFamilyStatRequest](#getfamilystatrequest) | [GetFamilyStatResponse](#getfamilystatresponse) | | | GetFamilyStats | [GetFamilyStatsRequest](#getfamilystatsrequest) | [GetFamilyStatsResponse](#getfamilystatsresponse) | | | CreateFamilyStatRanges | [CreateFamilyStatRangesRequest](#createfamilystatrangesrequest) | [CreateFamilyStatRangesResponse](#createfamilystatrangesresponse) | | | GetFamilyRuleDependencies | [GetFamilyRuleDependenciesRequest](#getfamilyruledependenciesrequest) | [GetFamilyRuleDependenciesResponse](#getfamilyruledependenciesresponse) | | | GenerateFamilyStatRangeName | [GenerateFamilyStatRangeNameRequest](#generatefamilystatrangenamerequest) | [GenerateFamilyStatRangeNameResponse](#generatefamilystatrangenameresponse) | | ## Messages *Data models used across requests/responses.* ### AbstractWindowType AbstractWindowType represents a window boundary that is agnostic of the alignment ID. | Field | Type | Label | Description | | :---------------------- | :----------------------- | :---- | :---------------------------------------------------------------------------------- | | family\_alignment\_name | string | | | | duration | google.protobuf.Duration | | Duration relative to the alignment used to compare the data. Defaults to 0 seconds. | ### AnnotationAlignment | Field | Type | Label | Description | | :------------- | :-------------------------------- | :---- | :---------- | | annotation\_id | string | | | | bound | [TimeRangeBound](#timerangebound) | | | ### CreateFamilyRequest | Field | Type | Label | Description | | :----------------- | :-------------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------- | | family | [Family](#family) | | Family level information about the family such as archival status and client\_key are set in the Family. | | family\_version | [FamilyVersion](#familyversion) | | Version specific information about the family such as name, description, metadata, etc. are set in the FamilyVersion. | | family\_runs | [FamilyRun](#familyrun) | repeated | The runs to include in the family. At least one run must be specified. | | family\_alignments | [FamilyAlignment](#familyalignment) | repeated | The alignments to apply to the family. If not provided, a default alignment will be created for the Family. | | family\_stats | [FamilyStatDetails](#familystatdetails) | repeated | The family stats to create for the family. If not provided, no family stats will be created. | ### CreateFamilyResponse | Field | Type | Label | Description | | :--------- | :------------------------------ | :---- | :---------- | | family\_id | string | | | | family | [FamilyDetails](#familydetails) | | | ### CreateFamilyStatRangesRequest | Field | Type | Label | Description | | :------------------- | :---------------------------------- | :------- | :---------- | | family\_stat\_ids | string | repeated | | | family\_stat\_ranges | [FamilyStatRange](#familystatrange) | repeated | | ### CreateFamilyStatRangesResponse | Field | Type | Label | Description | | :------------------ | :-------------------------------------- | :------- | :---------- | | family\_version\_id | string | | | | family | [FamilyDetails](#familydetails) | | | | family\_stats | [FamilyStatDetails](#familystatdetails) | repeated | | ### DefaultAnnotationAlignment | Field | Type | Label | Description | | :---------------- | :-------------------------------------------- | :---- | :------------------------------------------------------------------------------------------------------------------------- | | annotation\_name | string | | | | bound | [TimeRangeBound](#timerangebound) | | | | occurrence | [AnnotationOccurrence](#annotationoccurrence) | | | | occurrence\_index | int32 | | Index of the annotation to use when occurrence is "nth". Positive indices start from the beginning, negative from the end. | ### ExportFamilyRequest | Field | Type | Label | Description | | :-------------------------------------------- | :----- | :---- | :---------- | | oneof family\_identifier. family\_id | string | | | | oneof family\_identifier. client\_key | string | | | | oneof family\_identifier. family\_version\_id | string | | | ### ExportFamilyResponse | Field | Type | Label | Description | | :--------------- | :----- | :---- | :---------- | | exported\_family | string | | | ### Family | Field | Type | Label | Description | | :--------------------- | :------------------------ | :---- | :------------------------------------------------------------- | | family\_id | string | | | | client\_key | string | | Client key is a user-provided unique identifier for the family | | current\_version\_id | string | | The latest family\_version\_id for the family. | | is\_archived | bool | | Whether the family is archived. | | created\_date | google.protobuf.Timestamp | | | | modified\_date | google.protobuf.Timestamp | | | | archived\_date | google.protobuf.Timestamp | | | | created\_by\_user\_id | string | | | | modified\_by\_user\_id | string | | | | organization\_id | string | | | ### FamilyAlignment FamilyAlignment represents a family-level time-alignment for naming and resolving run relative times. | Field | Type | Label | Description | | :----------------------------------- | :-------------------------------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | family\_alignment\_id | string | | When creating a family, this field can contain a temporary identifier provided by the client for referencing this alignment in family\_stats. The temporary ID must be unique within the CreateFamilyRequest and is required when this alignment is referenced in family\_stats. The service will resolve it to the actual alignment ID. When updating a family, this field must contain the actual family\_alignment\_id. In responses, this field contains the actual family\_alignment\_id. | | family\_version\_id | string | | | | name | string | | The name of the alignment. Must be unique within the family. | | description | string | | | | oneof default\_alignment. run | [RunAlignment](#runalignment) | | | | oneof default\_alignment. annotation | [DefaultAnnotationAlignment](#defaultannotationalignment) | | | | oneof default\_alignment. timestamp | [TimestampAlignment](#timestampalignment) | | | | family\_alignment\_points | [FamilyAlignmentPoint](#familyalignmentpoint) | repeated | Specific alignment points for each family member for the alignment. If not provided for a family member, the member does not implement this alignment. | ### FamilyAlignmentPoint FamilyAlignmentPoint represents a member specific time-alignment for the FamilyAlignment. | Field | Type | Label | Description | | :--------------------------- | :------------------------------------------ | :---- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | family\_alignment\_point\_id | string | | When creating a family, this field can contain a temporary identifier provided by the client for referencing this alignment point in family\_stats. The temporary ID must be unique within the CreateFamilyRequest and is required when this alignment point is referenced in family\_stats. The service will resolve it to the actual alignment\_point\_id. When updating a family, this field must contain the actual family\_alignment\_point\_id. In responses, this field contains the actual family\_alignment\_point\_id. Can be empty string if not referenced in family\_stats. | | family\_run\_id | string | | | | run\_id | string | | | | family\_alignment\_id | string | | | | oneof alignment. run | [RunAlignment](#runalignment) | | | | oneof alignment. annotation | [AnnotationAlignment](#annotationalignment) | | | | oneof alignment. timestamp | [TimestampAlignment](#timestampalignment) | | | ### FamilyDetails | Field | Type | Label | Description | | :----------------- | :-------------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------- | | family | [Family](#family) | | | | family\_version | [FamilyVersion](#familyversion) | | The requested FamilyVersion for the family. Matches the current version unless a specific version is requested. | | family\_runs | [FamilyRun](#familyrun) | repeated | The family members associated with the FamilyVersion. | | family\_alignments | [FamilyAlignment](#familyalignment) | repeated | The alignments associated with the FamilyVersion. | | family\_stats | [FamilyStatDetails](#familystatdetails) | repeated | The family stats associated with the FamilyVersion. | ### FamilyRuleDependency | Field | Type | Label | Description | | :-------------- | :---------------------------------------------------------------------- | :---- | :---------- | | rule\_id | string | | | | name | string | | | | stat\_reference | [sift.rules.v1.FamilyStatReference](#sift-rules-v1-familystatreference) | | | ### FamilyRun FamilyRun represents a run which is either included in the family or explicitly excluded. | Field | Type | Label | Description | | :--------------------- | :------------------------ | :---- | :--------------------------------------------------------------------------------------------------------------- | | family\_run\_id | string | | | | family\_version\_id | string | | | | run\_id | string | | | | is\_exclusion | bool | | Whether the run is excluded from the family. If `true` the run is explicitly excluded, otherwise it is included. | | rationale | string | | User rationale for the inclusion or exclusion. | | added\_date | google.protobuf.Timestamp | | Date when the run was included or excluded from the family. | | added\_by\_user\_id | string | | User id of the user who included or excluded the run from the family. | | added\_in\_version\_id | string | | Version id of the version in which the run was included or excluded from the family. | ### FamilyStat | Field | Type | Label | Description | | :---------------------- | :------------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | family\_stat\_id | string | | | | family\_version\_id | string | | The family version id of the family stat. | | name | string | | The name of the family stat. | | description | string | | The description of the family stat. | | sample\_rate | double | | The sample rate of the family stat (Hz). | | default\_channel\_names | string | repeated | Ordered list of channel names to include in the family stat. The first channel name is the primary channel name across all the family members. The remaining channel names are fallback channels or individual overrides when the primary channel is not available across all the family members. | | created\_date | google.protobuf.Timestamp | | | | modified\_date | google.protobuf.Timestamp | | | | created\_by\_user\_id | string | | | | modified\_by\_user\_id | string | | | | organization\_id | string | | | ### FamilyStatChannel | Field | Type | Label | Description | | :------------------------ | :----- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | family\_stat\_channel\_id | string | | | | family\_stat\_id | string | | | | channel\_id | string | | The channel id of the channel to include in the family stat given the list of channel names provided in the family stat. | | alignment\_point\_id | string | | Specific alignment point id of the family member / channel to include in the family stat. When creating a family stat with a new Family, this field should contain the temporary\_id from FamilyAlignmentPoint.family\_alignment\_point\_id. The service will resolve it to the actual alignment\_point\_id. When updating a family stat, this field must contain the actual alignment\_point\_id. This will be prevalent when multiple alignment points are supported for a given family member. | ### FamilyStatDetails | Field | Type | Label | Description | | :------------------------ | :-------------------------------------------- | :------- | :---------- | | family\_stat | [FamilyStat](#familystat) | | | | family\_stat\_expressions | [FamilyStatExpression](#familystatexpression) | repeated | | | family\_stat\_channels | [FamilyStatChannel](#familystatchannel) | repeated | | | family\_stat\_ranges | [FamilyStatRange](#familystatrange) | repeated | | ### FamilyStatExpression | Field | Type | Label | Description | | :----------------------------- | :-------------------- | :---- | :---------- | | family\_stat\_expression\_id | string | | | | family\_stat\_id | string | | | | oneof expression. avg | google.protobuf.Empty | | | | oneof expression. median | google.protobuf.Empty | | | | oneof expression. min | google.protobuf.Empty | | | | oneof expression. max | google.protobuf.Empty | | | | oneof expression. stdev | google.protobuf.Empty | | | | oneof expression. sum | google.protobuf.Empty | | | | oneof expression. input\_count | google.protobuf.Empty | | | | oneof expression. sigma | google.protobuf.Empty | | | ### FamilyStatRange | Field | Type | Label | Description | | :---------------------- | :------------------------ | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | family\_stat\_range\_id | string | | | | family\_stat\_id | string | | | | family\_alignment\_id | string | | T-0 Alignment ID to align the data for stat calculation. When creating a family stat with a new Family, this field should contain the temporary\_id from FamilyAlignment.family\_alignment\_id. The service will resolve it to the actual alignment ID. When updating a family stat, this field must contain the actual family\_alignment\_id. | | name | string | | Unique name for the family stat range. | | window\_start | [WindowType](#windowtype) | optional | The start of the window for the stat calculation. The start is an alignment ID and a duration relative to the alignment. Defaults to T-0 alignment and 0 seconds. | | window\_end | [WindowType](#windowtype) | optional | The end of the window for the stat calculation. The end is an alignment ID and a duration relative to the alignment. Defaults to T-0 alignment and 0 seconds. However, window end must be after window start. Service provides basic validation: if window\_start.family\_alignment\_id = window\_end.family\_alignment\_id, then window\_start.duration \< window\_end.duration. | ### FamilyVersion | Field | Type | Label | Description | | :--------------------- | :---------------------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | family\_version\_id | string | | | | family\_id | string | | | | version | uint32 | | | | name | string | | The name of the family. Must be unique within the organization for the latest family versions. | | description | string | | | | run\_query | string | | An optional query to track a CEL expression against the ListRuns endpoint. This query is only for reference, and does not affect the runs that are included in the family. To specify which runs are included in the family, use the `runs` field. | | user\_notes | string | | Notes provided by the user to describe the family version changes | | change\_message | string | | Family Service provided message describing the changes made to the family version. | | metadata | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | Metadata associated with the family version. | | sigma\_default\_values | double | repeated | User-configurable default sigma multiplier values, e.g. \[1, 2, 3]. If not provided, the default values \[-1, 1, -2, 2, -3, 3] will be used. | | created\_date | google.protobuf.Timestamp | | | | modified\_date | google.protobuf.Timestamp | | | | created\_by\_user\_id | string | | | | modified\_by\_user\_id | string | | | | organization\_id | string | | | ### GenerateFamilyStatRangeNameRequest | Field | Type | Label | Description | | :---------------------- | :---------------------------------------- | :---- | :---------- | | family\_alignment\_name | string | | | | window\_start | [AbstractWindowType](#abstractwindowtype) | | | | window\_end | [AbstractWindowType](#abstractwindowtype) | | | ### GenerateFamilyStatRangeNameResponse | Field | Type | Label | Description | | :---- | :----- | :---- | :---------- | | name | string | | | ### GetFamiliesRequest | Field | Type | Label | Description | | :----------- | :----- | :------- | :---------- | | family\_ids | string | repeated | | | client\_keys | string | repeated | | ### GetFamiliesResponse | Field | Type | Label | Description | | :------- | :------------------------------ | :------- | :---------- | | families | [FamilyDetails](#familydetails) | repeated | | ### GetFamilyCandidateRunCountRequest | Field | Type | Label | Description | | :------------------ | :----- | :---- | :---------- | | family\_version\_id | string | | | ### GetFamilyCandidateRunCountResponse | Field | Type | Label | Description | | :---- | :----- | :---- | :---------- | | count | uint32 | | | ### GetFamilyCandidateRunsRequest | Field | Type | Label | Description | | :------------------ | :----- | :---- | :---------- | | family\_version\_id | string | | | ### GetFamilyCandidateRunsResponse | Field | Type | Label | Description | | :------------------ | :----- | :------- | :---------- | | run\_query | string | | | | candidate\_run\_ids | string | repeated | | ### GetFamilyRequest | Field | Type | Label | Description | | :------------------------------------ | :----- | :---- | :---------- | | oneof family\_identifier. family\_id | string | | | | oneof family\_identifier. client\_key | string | | | ### GetFamilyResponse | Field | Type | Label | Description | | :----- | :------------------------------ | :---- | :---------- | | family | [FamilyDetails](#familydetails) | | | ### GetFamilyRuleDependenciesRequest | Field | Type | Label | Description | | :--------- | :----- | :---- | :---------- | | family\_id | string | | | ### GetFamilyRuleDependenciesResponse | Field | Type | Label | Description | | :----------------- | :-------------------------------------------- | :------- | :---------- | | rule\_dependencies | [FamilyRuleDependency](#familyruledependency) | repeated | | ### GetFamilyStatRequest | Field | Type | Label | Description | | :--------------- | :----- | :---- | :---------- | | family\_stat\_id | string | | | ### GetFamilyStatResponse | Field | Type | Label | Description | | :-------------------- | :-------------------------------------- | :---- | :---------- | | family\_stat\_details | [FamilyStatDetails](#familystatdetails) | | | ### GetFamilyStatsRequest | Field | Type | Label | Description | | :------------------ | :----- | :---- | :---------- | | family\_version\_id | string | | | ### GetFamilyStatsResponse | Field | Type | Label | Description | | :--------------------- | :-------------------------------------- | :------- | :---------- | | family\_stats\_details | [FamilyStatDetails](#familystatdetails) | repeated | | ### GetFamilyVersionRequest | Field | Type | Label | Description | | :------------------ | :----- | :---- | :---------- | | family\_version\_id | string | | | ### GetFamilyVersionResponse | Field | Type | Label | Description | | :----- | :------------------------------ | :---- | :---------- | | family | [FamilyDetails](#familydetails) | | | ### ImportFamilyRequest | Field | Type | Label | Description | | :----------- | :----- | :---- | :---------------------------------------------------------------------------------------------------------------------------------------- | | family\_yaml | string | | The source to import the family from. Must provide family\_yaml. The contents of the source should match the shape of CreateFamilyRequest | ### ImportFamilyResponse | Field | Type | Label | Description | | :--------- | :------------------------------ | :---- | :---------- | | family\_id | string | | | | family | [FamilyDetails](#familydetails) | | | ### ImportUpdateFamilyRequest | Field | Type | Label | Description | | :------------------------------------ | :------------------------------------------------------ | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | oneof family\_identifier. family\_id | string | | | | oneof family\_identifier. client\_key | string | | | | family\_yaml | string | | The source to update the family from. Must provide family\_yaml. The contents of the source should match the shape of UpdateFamilyRequest FamilyDetails. The update\_mask is optional and defaults to updating provided fields. | | update\_mask | [google.protobuf.FieldMask](#google-protobuf-fieldmask) | | See UpdateFamilyRequest | ### ImportUpdateFamilyResponse | Field | Type | Label | Description | | :------------------ | :------------------------------ | :---- | :---------- | | family\_version\_id | string | | | | family | [FamilyDetails](#familydetails) | | | ### ListFamiliesRequest | Field | Type | Label | Description | | :---------- | :----- | :---- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page\_size | uint32 | | The maximum number of families to return. The service may return fewer than this value, even if there are additional pages. If unspecified, the limit defaults to 50. The maximum value is 100. | | page\_token | string | | A page token, received from a previous `ListFamilies` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListFamilies` must match the call that provided the page token. | | filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are: `family_id`, `client_key`, `organization_id`, `archived_date`, `is_archived`, `created_by_user_id`, `created_date`, `modified_by_user_id`, `modified_date`, `name`, `description`, `run_query`, `run_id_includes`, `run_id_excludes`, `alignment_name`, `alignment_description`, `metadata`. For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). | | order\_by | string | | How to order the retrieved families. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are: `created_date`, `modified_date`, `archived_date`. If left empty, items are ordered by `created_date` in descending order. For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc" | ### ListFamiliesResponse | Field | Type | Label | Description | | :---------------- | :------------------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------- | | families | [ListFamily](#listfamily) | repeated | | | next\_page\_token | string | | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. | ### ListFamily | Field | Type | Label | Description | | :-------------- | :------------------------------ | :---- | :---------------------------------------------------- | | family | [Family](#family) | | | | family\_version | [FamilyVersion](#familyversion) | | The latest family version associated with the Family. | ### ListFamilyAlignmentPointsRequest | Field | Type | Label | Description | | :-------------------- | :----- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | family\_alignment\_id | string | | Provide family\_alignment\_id to identify the family to list alignments points. | | page\_size | uint32 | | The maximum number of family version alignment points to return. The service may return fewer than this value, even if there are additional pages. If unspecified, the limit defaults to 200. The maximum value is 1000. | | filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are: `family_run_id`, and for the associated Run: `name`, `description`, `start_time`, `end_time`, `duration`. Note: `name`, `description`, `start_time`, `end_time`, and `duration` are filters on the associated run. For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). | | page\_token | string | | A page token, received from a previous `ListFamilyAlignmentPoints` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListFamilyAlignmentPoints` must match the call that provided the page token. | ### ListFamilyAlignmentPointsResponse | Field | Type | Label | Description | | :------------------------ | :-------------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------- | | family\_alignment\_points | [FamilyAlignmentPoint](#familyalignmentpoint) | repeated | | | next\_page\_token | string | | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. | ### ListFamilyAlignmentsRequest | Field | Type | Label | Description | | :------------------ | :----- | :---- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | family\_version\_id | string | | Provide family\_id to identify the family to list alignments. | | page\_size | uint32 | | The maximum number of family version alignments to return. The service may return fewer than this value, even if there are additional pages. If unspecified, the limit defaults to 200. The maximum value is 1000. | | filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are: `name`, `description`. For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). | | page\_token | string | | A page token, received from a previous `ListFamilyAlignments` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListFamilyAlignments` must match the call that provided the page token. | ### ListFamilyAlignmentsResponse | Field | Type | Label | Description | | :----------------- | :---------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------- | | family\_alignments | [FamilyAlignment](#familyalignment) | repeated | | | next\_page\_token | string | | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. | ### ListFamilyCandidateRunsRequest Request for `FamilyService.ListFamilyCandidateRuns`. The CEL filter supports the standard run filter fields plus an `include_archived` directive. Archived runs are excluded by default; pass `include_archived == true` in the filter to include them. When `family_id` is set, the server filters out runs already on that family's persisted membership (both included and excluded entries) so the response only contains runs not yet on the family. Clients editing an unsaved draft of family membership should omit `family_id` and apply their own draft-aware filtering, since the persisted membership does not reflect the draft state. | Field | Type | Label | Description | | :---------- | :----- | :---- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | page\_size | uint32 | | The maximum number of runs to return. The service may return fewer than this value. If unspecified, at most 50 runs will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. | | page\_token | string | | A page token, received from a previous call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided must match the call that provided the page token. | | filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Supports all ListRuns filter fields plus `include_archived`. When `include_archived` is not present in the filter, archived runs are excluded by default. Set `include_archived == true` in the filter to include archived runs. Note: `include_archived` is a directive and must appear at the top level of the filter (or within a top-level AND chain). It cannot be used inside an OR expression. | | order\_by | string | | How to order the retrieved runs. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are `name`, `description`, `created_date`, `modified_date`, `start_time`, and `stop_time`. If left empty, items are ordered by `created_date` in descending order (newest-first). | | family\_id | string | | Optional family ID to filter out runs already on the family's persisted membership. When set, the response excludes runs that are already included or excluded in the family. Omit this field when working with draft membership changes. | ### ListFamilyCandidateRunsResponse | Field | Type | Label | Description | | :---------------- | :------------------------------------ | :------- | :---------- | | runs | [sift.runs.v2.Run](#sift-runs-v2-run) | repeated | | | next\_page\_token | string | | | ### ListFamilyMembersRequest | Field | Type | Label | Description | | :------------------ | :----- | :---- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | family\_version\_id | string | | Provide family\_version\_id to identify the family to list members for. | | page\_size | uint32 | | The maximum number of family members to return. The service may return fewer than this value, even if there are additional pages. If unspecified, the max limit defaults to 200. The maximum value is 500. | | filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are: `is_exclusion`, `rationale`, `added_date`, `added_by_user_id`, `added_in_version_id`, and for the associated Run:`name`, `description`, `start_time`, `end_time`, `duration`. Note: `name`, `description`, `start_time`, `end_time`, and `duration` are filters on the associated run. For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). | | page\_token | string | | A page token, received from a previous `ListFamilyMembers` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListFamilyMembers` must match the call that provided the page token. | ### ListFamilyMembersResponse | Field | Type | Label | Description | | :---------------- | :---------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------- | | family\_runs | [FamilyRun](#familyrun) | repeated | | | next\_page\_token | string | | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. | ### ListFamilyVersionsRequest | Field | Type | Label | Description | | :---------- | :----- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | page\_size | uint32 | | The maximum number of family versions to return. The service may return fewer than this value, even if there are additional pages. If unspecified, the max limit defaults to 50. The maximum value is 200. | | filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are: `family_id`, `family_version_id`, `organization_id`, `name`, `description`, `run_query`, `user_notes`, `change_message`, `created_by_user_id`, `created_date`, `modified_by_user_id`, `modified_date`, `archived_date`, `is_archived`, `run_id_includes`, `run_id_excludes`, `alignment_name`, `alignment_description`. For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). | | page\_token | string | | A page token, received from a previous `ListFamilyVersions` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListFamilyVersions` must match the call that provided the page token. | | order\_by | string | | How to order the retrieved family versions. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are: `created_date`, `modified_date`, `name`. If left empty, items are ordered by `created_date` in descending order. For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc" | ### ListFamilyVersionsResponse | Field | Type | Label | Description | | :---------------- | :------------------------------ | :------- | :----------------------------------------------------------------------------------------------------------------------------- | | family\_versions | [FamilyVersion](#familyversion) | repeated | | | next\_page\_token | string | | A token, which can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages. | ### RunAlignment | Field | Type | Label | Description | | :---- | :-------------------------------- | :---- | :---------- | | bound | [TimeRangeBound](#timerangebound) | | | ### TimestampAlignment | Field | Type | Label | Description | | :-------- | :------------------------ | :---- | :---------- | | timestamp | google.protobuf.Timestamp | | | ### UpdateFamilyRequest | Field | Type | Label | Description | | :------------------------------------ | :------------------------------------------------------ | :---- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | oneof family\_identifier. family\_id | string | | | | oneof family\_identifier. client\_key | string | | | | family | [FamilyDetails](#familydetails) | | The family data to update. Only fields referenced in the update\_mask will be updated. | | update\_mask | [google.protobuf.FieldMask](#google-protobuf-fieldmask) | | Note: Whenever the family is updated, the family stats are also updated to point to the new family version to ensure the family stats are always up to date. client\_key can only be updated if it is not already set. It must be passed in via the family request and cannot be used as identifier. | ### UpdateFamilyResponse | Field | Type | Label | Description | | :------------------ | :-------------------------------------- | :------- | :---------- | | family\_version\_id | string | | | | family | [FamilyDetails](#familydetails) | | | | family\_stats | [FamilyStatDetails](#familystatdetails) | repeated | | ### ValidateFamilyClientKeyRequest | Field | Type | Label | Description | | :---------- | :----- | :---- | :---------- | | client\_key | string | | | ### ValidateFamilyClientKeyResponse | Field | Type | Label | Description | | :--------------------------- | :----- | :---- | :---------- | | oneof result. success | bool | | | | oneof result. error\_message | string | | | ### ValidateFamilyNameRequest | Field | Type | Label | Description | | :----------- | :----- | :---- | :---------- | | family\_name | string | | | ### ValidateFamilyNameResponse | Field | Type | Label | Description | | :--------------------------- | :----- | :---- | :---------- | | oneof result. success | bool | | | | oneof result. error\_message | string | | | ### WindowType WindowType represents a window boundary that can be either an alignment ID or a duration. | Field | Type | Label | Description | | :-------------------- | :----------------------- | :---- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | family\_alignment\_id | string | | Alignment ID to use as the window boundary. When creating a family stat with a new Family, this field should contain the temporary\_id from FamilyAlignment.family\_alignment\_id. Default to the window's T-0 alignment. The service will resolve it to the actual alignment ID. When updating a family stat, this field must contain the actual family\_alignment\_id. | | duration | google.protobuf.Duration | | Duration relative to the alignment used to compare the data. Defaults to 0 seconds. | ## Enums *Allowed constant values used in message fields.* ### AnnotationOccurrence | Name | Number | Description | | :---------------------------------- | :----- | :-------------- | | ANNOTATION\_OCCURRENCE\_UNSPECIFIED | 0 | **Deprecated.** | | ANNOTATION\_OCCURRENCE\_FIRST | 1 | | | ANNOTATION\_OCCURRENCE\_LAST | 2 | | | ANNOTATION\_OCCURRENCE\_EVERY | 3 | | | ANNOTATION\_OCCURRENCE\_NTH | 4 | | ### TimeRangeBound | Name | Number | Description | | :------------------------------ | :----- | :-------------- | | TIME\_RANGE\_BOUND\_UNSPECIFIED | 0 | **Deprecated.** | | TIME\_RANGE\_BOUND\_START | 1 | | | TIME\_RANGE\_BOUND\_END | 2 | |