Reporting APIs

Reporting APIs allow users to generate application reports. Instead of first exporting generated data, such as traffic flows, and then using other tools to create reports, users can now use built-in reports.

Users can request one-time or recurring reports, specify time ranges, as well as report types.

Reporting APIs belong to several groups based on their use:

There is also a VEN Dashboard to help you visualize VEN statistics:

Reporting API Types

Reporting Schedules

These APIs allow the Global Organization Administrator (this_global_org_user) to manage report schedules.

Each report can be generated once or recurring, where the recurrence is specified during report configuration.

The default time range is 30 days, and other possible values are 1 day, 7 days, 14 days, 30 days, 60 days, and 90 days.

Functionality	HTTP	URI
Returns a collection of report schedules.	`GET`	`[api_version][org_href]/report_schedule`
Returns a scheduled report for the provided UUID.	`GET`	`[api_version][org_href]/report_schedule/:report_schedule_id`
Updates a report schedule for the provided UUID.	`PUT`	`[api_version][org_href]/report_schedule/:report_schedule_id`
Create a new report schedule.	`POST`	`[api_version][org_href]/report_schedule`
Deletes a report schedule for the provided UUID.	`GET`	`[api_version][org_href]/report_schedule/:report_schedule_id`

Request Parameters

Parameter	Description	Parameter Type	Format
`org_id`	Organization	path	Integer
`report_schedule_id`	UUID of the report schedule	Sring	date/time

Response Properties

Parameter	Description	Parameter Type
`href`	Report Schedule URI	URI, required
`report_template`	Template for the report	Object, required
`report_generation_frequency`	How often to generate a report: in addition to daily, `weekly`, `monthly`, and `quarterly` reports, you can schedule to receive the report only `once`.	String
`report_parameters`	Any specific parameters required for this report template `executive_summary_report_params.schema.json` `traffic_flow_report_params.schema.json` `explorer_report_params.schema.json` `ves_report_params.schema.json`	Object, required
`created_at`	Timestamp (rfc3339 timestamp) in UTC when this report schedule was created	String
`created_by`	The URI of the user who created this report schedule	URI
`updated_at`	Timestamp (rfc3339 timestamp) when this report schedule was last updated.",	String
`updated_by`	The URI of the user who updated this report schedule	URI

Defining Report Schedule Query

To define the query for report schedules, reference the required schemas (explained in Schemas to Define a Report).

executive_summary_report_params.schema.json

```
traffic_flow_report_params.schema.json
```
```
report_app_groups.schema.json
```
```
custom_date_range.schema.json
```

```
ves_report_params.schema.json
```

Report Templates

These API's allow the Global Organization Administrator (this_global_org_user) to manage report templates. In each report template, they can specify type, time range, recurrence, and suitable parameters for the report type.

Functionality	HTTP	URI
Lists the collection of all available report templates for this user and organization.	`GET`	`[api_version][org_href]/report_templates`
This API is used to enable/disable a specific report type, which can be done only by the organization administrator.	`PUT`	`[api_version][org_href]/report_templates`

Properties for Report Templates

Property	Description	Parameter Type	Required
`href`	Report Template URI	String	Yes
`name`	The Display name for this report template maxLength: 255	String	Yes
`report_parameters`	Any specific parameters required for this report template to define one of the report types, using on of the listed schemas: `executive_summary_report_params.schema.json` `traffic_flow_report_params.schema.json` `explorer_report_params.schema.json` `ves_report_params.schema.json`	Object	Yes

Property

Description

Parameter Type

Required

href

Report Template URI

String

Yes

name

The Display name for this report template

maxLength: 255

String

Yes

report_parameters

Any specific parameters required for this report template to define one of the report types, using on of the listed schemas:

executive_summary_report_params.schema.json
traffic_flow_report_params.schema.json
explorer_report_params.schema.json
ves_report_params.schema.json

Object

Yes

Defining Report Templates Query

To define the query for report templates, reference the required schemas (explained in Schemas to Define a Report).

On-Demand Reports

The user authorized as the Global Organization Administrator (this_global_org_user) can download various kinds of reports, create them on-demand, or add the property report_format to determine the format in which the report will be generated.

Functionality	HTTP	URI
Returns a collection of reports.	`GET`	`[api_version][org_href]/reports`
Returns a report for the provided UUID.	`GET`	`[api_version][org_href]/reports/:report_id`
Downloads a specific report.	`GET`	`[api_version][org_href]/reports/:report_id/download`
Creates a new on-demand report.	`POST`	`[api_version][org_href]/reports`
Cancels a report if it's not yet completed/failed	`PUT`	`[api_version][org_href]/reports/:report_id`
Added a new property `report_format`, which determines the format in which the report should be generated	`POST`	`[api_version][org_href]/reports_schedules`
Added a new property `report_format` , which determines the format in which the report should be generated	`PUT`	`[api_version][org_href]/reports_schedules`

Parameters for On-Demand Reports

Parameter	Description	Parameter Type	Required
`href`		Integer	Yes
`report_template`	Template for the report	Object	Yes
`status`	Current status of this report	String	Yes
`report_parameters`	Any specific parameters required for this report template to define one of the report types using on of the listed schemas: `executive_summary_report_params.schema.json` `traffic_flow_report_params.schema.json` `explorer_report_params.schema.json` `ves_report_params.schema.json`	Object	Yes
`send_by_email`	Flag for whether to send user reports by email	Boolean	True/false
`progress_percentage`	Progress percentage for this report.	Integer	`"minimum": 0, "maximum": 100`

Report Settings

Report Settings define for how many days a report will be stored or persisted.

The user authorized as the Global Organization Administrator (this_global_org_user) can manage the report settings, list them or update.

Functionality	HTTP	URI
Get the report settings for an organization.	`GET`	`[api_version][org_href]/report_settings`
Updates the report settings for an organization.	`PUT`	`[api_version][org_href]/report_settings`

Schemas to Define a Report

These schemas are referenced and used to define the content of a report:

```
executive_summary_report_params.schema.json
```
Reports parameters for the executive summary report, such as report_time_range (Time range the report is built across) and references to report_time_range_definitions.schema.json#/definitions/custom_date_range or report_time_range_definitions.schema.json#/definitions/last_num_days.

```
traffic_flow_report_params.schema.json
```
Reports parameters for traffic flow query report.

```
report_app_groups.schema.json
```
This is the App Group Schema for reports.

```
custom_date_range.schema.json
```
Provides the time range the report is built across.

```
common legacy_workload_modes.schema.json
```
Provides the assigned labels summary with the label URI, as well as the key and value in the key-value pair.

```
report_time_range_definitions.schema.json
```
Provides the report parameters for the executive summary report, such as Start date for the range, End date for the range, and Last x number of days the report is built across.

```
labels_summary.schema.json
```
Provides the assigned labels summary with properties such as label URI, Key in key-value pair, and Value in key-value pair.
```
ves_report_params.schema.json
```
Provides report parameters for the new ves (vulnerability-exposure score ) report type.

Examples

Report Templates

GET /orgs/:xorg_id/report_templates

List the report templates for this user and organization.

[
	{
		"href": "/orgs/1/report_templates/executive_summary_report",
		"name": "Executive Summary",
		"report_parameters": {}
	},
	{
		"href": "/orgs/1/report_templates/traffic_flow_report",
		"name": "Traffic Flow Query",
		"report_parameters": {
			"app_groups": []
		}
	}
]

This request references the following two schemas (see Schemas to Define a Report).

executive_summary_report_params.schema.json
traffic_flow_report_params.schema.json

Report Schedules

POST /api/v2/orgs/1/report_schedules

Request to create a new report schedule:

{
	"report_template": {
		"href": "/orgs/1/report_templates/traffic_flow_report"
	},
	"name": "John's Traffic Flow Report - Quarterly",
	"report_generation_frequency": "quarterly",
	"report_parameters": {
		"report_time_range": {
			"last_num_days": 90
		},
		"app_groups": [
     
		]
	}
}

Response (201 created)

{
	"href": "/orgs/1/report_schedules/8a08b381-c8fe-4837-b9c6-071c70861369",
	"report_template": {
		"href": "/orgs/1/report_templates/traffic_flow_report"
	},
	"name": "John's Traffic Flow Report - Quarterly",
	"report_generation_frequency": "quarterly",
	"report_parameters": {
		"app_groups": [],
		"report_time_range": {
			"last_num_days": 90
		}
	}
}

On-demand Reports

POST /api/v2/orgs/1/reports

Request to create an on-demand report in the PDF format (report_format):

{
	"report_template": {
		"href": "/orgs/1/report_templates/executive_summary_report"
	},
	"description": "John's Executive Summary Report",
	"report_parameters": {
		"report_time_range": {
		"last_num_days": 30
		}
	},
	"report_format": "pdf"
}

Response

{
	"href": "/orgs/1/reports/be9b68ec-c35a-49bb-9400-f78c9950e321",
	"report_template": {
		"href": "/orgs/1/report_templates/executive_summary_report",
		"name": "Executive Summary Report"
	},
	"description": "John's Executive Summary Report",
	"created_at": "2021-01-15T05:45:27.130Z",
	"updated_at": "2021-01-15T05:45:27.130Z",
	"progress_percentage": 0,
	"generated_at": null,
	"status": "queued",
	"report_parameters": {
		"report_time_range": {
			"last_num_days": 30
		}
	},
	"created_by": {
		"href": "/users/1"
	},
	updated_by": {
		"href": "/users/1"
	}
}

Report Settings

GET /orgs/:xorg_id/settings/reports

Request to list report settings:

{
	"href": "/orgs/1/report_settings",
	"report_retention_days": 1,
	"enabled": true,
	"max_queued_reports": 25
}

REST APIs for 23.5

Reporting APIs

Reporting API Types

Reporting Schedules

Request Parameters

Response Properties

Defining Report Schedule Query

Report Templates

Properties for Report Templates

Defining Report Templates Query

On-Demand Reports

Parameters for On-Demand Reports

Report Settings

Schemas to Define a Report

Examples

Report Templates

Report Schedules

On-demand Reports

Report Settings

Search results