Services
RPC methods exposed by this API.FamilyService
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 |
CreateFamilyRequest
| Field | Type | Label | Description |
|---|---|---|---|
| family | Family | Family level information about the family such as archival status and client_key are set in the Family. | |
| family_version | FamilyVersion | Version specific information about the family such as name, description, metadata, etc. are set in the FamilyVersion. | |
| family_runs | FamilyRun | repeated | The runs to include in the family. At least one run must be specified. |
| family_alignments | FamilyAlignment | repeated | The alignments to apply to the family. If not provided, a default alignment will be created for the Family. |
| family_stats | 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 |
CreateFamilyStatRangesRequest
| Field | Type | Label | Description |
|---|---|---|---|
| family_stat_ids | string | repeated | |
| family_stat_ranges | FamilyStatRange | repeated |
CreateFamilyStatRangesResponse
| Field | Type | Label | Description |
|---|---|---|---|
| family_version_id | string | ||
| family | FamilyDetails | ||
| family_stats | FamilyStatDetails | repeated |
DefaultAnnotationAlignment
| Field | Type | Label | Description |
|---|---|---|---|
| annotation_name | string | ||
| bound | TimeRangeBound | ||
| occurrence | 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 | ||
| oneof default_alignment. annotation | DefaultAnnotationAlignment | ||
| oneof default_alignment. timestamp | TimestampAlignment | ||
| family_alignment_points | 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 | ||
| oneof alignment. annotation | AnnotationAlignment | ||
| oneof alignment. timestamp | TimestampAlignment |
FamilyDetails
| Field | Type | Label | Description |
|---|---|---|---|
| family | Family | ||
| family_version | FamilyVersion | The requested FamilyVersion for the family. Matches the current version unless a specific version is requested. | |
| family_runs | FamilyRun | repeated | The family members associated with the FamilyVersion. |
| family_alignments | FamilyAlignment | repeated | The alignments associated with the FamilyVersion. |
| family_stats | 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 |
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 | ||
| family_stat_expressions | FamilyStatExpression | repeated | |
| family_stat_channels | FamilyStatChannel | repeated | |
| family_stat_ranges | 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 | 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 | 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 | 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 | ||
| window_end | 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 | 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 |
GetFamilyRuleDependenciesRequest
| Field | Type | Label | Description |
|---|---|---|---|
| family_id | string |
GetFamilyRuleDependenciesResponse
| Field | Type | Label | Description |
|---|---|---|---|
| rule_dependencies | FamilyRuleDependency | repeated |
GetFamilyStatRequest
| Field | Type | Label | Description |
|---|---|---|---|
| family_stat_id | string |
GetFamilyStatResponse
| Field | Type | Label | Description |
|---|---|---|---|
| family_stat_details | FamilyStatDetails |
GetFamilyStatsRequest
| Field | Type | Label | Description |
|---|---|---|---|
| family_version_id | string |
GetFamilyStatsResponse
| Field | Type | Label | Description |
|---|---|---|---|
| family_stats_details | FamilyStatDetails | repeated |
GetFamilyVersionRequest
| Field | Type | Label | Description |
|---|---|---|---|
| family_version_id | string |
GetFamilyVersionResponse
| Field | Type | Label | Description |
|---|---|---|---|
| family | 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 |
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 | See UpdateFamilyRequest |
ImportUpdateFamilyResponse
| Field | Type | Label | Description |
|---|---|---|---|
| family_version_id | string | ||
| family | 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) 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. | |
| 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 Example: “created_date desc” |
ListFamiliesResponse
| Field | Type | Label | Description |
|---|---|---|---|
| families | 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_version | 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) 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. | |
| 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 | 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) filter string. Available fields to filter by are: name, description. For further information about how to use CELs, please refer to this guide. | |
| 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 | 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 forFamilyService.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) 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 | 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) 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. | |
| 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 | 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) 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. | |
| 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 Example: “created_date desc” |
ListFamilyVersionsResponse
| Field | Type | Label | Description |
|---|---|---|---|
| family_versions | 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 |
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 | The family data to update. Only fields referenced in the update_mask will be updated. | |
| update_mask | 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 | ||
| family_stats | 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 |