Reporting APIs Reference

This topic contains properties and examples for reporting APIs

Reporting Parameters and Properties

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

Property	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. These parameters are added as references: `executive_summary_report_params. schema.json` `traffic_flow_report_params. schema.json` `explorer_report_params. schema.json` `ves_report_params.schema.json` `ransomware_risk_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

Properties for Report Templates

Property	Description	Parameter Type	Required
`href`	Report Template URI	String	Yes
`name`	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 one 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` `ransomware_risk_report_params. schema.json`	Object	Yes

Property

Description

Parameter Type

Required

href

Report Template URI

String

Yes

name

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 one 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
ransomware_risk_report_params. schema.json

Object

Yes

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 one 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` `ransomware_risk_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 Templates Examples

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:

executive_summary_report_params.schema.json
traffic_flow_report_params.schema.json

Report Schedules Examples

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 24.5