---
title: "Report"
method: PUT
path: "/api/3/reports/{id}"
tags: ["Report"]
---

# Report

`PUT /api/3/reports/{id}`

Updates the configuration details of a report.

## Path parameters

- `id` integer, required

## Request body

- Report — The specification of a report configuration.
  - `baseline` object — If the template is `baseline-comparison` or `executive-overview` the baseline scan to compare against. This can be the `first` scan, the `previous` scan, or a scan as of a specified date. Defaults to `previous`.
  - `bureau` string — The name of the bureau for a CyberScope report. Only used when the format is `"cyberscope-xml"`.
  - `component` string — The name of the component for a CyberScope report. Only used when the format is `"cyberscope-xml"`.
  - `email` ReportEmail — Email distribution settings for the report.
    - `access` 'file' | 'zip' | 'url' | 'none' — The format to distribute the report in when sending to users who have explicit access to the report.
    - `additional` 'file' | 'zip' | 'none' — The format to distribute the report to additional recipients.
    - `additionalRecipients` string[] — The email address of additional recipients to distribute the report to.
    - `assetAccess` boolean — Whether to distribute the report to all users to have access to assets in the report.
    - `owner` 'file' | 'url' | 'zip' | 'none' — The format to distribute the report to the owner.
    - `smtp` ReportEmailSmtp — SMTP delivery settings.
      - `global` boolean — Whether to use global SMTP settings. If enabled, `sender` and `relay` may not be specified.
      - `relay` string — SMTP relay host or IP address.
      - `sender` string — SMTP sender address.
  - `enclave` string — The name of the enclave for a CyberScope report. Only used when the format is `"cyberscope-xml"`.
  - `filters` ReportConfigFiltersResource — Filters applied to the contents of the report. The supported filters for a report vary by format and template. <div class="properties"> <div class="property-info"> <span class="property-name">categories</span> <span class="param-type complex">Object</span> <div class="redoc-markdown-block">The vulnerability categories to include or exclude in the report. Only included or excluded may be specified, not both.</div> </div> <div class="properties nested"> <div class="property-info"> <span class="property-name">included</span> <span class="param-type param-array-format integer">Array[string]</span> <div class="redoc-markdown-block">The identifiers of the vulnerability categories to included in the report.</div> </div> <div class="property-info"> <span class="property-name">excluded</span> <span class="param-type param-array-format integer">Array[string]</span> <div class="redoc-markdown-block">The identifiers of the vulnerability categories to exclude in the report.</div> </div> </div> <div class="property-info"> <span class="property-name">severity</span> <span class="param-type">string</span> <div class="param-enum"> <span class="param-enum-value string">"all"</span> <span class="param-enum-value string">"critical"</span> <span class="param-enum-value string">"critical-and-severe"</span> </div> <div class="redoc-markdown-block">The vulnerability severities to include in the report.</div> </div> <div class="property-info"> <span class="property-name">statuses</span> <span class="param-type param-array-format integer">Array[string]</span> <div class="param-enum"> <span class="param-enum-value string">"vulnerable"</span> <span class="param-enum-value string">"vulnerable-version"</span> <span class="param-enum-value string">"potentially-vulnerable"</span> <span class="param-enum-value string">"vulnerable-and-validated"</span> </div> <div class="redoc-markdown-block">The vulnerability statuses to include in the report. If <code>"vulnerable-and-validated"</code> is selected no other values can be specified. </div> </div> </div> The following filter elements may be defined for non-templatized report formats: | Format | Categories | Severity | Statuses | | ------------------------------------- |:--------------:|:----------:|:----------:| | `arf-xml` | | | | | `csv-export` | &check; | &check; | &check; | | `cyberscope-xml` | | | | | `nexpose-simple-xml` | &check; | &check; | | | `oval-xml` | | | | | `qualys-xml` | &check; | &check; | | | `scap-xml` | &check; | &check; | | | `sql-query` | &check; | &check; | &check; | | `xccdf-csv` | | | | | `xccdf-xml` | &check; | &check; | | | `xml-export` | &check; | &check; | &check; | | `xml-export-v2` | &check; | &check; | &check; | The following filter elements may be defined for templatized report formats: | Template | Categories | Severity | Statuses | | --------------------------------------- |:--------------:|:----------:|:----------:| | `audit-report` | &check; | &check; | | | `baseline-comparison` | | | | | `basic-vulnerability-check-results` | &check; | &check; | &check; | | `executive-overview` | | | | | `highest-risk-vulns` | | | | | `pci-attestation-v12` | | | | | `pci-executive-summary-v12` | | | | | `pci-vuln-details-v12` | | | | | `policy-details` | &check; | &check; | &check; | | `policy-eval` | | | | | `policy-summary` | &check; | &check; | &check; | | `prioritized-remediations` | &check; | &check; | &check; | | `prioritized-remediations-with-details` | &check; | &check; | &check; | | `r7-discovered-assets` | &check; | &check; | &check; | | `r7-vulnerability-exceptions` | &check; | &check; | &check; | | `remediation-plan` | &check; | &check; | | | `report-card` | &check; | &check; | | | `risk-scorecard` | &check; | &check; | &check; | | `rule-breakdown-summary` | &check; | &check; | &check; | | `top-policy-remediations` | &check; | &check; | &check; | | `top-policy-remediations-with-details` | &check; | &check; | &check; | | `top-riskiest-assets` | &check; | &check; | &check; | | `top-vulnerable-assets` | &check; | &check; | &check; | | `vulnerability-trends` | &check; | &check; | &check; |
    - `categories` ReportConfigCategoryFilters — Vulnerability categories to include or exclude. Only `included` or `excluded` may be specified, but not both.
      - `excluded` string[] — The vulnerability categories to exclude. Defaults to no categories.
      - `included` string[] — The vulnerability categories to include. Defaults to all categories.
      - `links` Link[], required — Hypermedia links to corresponding or related resources.
        - `deprecation` string
        - `href` string — A hypertext reference, which is either a URI (see <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>) or URI template (see <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc6570">RFC 6570</a>).
        - `hreflang` string
        - `media` string
        - `rel` string — The link relation type. This value is one from the <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc5988#section-6.2">Link Relation Type Registry</a> or is the type of resource being linked to.
        - `title` string
        - `type` string
    - `severity` 'all' | 'critical' | 'critical-and-severe' — The vulnerability severities to include. Defaults to `all`.
    - `statuses` string[] — The vulnerability statuses to include. Defaults to [ `vulnerable`, `vulnerable-version`, `potentially-vulnerable` ].
  - `format` 'sql-query' | 'arf-xml' | 'csv-export' | 'cyberscope-xml' | 'nexpose-simple-xml' | 'oval-xml' | 'qualys-xml' | 'scap-xml' | 'xccdf-csv' | 'xccdf-xml' | 'xml-export' | 'xml-export-v2' | 'pdf' | 'rtf' | 'xml' | 'html' | 'text' — The output format of the report. The format will restrict the available templates and parameters that can be specified.
  - `frequency` ReportFrequency — The recurring frequency with which to generate the report.
    - `nextRuntimes` string[] — The next scheduled run-times for generation of the report when type is `schedule`.
    - `repeat` ReportRepeat — How often the report generates when type is `schedule`.
      - `dayOfWeek` 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' — The day of the week the scheduled task should repeat. This property only applies to schedules with a `every` value of `"day-of-month"`.
      - `every` 'hour' | 'day' | 'week' | 'date-of-month' | 'day-of-month', required — The frequency schedule repeats. Each value represents a different unit of time and is used in conjunction with the property `interval`. For example, a schedule can repeat hourly, daily, monthly, etc. The following table describes each supported value: | Value | Description | | ---------- | ---------------- | | hour | Specifies the schedule repeats in hourly increments. | | day | Specifies the schedule repeats in daily increments. | | week | Specifies the schedule repeats in weekly increments. | | date-of-month | Specifies the schedule repeats nth day of the `interval` month. Requires the property `dateOfMonth` to be specified. For example, if `dateOfMonth` is `17` and the `interval` is `2`, then the schedule will repeat every 2 months on the 17th day of the month. | | day-of-month | Specifies the schedule repeats on a monthly interval but instead of a specific date being specified, the day of the week and week of the month are specified. Requires the properties `dayOfWeek` and `weekOfMonth` to be specified. For example, if `dayOfWeek` is `"friday"`, `weekOfMonth` is `3`, and the `interval` is `4`, then the schedule will repeat every 4 months on the 3rd Friday of the month. |
      - `interval` integer, required — The interval time the schedule should repeat. The is depends on the value set in `every`. For example, if the value in property `every` is set to `"day"` and `interval` is set to `2`, then the schedule will repeat every 2 days.
      - `weekOfMonth` integer — The week of the month the scheduled task should repeat. For This property only applies to schedules with a `every` value of `"day-of-month"`. Each week of the month is counted in 7-day increments. For example, week 1 consists of days 1-7 of the month while week 2 consists of days 8-14 of the month and so forth.
    - `start` string, date-time — When the report starts generating when type is `schedule`.
    - `type` 'scan' | 'schedule' | 'none' — The frequency to generate the report. `schedule` generates the report every scheduled time interval, and requires the `repeat` and `start` properties to be specified. `scan` generates the report after any scan of any element in the scope of the report. `none` does not generate the report automatically. Defaults to `none`.
  - `id` integer — The identifier of the report.
  - `language` string — The locale (language) in which the report is generated
  - `links` Link[] — Hypermedia links to corresponding or related resources.
    - `deprecation` string
    - `href` string — A hypertext reference, which is either a URI (see <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc3986">RFC 3986</a>) or URI template (see <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc6570">RFC 6570</a>).
    - `hreflang` string
    - `media` string
    - `rel` string — The link relation type. This value is one from the <a target="_blank" rel="noopener noreferrer" href="https://tools.ietf.org/html/rfc5988#section-6.2">Link Relation Type Registry</a> or is the type of resource being linked to.
    - `title` string
    - `type` string
  - `name` string — The name of the report.
  - `organization` string — The organization used for a XCCDF XML report. Only used when the format is `"xccdf-xml"`.
  - `owner` integer — The identifier of the report owner.
  - `policies` object[] — If the template is `rule-breakdown-summary`, `top-policy-remediations`, or `top-policy-remediations-with-details` the identifiers of the policies to report against.
  - `policy` object — The identifier of the policy
  - `query` string — SQL query to run against the Reporting Data Model. Only used when the format is `"sql-query"`.
  - `range` RangeResource — If the template is `vulnerability-trends`, `r7-vulnerability-exceptions`, or `r7-discovered-assets` the date range to trend over.
    - `every` 'day' | 'month' | 'year' — If `from` is a custom date the interval amount between reporting periods.
    - `from` object — The start date of the trend, which can either be a duration or a specific date and time.
    - `interval` integer — If `from` is a custom date the interval between reporting periods.
    - `to` string, date — The end date of the trend (empty if `from` is a duration).
  - `remediation` RemediationResource — If the template is `prioritized-remediations`, `prioritized-remediations-with-details`, `top-policy-remediations`, or `top-policy-remediations-with-details` the remediation display settings.
    - `solutions` integer — The number of remediations to display.
    - `sort` 'assets' | 'vulnerabilities' | 'malware_kits' | 'exploits' | 'riskscore' — The attribute to prioritize remediation impact. Only supported for the `prioritized-remediations` and `prioritized-remediations-with-details` templates.
  - `riskTrend` RiskTrendResource — Configuration details for risk trending output.
    - `allAssets` RiskTrendAllAssetsResource — Trend settings for a trend across all assets in the scope of the report.
      - `total` boolean — Includes a trend for the total risk of all assets.
      - `trend` 'average-risk' | 'number-of-assets' | 'none' — Whether to include a trend for average risk of all assets or the total number of assets.
    - `assetGroupMembership` 'historical' | 'generation' — Whether all assets tagged in the history of deployment or those tagged as of the report generation time are to be included.
    - `assetGroups` 'average' | 'total' — Whether to include a trend for the 5 highest-risk asset groups in the scope of the report (either the average or total risk). Only allowed if asset groups are specified in the report scope.
    - `assets` boolean — Whether to include a trend for the 5 highest-risk assets in the scope of the report.
    - `from` object — The start date of the risk trend, which can either be a duration or a specific date and time.
    - `sites` 'average' | 'total' — Whether to include a trend for the 5 highest-risk asset groups in the scope of the report (either the average or total risk). Only allowed if asset groups are specified in the report scope.
    - `tagMembership` 'historical' | 'generation' — Whether all assets tagged in the history of deployment or those tagged as of the report generation time are to be included.
    - `tags` 'average' | 'total' — Whether to include a trend for the 5 highest-risk asset groups in the scope of the report (either the average or total risk). Only allowed if asset groups are specified in the report scope.
    - `to` string, date — The end date of the risk trend (empty if `from` is a duration).
  - `scope` ReportConfigScopeResource — The scope of the report. Scope is an object that has the following properties that vary by format and template: <div class="properties"> <div class="property-info"> <span class="property-name">assets</span> <span class="param-type param-array-format integer">Array[integer &lt;int32&gt;]</span> <div class="redoc-markdown-block">The identifiers of the assets to report on.</div> </div> <div class="property-info"> <span class="property-name">sites</span> <span class="param-type param-array-format integer">Array[integer &lt;int32&gt;]</span> <div class="redoc-markdown-block">The identifiers of the sites to report on.</div> </div> <div class="property-info"> <span class="property-name">assetGroups</span> <span class="param-type param-array-format integer">Array[integer &lt;int32&gt;]</span> <div class="redoc-markdown-block">The identifiers of the asset to report on.</div> </div> <div class="property-info"> <span class="property-name">tags</span> <span class="param-type param-array-format integer">Array[integer &lt;int32&gt;]</span> <div class="redoc-markdown-block">The identifiers of the tag to report on.</div> </div> <div class="property-info"> <span class="property-name">scan</span> <span class="param-type param-array-format integer">integer &lt;int32&gt;</span> <div class="redoc-markdown-block">The identifier of the scan to report on.</div> </div> </div> The following scope elements may be defined for non-templatized report formats: | Format | Assets | Sites | Asset Groups | Tags | Scan | | ------------------------------------- |:----------:|:-------:|:------------:|:-------:|:---------:| | `arf-xml` | &check; | &check; | &check; | &check; | | | `csv-export` | &check; | &check; | &check; | &check; | &check; | | `cyberscope-xml` | &check; | &check; | &check; | &check; | &check; | | `nexpose-simple-xml` | &check; | &check; | &check; | &check; | &check; | | `oval-xml` | &check; | &check; | &check; | &check; | | | `qualys-xml` | &check; | &check; | &check; | &check; | &check; | | `scap-xml` | &check; | &check; | &check; | &check; | &check; | | `sql-query` | &check; | &check; | &check; | &check; | &check; | | `xccdf-csv` | &check; | | | | | | `xccdf-xml` | &check; | &check; | &check; | &check; | &check; | | `xml-export` | &check; | &check; | &check; | &check; | &check; | | `xml-export-v2` | &check; | &check; | &check; | &check; | &check; | The following scope elements may be defined for templatized report formats: | Template | Assets | Sites | Asset Groups | Tags | Scan | | -----------------------------------------|:----------:|:-------:|:------------:|:-------:|:-------:| | `audit-report` | &check; | &check; | &check; | &check; | &check; | | `baseline-comparison` | &check; | &check; | &check; | &check; | | | `basic-vulnerability-check-results` | &check; | &check; | &check; | &check; | &check; | | `executive-overview` | &check; | &check; | &check; | &check; | | | `highest-risk-vulns` | &check; | &check; | &check; | &check; | | | `pci-attestation-v12` | &check; | &check; | &check; | &check; | &check; | | `pci-executive-summary-v12` | &check; | &check; | &check; | &check; | &check; | | `pci-vuln-details-v12` | &check; | &check; | &check; | &check; | &check; | | `policy-details` | &check; | &check; | &check; | &check; | | | `policy-eval` | &check; | &check; | &check; | &check; | | | `policy-summary` | &check; | &check; | &check; | &check; | &check; | | `prioritized-remediations` | &check; | &check; | &check; | &check; | &check; | | `prioritized-remediations-with-details` | &check; | &check; | &check; | &check; | &check; | | `r7-discovered-assets` | &check; | &check; | &check; | &check; | &check; | | `r7-vulnerability-exceptions` | &check; | &check; | &check; | &check; | &check; | | `remediation-plan` | &check; | &check; | &check; | &check; | &check; | | `report-card` | &check; | &check; | &check; | &check; | &check; | | `risk-scorecard` | &check; | &check; | &check; | &check; | | | `rule-breakdown-summary` | &check; | &check; | &check; | &check; | | | `top-policy-remediations` | &check; | &check; | &check; | &check; | | | `top-policy-remediations-with-details` | &check; | &check; | &check; | &check; | | | `top-riskiest-assets` | &check; | &check; | &check; | &check; | &check; | | `top-vulnerable-assets` | &check; | &check; | &check; | &check; | &check; | | `vulnerability-trends` | &check; | &check; | &check; | &check; | | If a report supports specifying a scan as the scope and a scan is specified, no other scope elements may be defined. In all other cases as many different types of supported scope elements can be specified in any combination. All reports except the `sql-query` format require at least one element to be specified as the scope.
    - `assetGroups` integer[] — Identifiers of the asset groups in the scope of the report.
    - `assets` integer[] — Identifiers of the assets in the scope of the report.
    - `scan` object — The identifier of the scan.
    - `sites` integer[] — Identifiers of the sites in the scope of the report.
    - `tags` integer[] — Identifiers of the tags in the scope of the report.
  - `storage` ReportStorage — The additional storage location and path.
    - `location` string — The location to storage an additional copy of the report. This is a sub-path post-fixed to `$(install_dir)/nsc/reports/$(user)/`. Variables such as `$(report_name)`, `$(date)`, and `$(time)` may be used to generate the directory structure.
    - `path` string — The full path to the additional copy storage location.
  - `template` string — The template for the report (only required if the format is templatized).
  - `timezone` string — The timezone the report generates in, such as `"America/Los_Angeles"`.
  - `users` integer[] — The identifiers of the users granted explicit access to the report.
  - `version` string — The version of the report Data Model to report against. Only used when the format is `"sql-query"`.

## Response `200`

OK

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/rapid7/apis/rapid7-vm-api.md) · [All operations](https://skmtc.net/rapid7/apis/rapid7-vm-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rapid7/rapid7-vm-api/versions/3a8197c22d71/schema)