> ## 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.
# reports
> sift/reports/v1/reports.proto
## Services
*RPC methods exposed by this API.*
### ReportService
Report access is gated on the parent run's view\_details (RESOURCE\_TYPE\_RUN), not on
RESOURCE\_TYPE\_REPORT (which the policy evaluation service does not yet support). RPCs that have
a run id directly on the request use inbound\_policy\_enforcement; RPCs that resolve the run via a
DB lookup (e.g. report\_id -> report -> run\_id) use manual\_policy\_enforcement and do the check in
the handler. See web-service/authorization/authorization.go for the helpers.
| Method | Request | Response | Description |
| :------------------------------- | :---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GetReport | [GetReportRequest](#getreportrequest) | [GetReportResponse](#getreportresponse) | Retrieve a report. |
| CreateReport | [CreateReportRequest](#createreportrequest) | [CreateReportResponse](#createreportresponse) | Deprecated - use RuleEvaluationService instead. |
| UpdateReport | [UpdateReportRequest](#updatereportrequest) | [UpdateReportResponse](#updatereportresponse) | Update a report. |
| ListReports | [ListReportsRequest](#listreportsrequest) | [ListReportsResponse](#listreportsresponse) | List reports. |
| RerunReport | [RerunReportRequest](#rerunreportrequest) | [RerunReportResponse](#rerunreportresponse) | Rerunning a report will create a new report with the same rule versions and run as the original report and run the evaluation again using the most up-to-date set of data. |
| CancelReport | [CancelReportRequest](#cancelreportrequest) | [CancelReportResponse](#cancelreportresponse) | Canceling a report will stop the evaluation of the report and mark it as canceled. Any results that have been calculated up to the point of cancellation will be saved. |
| ListReportRuleSummaries | [ListReportRuleSummariesRequest](#listreportrulesummariesrequest) | [ListReportRuleSummariesResponse](#listreportrulesummariesresponse) | List paginated rule summaries for a report. |
| ListReportMetadataValues | [ListReportMetadataValuesRequest](#listreportmetadatavaluesrequest) | [ListReportMetadataValuesResponse](#listreportmetadatavaluesresponse) | List paginated metadata values for a report. |
| ListReportsWithCumulativeSummary | [ListReportsWithCumulativeSummaryRequest](#listreportswithcumulativesummaryrequest) | [ListReportsWithCumulativeSummaryResponse](#listreportswithcumulativesummaryresponse) | List reports with cumulative summary. |
## Messages
*Data models used across requests/responses.*
### CancelReportRequest
| Field | Type | Label | Description |
| :--------- | :----- | :---- | :---------- |
| report\_id | string | | |
### CancelReportResponse
no response fields
*This message has no fields.*
### CreateReportFromReportTemplateRequest
Deprecated - use RuleEvaluationService instead.
Report rule lines use each template rule's `display_order` from `ReportTemplateRule` at creation time.
| Field | Type | Label | Description |
| :------------------- | :----- | :---- | :---------- |
| report\_template\_id | string | | |
### CreateReportFromRulesRequest
Deprecated - use RuleEvaluationService instead.
How rules are ordered on the created report depends on `rule_identifiers`: list order for `rule_ids`, or server resolution order for `rule_client_keys`.
| Field | Type | Label | Description |
| :------------------------------------------ | :---------------------------------------------------------------------- | :------- | :---------- |
| name | string | | |
| description | string | optional | |
| tag\_names | string | repeated | |
| oneof rule\_identifiers. rule\_ids | [CreateReportRequestRuleIds](#createreportrequestruleids) | | |
| oneof rule\_identifiers. rule\_client\_keys | [CreateReportRequestClientKeys](#createreportrequestclientkeys) | | |
| oneof rule\_identifiers. rule\_version\_ids | [CreateReportRequestRuleVersionIds](#createreportrequestruleversionids) | | |
### CreateReportRequest
Deprecated - use RuleEvaluationService instead.
| Field | Type | Label | Description |
| :----------------------------------------------------- | :------------------------------------------------------------------------------ | :------- | :---------------------------------------------------------------------------------------------------------------- |
| oneof request. report\_from\_report\_template\_request | [CreateReportFromReportTemplateRequest](#createreportfromreporttemplaterequest) | | |
| oneof request. report\_from\_rules\_request | [CreateReportFromRulesRequest](#createreportfromrulesrequest) | | |
| organization\_id | string | | |
| run\_id | string | | |
| name | string | optional | Override the name of the report. If not provided, the name will be generated based on the report template or run. |
| metadata | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | |
### CreateReportRequestClientKeys
Deprecated - use RuleEvaluationService instead.
Rule order on the created report follows the order in which the server resolves these keys to rules (not client-defined).
| Field | Type | Label | Description |
| :----------------- | :----- | :------- | :---------- |
| rule\_client\_keys | string | repeated | |
### CreateReportRequestRuleIds
Deprecated - use RuleEvaluationService instead.
The order of `rule_ids` is the report rule order: first ID is `display_order` 0, second is 1, etc., on the created report.
| Field | Type | Label | Description |
| :-------- | :----- | :------- | :---------- |
| rule\_ids | string | repeated | |
### CreateReportRequestRuleVersionIds
Deprecated - use RuleEvaluationService instead.
| Field | Type | Label | Description |
| :----------------- | :----- | :------- | :---------- |
| rule\_version\_ids | string | repeated | |
### CreateReportResponse
Deprecated - use RuleEvaluationService instead.
| Field | Type | Label | Description |
| :----- | :---------------- | :---- | :---------- |
| report | [Report](#report) | | |
### GetReportRequest
The request for a call to `ReportService_GetReport` to retrieve a report template.
| Field | Type | Label | Description |
| :--------- | :----- | :---- | :---------- |
| report\_id | string | | |
### GetReportResponse
The request of a call to `ReportService_GetReport` to retrieve a report template.
| Field | Type | Label | Description |
| :----- | :---------------- | :---- | :---------- |
| report | [Report](#report) | | |
### ListReportMetadataValuesRequest
The request for a call to `ReportService_ListReportMetadataValues`.
| Field | Type | Label | Description |
| :---------- | :----- | :---- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| report\_id | string | | The report whose metadata values to list. |
| page\_size | uint32 | | The maximum number of metadata values to return. The service may return fewer than this value. If unspecified, at most 50 metadata values will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Optional. |
| page\_token | string | | A page token, received from a previous `ListReportMetadataValues` call. Provide this to retrieve the subsequent page. Optional. |
| filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `key_name`, `value_string`, `value_number`, `value_boolean`, `key_is_archived`, and `value_is_archived`. Optional. |
### ListReportMetadataValuesResponse
The response of a call to `ReportService_ListReportMetadataValues`.
| Field | Type | Label | Description |
| :---------------- | :---------------------------------------------------------------- | :------- | :---------- |
| metadata\_values | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | |
| next\_page\_token | string | | |
### ListReportRuleSummariesRequest
The request for a call to `ReportService_ListReportRuleSummaries`.
| Field | Type | Label | Description |
| :---------- | :----- | :---- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| report\_id | string | | The report whose rule summaries to list. |
| page\_size | uint32 | | The maximum number of rule summaries to return. The service may return fewer than this value. If unspecified, at most 50 rule summaries will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Optional. |
| page\_token | string | | A page token, received from a previous `ListReportRuleSummaries` call. Provide this to retrieve the subsequent page. Optional. |
| filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `rule_id`, `rule_version_id`, `asset_id`, `status`, `created_date`, and `modified_date`. Optional. |
| order\_by | string | | How to order the retrieved rule summaries. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order by are `display_order`, `created_date`, and `modified_date`. If left empty, items are ordered by `display_order` ascending. |
### ListReportRuleSummariesResponse
The response of a call to `ReportService_ListReportRuleSummaries`.
| Field | Type | Label | Description |
| :---------------------- | :-------------------------------------- | :------- | :---------- |
| report\_rule\_summaries | [ReportRuleSummary](#reportrulesummary) | repeated | |
| next\_page\_token | string | | |
### ListReportsRequest
The request for a call to `ReportService_ListReports` to retrieve report.
| Field | Type | Label | Description |
| :--------------- | :----- | :---- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page\_size | uint32 | | The maximum number of reports to return. The service may return fewer than this value. If unspecified, at most 50 reports will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Optional. |
| page\_token | string | | A page token, received from a previous `ListReports` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListReports` must match the call that provided the page token. Optional. |
| filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `report_id`, `report_template_id`, `tag_name`, `name`, `run_id`, `is_archived`, `archived_date`, `created_date`, `created_by_user_id`, `metadata`, `modified_date`, and `modified_by_user_id`. 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). For more information about the fields used for filtering, please refer to [this definition](/docs/api/grpc/protocol-buffers/reports#report). Optional. |
| organization\_id | string | | This field is only required if your user belongs to multiple organizations. |
| order\_by | string | | How to order the retrieved reports. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are `name`, `created_date` and `modified_date`. If left empty, items are ordered by `created_date` in descending order (newest-first). For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc,modified\_date" |
### ListReportsResponse
The response of a call to `ReportService_ListReportsResponse`.
| Field | Type | Label | Description |
| :---------------- | :---------------- | :------- | :---------- |
| reports | [Report](#report) | repeated | |
| next\_page\_token | string | | |
### ListReportsWithCumulativeSummaryRequest
The request for a call to `ReportService_ListReportsWithCumulativeSummary` to retrieve reports.
| Field | Type | Label | Description |
| :--------------- | :----- | :---- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page\_size | uint32 | | The maximum number of reports to return. The service may return fewer than this value. If unspecified, at most 50 reports will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. Optional. |
| page\_token | string | | A page token, received from a previous `ListReportsWithCumulativeSummary` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListReportsWithCumulativeSummary` must match the call that provided the page token. Optional. |
| filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `report_id`, `report_template_id`, `tag_name`, `name`, `run_id`, `is_archived`, `archived_date`, `created_date`, `created_by_user_id`, `metadata`, `modified_date`, and `modified_by_user_id`. 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). For more information about the fields used for filtering, please refer to [this definition](/docs/api/grpc/protocol-buffers/reports#report). Optional. |
| organization\_id | string | | This field is only required if your user belongs to multiple organizations. |
| order\_by | string | | How to order the retrieved reports. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are `name`, `created_date` and `modified_date`. If left empty, items are ordered by `created_date` in descending order (newest-first). For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc,modified\_date" |
### ListReportsWithCumulativeSummaryResponse
The response of a call to `ReportService_ListReportsWithCumulativeSummaryResponse`.
| Field | Type | Label | Description |
| :---------------- | :---------------------------------------------------------- | :------- | :---------- |
| reports | [ReportWithCumulativeSummary](#reportwithcumulativesummary) | repeated | |
| next\_page\_token | string | | |
### Report
| Field | Type | Label | Description |
| :---------------------- | :---------------------------------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| report\_id | string | | |
| report\_template\_id | string | | |
| run\_id | string | | |
| organization\_id | string | | |
| name | string | | |
| description | string | optional | |
| created\_by\_user\_id | string | | |
| modified\_by\_user\_id | string | | |
| created\_date | google.protobuf.Timestamp | | |
| modified\_date | google.protobuf.Timestamp | | |
| summaries | [ReportRuleSummary](#reportrulesummary) | repeated | One entry per rule line on this report. Sort by `display_order` ascending for the canonical evaluation / display sequence (clients may still group by status for UI). `display_order` is set when the report is created from a template or from rules. |
| tags | [ReportTag](#reporttag) | repeated | |
| rerun\_from\_report\_id | string | optional | |
| job\_id | string | optional | |
| archived\_date | google.protobuf.Timestamp | optional | |
| metadata | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | |
| is\_archived | bool | | |
### ReportCumulativeRuleSummary
Aggregated annotation and rule-status counts across all rules in a report.
Annotation counts (num\_annotations\_*) reflect the total number
of annotations in each state summed over every rule version in the report.
Rule counts (num\_rules\_*) reflect how many rule versions are in each
execution status.
| Field | Type | Label | Description |
| :----------------------------------- | :----- | :---- | :--------------------------------------------------------------------- |
| num\_annotations\_open | uint32 | | Total number of open (unresolved) annotations across all rules. |
| num\_annotations\_failed | uint32 | | Total number of failed (flagged) annotations across all rules. |
| num\_annotations\_passed | uint32 | | Total number of passed (resolved) annotations across all rules. |
| num\_annotations\_total | uint32 | | Total number of annotations across all rules (open + failed + passed). |
| num\_rules\_created | uint32 | | Number of rule versions in CREATED status. |
| num\_rules\_live | uint32 | | Number of rule versions currently running (LIVE status). |
| num\_rules\_finished | uint32 | | Number of rule versions that finished successfully. |
| num\_rules\_failed | uint32 | | Number of rule versions that failed during execution. |
| num\_rules\_canceled | uint32 | | Number of rule versions that were canceled. |
| num\_rules\_error | uint32 | | Number of rule versions that encountered an error. |
| num\_rules\_total | uint32 | | Total number of rule versions across all statuses. |
| num\_of\_rules\_without\_annotations | uint32 | | Number of finished rule versions that produced no annotations. |
### ReportRuleStatusDetails
| Field | Type | Label | Description |
| :---------------------- | :------------------------------------------------------------------ | :---- | :---------- |
| oneof details. created | [ReportRuleStatusDetailsCreated](#reportrulestatusdetailscreated) | | |
| oneof details. live | [ReportRuleStatusDetailsLive](#reportrulestatusdetailslive) | | |
| oneof details. finished | [ReportRuleStatusDetailsFinished](#reportrulestatusdetailsfinished) | | |
| oneof details. failed | [ReportRuleStatusDetailsFailed](#reportrulestatusdetailsfailed) | | |
| oneof details. canceled | [ReportRuleStatusDetailsCanceled](#reportrulestatusdetailscanceled) | | |
| oneof details. error | [ReportRuleStatusDetailsError](#reportrulestatusdetailserror) | | |
### ReportRuleStatusDetailsCanceled
*This message has no fields.*
### ReportRuleStatusDetailsCreated
*This message has no fields.*
### ReportRuleStatusDetailsError
| Field | Type | Label | Description |
| :------------- | :----- | :------- | :---------- |
| error\_message | string | | |
| exit\_code | int32 | optional | |
| stdout | string | optional | |
| stderr | string | optional | |
### ReportRuleStatusDetailsFailed
| Field | Type | Label | Description |
| :------------- | :----- | :------- | :---------- |
| error\_message | string | | |
| exit\_code | int32 | optional | |
| stdout | string | optional | |
| stderr | string | optional | |
### ReportRuleStatusDetailsFinished
| Field | Type | Label | Description |
| :----- | :----- | :------- | :---------- |
| stdout | string | optional | |
| stderr | string | optional | |
### ReportRuleStatusDetailsLive
*This message has no fields.*
### ReportRuleSummary
| Field | Type | Label | Description |
| :------------------------ | :-------------------------------------------------- | :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| rule\_id | string | | |
| rule\_client\_key | string | | |
| rule\_version\_id | string | | |
| rule\_version\_number | uint32 | | |
| report\_rule\_version\_id | string | | |
| num\_open | uint32 | | |
| num\_failed | uint32 | | |
| num\_passed | uint32 | | |
| status | [ReportRuleStatus](#reportrulestatus) | | |
| status\_details | [ReportRuleStatusDetails](#reportrulestatusdetails) | | |
| created\_date | google.protobuf.Timestamp | | |
| modified\_date | google.protobuf.Timestamp | | |
| asset\_id | string | | |
| deleted\_date | google.protobuf.Timestamp | | |
| display\_order | uint32 | | Zero-based position of this rule line on the report. Copied from the report template rule's `display_order`, or from the position of `rule_id` in `CreateReportRequestRuleIds.rule_ids` when creating from explicit rule IDs. Lower values run first. |
### ReportTag
| Field | Type | Label | Description |
| :-------- | :----- | :---- | :---------- |
| tag\_name | string | | |
### ReportWithCumulativeSummary
ReportWithCumulativeSummary is a projection of `Report` that replaces the per-rule `summaries`
list with a single `cumulative_summary` aggregated across all rules. It is returned by
`ListReportsWithCumulativeSummary` to keep response sizes manageable when listing many reports.
| Field | Type | Label | Description |
| :---------------------- | :---------------------------------------------------------- | :------- | :-------------------------------------------------------------------------- |
| report\_id | string | | The unique identifier of the report. |
| report\_template\_id | string | | The identifier of the report template this report was created from, if any. |
| run\_id | string | | The identifier of the run associated with this report. |
| organization\_id | string | | The organization this report belongs to. |
| name | string | | The display name of the report. |
| description | string | optional | An optional description of the report. |
| created\_by\_user\_id | string | | The identifier of the user who created the report. |
| modified\_by\_user\_id | string | | The identifier of the user who last modified the report. |
| created\_date | google.protobuf.Timestamp | | When the report was created. |
| modified\_date | google.protobuf.Timestamp | | When the report was last modified. |
| cumulative\_summary | [ReportCumulativeRuleSummary](#reportcumulativerulesummary) | | Aggregated rule summary across all rules on this report. |
| tags | [ReportTag](#reporttag) | repeated | Tags associated with this report. |
| rerun\_from\_report\_id | string | optional | The identifier of the report this report was rerun from, if any. |
| job\_id | string | optional | The identifier of the job that produced this report, if any. |
| archived\_date | google.protobuf.Timestamp | optional | When the report was archived, if it has been archived. |
| is\_archived | bool | | Whether the report has been archived. |
### RerunReportRequest
| Field | Type | Label | Description |
| :--------- | :----- | :---- | :---------- |
| report\_id | string | | |
### RerunReportResponse
| Field | Type | Label | Description |
| :--------- | :----- | :---- | :---------- |
| job\_id | string | | |
| report\_id | string | | |
### UpdateReportRequest
| Field | Type | Label | Description |
| :----------- | :------------------------------------------------------ | :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| report | [Report](#report) | | The report to update. |
| update\_mask | [google.protobuf.FieldMask](#google-protobuf-fieldmask) | | The list of fields to be updated. The fields available to be updated are `name`, `description`, `archived_date`, `is_archived`, and `metadata`. An empty `name` is ignored and the existing name is preserved. Including `description` in the mask with the field unset clears the description. |
### UpdateReportResponse
no response fields
*This message has no fields.*
## Enums
*Allowed constant values used in message fields.*
### ReportRuleStatus
| Name | Number | Description |
| :-------------------------------- | :----- | :---------- |
| REPORT\_RULE\_STATUS\_UNSPECIFIED | 0 | |
| REPORT\_RULE\_STATUS\_CREATED | 1 | |
| REPORT\_RULE\_STATUS\_LIVE | 2 | |
| REPORT\_RULE\_STATUS\_FINISHED | 3 | |
| REPORT\_RULE\_STATUS\_FAILED | 4 | |
| REPORT\_RULE\_STATUS\_CANCELED | 5 | |
| REPORT\_RULE\_STATUS\_ERROR | 6 | |