Insights Reports API
Get a list of Insights reports
GET: /api/{spaceId}/insights/reports
Returns a paginated list of the Insights reports in the supplied Octopus Deploy space.
Parameters
Name Description spaceId Id of the space skip Number of items to skip. Defaults to zero take Number of items to take (i.e. the page size). Defaults to 30
Sample response
{ "ItemType" : "InsightsReport" , "TotalResults" : 2 , "ItemsPerPage" : 30 , "NumberOfPages" : 1 , "LastPageNumber" : 0 , "Items" : [ { "Id" : "InsightsReports-1" , "SpaceId" : "Spaces-1" , "Name" : "High Volume Report" , "Description" : "High volume tenanted deployments report" , "ProjectGroupIds" : [ "ProjectGroups-1" , "ProjectGroups-2" ], "ProjectIds" : [ "Projects-1" , "Projects-2" ], "TenantIds" : [ "Tenants-1" , "Tenants-2" , "Tenants-3" ], "TenantTags" : [ "Deployment Group/Group A" , "Deployment Group/Group B" , "Deployment Group/Group C" , "Location/Australia" , "Location/Asia" , "Location/Europe" , "Location/US" ], "TenantMode" : "TenantedAndUntenanted" , "EnvironmentGroups" : [ { "Name" : "Test" , "Environments" : [ "Environments-1" , "Environments-2" ] }, { "Name" : "Internal" , "Environments" : [ "Environments-3" , "Environments-4" ] }, { "Name" : "Production" , "Environments" : [ "Environments-5" , "Environments-6" ] } ], "TimeZone" : "UTC" , "IconId" : "map-signs" , "IconColor" : "#3CA4F3" , "Links" : { "Self" : "/api/Spaces-1/insights/reports/InsightsReports-1" , "Logo" : "/api/Spaces-1/insights/reports/InsightsReports-1/logo" } } ], "Links" : { "Self" : "/api/Spaces-1/insights/reports?skip=0&take=30" , "Template" : "/api/Spaces-1/insights/reports{?skip,take}" , "Page.All" : "/api/Spaces-1/insights/reports?skip=0&take=2147483647" , "Page.Current" : "/api/Spaces-1/insights/reports?skip=0&take=30" , "Page.Last" : "/api/Spaces-1/insights/reports?skip=0&take=30" } } Properties
Property Description ItemType The type of resource - for Insights Reports, this will always be “InsightsReport” TotalResults The total number of reports ItemsPerPage The number of reports per page NumberOfPages The total number of pages LastPageNumber The number of the last page of reports, counting from zero Items An array of the reports returned for the current page. See the section Get a specific Insights Report for details of the report structure Links Links to other resources. See REST API Links https://octopus.com/docs/octopus-rest-api#api-links
Create an Insights report
POST: /api/{spaceId}/insights/reports
Create a new Insights report.
Parameters
Name Description spaceId Id of the space
Request Body
The request body is in JSON format.
Sample request
{ "SpaceId" : "Spaces-1" , "Name" : "High Volume Report" , "Description" : "High volume tenanted deployments report" , "ProjectGroupIds" : [ "ProjectGroups-1" , "ProjectGroups-2" ], "ProjectIds" : [ "Projects-1" , "Projects-2" ], "TenantIds" : [ "Tenants-1" , "Tenants-2" , "Tenants-3" ], "TenantTags" : [ "Deployment Group/Group A" , "Deployment Group/Group B" , "Deployment Group/Group C" , "Location/Australia" , "Location/Asia" , "Location/Europe" , "Location/US" ], "TenantMode" : "TenantedAndUntenanted" , "EnvironmentGroups" : [ { "Name" : "Test" , "Environments" : [ "Environments-1" , "Environments-2" ] }, { "Name" : "Internal" , "Environments" : [ "Environments-3" , "Environments-4" ] }, { "Name" : "Production" , "Environments" : [ "Environments-5" , "Environments-6" ] } ], "TimeZone" : "UTC" } Properties
Property Description SpaceId Required The id of the space to contain the report Name Required The name of the report Description Optional The description of the report ProjectGroupIds Optional An array of the project group ids to be included in the report ProjectIds Optional An array of the project ids to be included in the report TenantIds Optional An array of the tenant ids to be included in the report TenantTags Optional An array of the tenant tags to be associated with this report TenantMode Optional Indicates what types of deployments will be contributing to this report. May be TenantedAndUntenanted, Tenanted, or Untenanted EnvironmentGroups Optional An array of the environment groups to be included in this report. See below for details TimeZone Optional The timezone to be used in the report. Must be either a Windows or IANA (Tzdb) timezone
EnvironmentGroups Properties
Property Description Name Required The name of the environment group. Must be unique per report Environments Required An array of the ids of the environments to include in the group
Get a specific Insights report
GET: /api/{spaceId}/insights/reports/{reportId}
Retrieves an existing Insights report.
Parameters
Name Description spaceId Id of the space containing the report reportId Id of the report to retrieve
Sample response
{ "Id" : "InsightsReports-1" , "SpaceId" : "Spaces-1" , "Name" : "High Volume Report" , "Description" : "High volume tenanted deployments report" , "ProjectGroupIds" : [ "ProjectGroups-1" , "ProjectGroups-2" ], "ProjectIds" : [ "Projects-1" , "Projects-2" ], "TenantIds" : [ "Tenants-1" , "Tenants-2" , "Tenants-3" ], "TenantTags" : [ "Deployment Group/Group A" , "Deployment Group/Group B" , "Deployment Group/Group C" , "Location/Australia" , "Location/Asia" , "Location/Europe" , "Location/US" ], "TenantMode" : "TenantedAndUntenanted" , "EnvironmentGroups" : [ { "Name" : "Test" , "Environments" : [ "Environments-1" , "Environments-2" ] }, { "Name" : "Internal" , "Environments" : [ "Environments-3" , "Environments-4" ] }, { "Name" : "Production" , "Environments" : [ "Environments-5" , "Environments-6" ] } ], "TimeZone" : "UTC" , "IconId" : null , "IconColor" : null , "Links" : { "Self" : "/api/Spaces-1/insights/reports/InsightsReports-1" , "Logo" : "/api/Spaces-1/insights/reports/InsightsReports-1/logo" } } Properties
Property Description Id The id of the Insights report SpaceId The id of the space containing the report Name The name of the report Description The description of the report ProjectGroupIds An array of the project group ids included in the report ProjectIds An array of the project ids included in the report TenantIds An array of the tenant ids included in the report TenantTags An array of the tenant tags associated with this report TenantMode Indicates what types of deployments contributed to this report. May be TenantedAndUntenanted, Tenanted, or Untenanted EnvironmentGroups An array of the environment groups included in this report TimeZone The timezone used in the report, in Windows timezone format IconId A Font Awesome icon name IconColor The icon color in hex format (example: ‘#0D80D8’) Links Links to other resources. See REST API Links
Update an Insights report
PUT: /api/{spaceId}/insights/reports/{reportId}
Updates an existing Insights report.
Parameters
Name Description spaceId Id of the space containing the report reportId The id of the Insights report to update
Request Body
The request body is in JSON format.
Sample request
{ "SpaceId" : "Spaces-1" , "Id" : "InsightsReports-1" , "Name" : "High Volume Report" , "Description" : "High volume tenanted deployments report" , "ProjectGroupIds" : [ "ProjectGroups-1" , "ProjectGroups-2" ], "ProjectIds" : [ "Projects-1" , "Projects-2" ], "TenantIds" : [ "Tenants-1" , "Tenants-2" , "Tenants-3" ], "TenantTags" : [ "Deployment Group/Group A" , "Deployment Group/Group B" , "Deployment Group/Group C" , "Location/Australia" , "Location/Asia" , "Location/Europe" , "Location/US" ], "TenantMode" : "TenantedAndUntenanted" , "EnvironmentGroups" : [ { "Name" : "Test" , "Environments" : [ "Environments-1" , "Environments-2" ] }, { "Name" : "Internal" , "Environments" : [ "Environments-3" , "Environments-4" ] }, { "Name" : "Production" , "Environments" : [ "Environments-5" , "Environments-6" ] } ], "TimeZone" : "UTC" } Properties
Property Required Description SpaceId Required The id of the space containing the report. Id Required The id of the report to be updated. Name Required The name of the report. Description Optional The description of the report. ProjectGroupIds Optional An array of the project group ids to be included in the report. ProjectIds Optional An array of the project ids to be included in the report. TenantIds Optional An array of the tenant ids to be included in the report. TenantTags Optional An array of the tenant tags to be associated with this report. TenantMode Optional Indicates what types of deployments will be contributing to this report. May be TenantedAndUntenanted, Tenanted, or Untenanted. EnvironmentGroups Optional An array of the environment groups to be included in this report. TimeZone Optional The timezone to be used in the report. Must be either a Windows or IANA (Tzdb) timezone.
Delete an insights report
DELETE: /api/{spaceId}/insights/reports/{reportId}
Deletes an existing Insights report.
Parameters
Name Description spaceId Id of the space containing the report reportId The id of the Insights report to delete
Get deployment level insights metrics
GET: /api/{spaceId}/insights/reports/{reportId}/deployments
Returns the streams of deployments for the given report. A stream is a sequence of deployments used to calculate metrics. Includes all the deployments with their Insights metrics for the last 12 whole months and this month, for the specified report.
Parameters
Name Description spaceId Id of the space containing the report reportId The id of the Insights report for which to retrieve details
Sample response
{ "ReportName" : "High Volume Report" , "Streams" : [ { "ProjectId" : "Projects-1" , "ProjectName" : "My Project 1" , "ChannelId" : "Channels-1" , "ChannelName" : "My Channel 1" , "EnvironmentId" : "Environments-1" , "EnvironmentName" : "Test Environment" , "TenantId" : "Tenants-1" , "TenantName" : "Australia East" , "Deployments" : [ { "Id" : "Deployments-1" , "ReleaseVersion" : "2022.3.1" , "TaskState" : "Success" , "CompletedTime" : "2022-08-18T14:28:15.9395818Z" , "HadGuidedFailure" : false , "LeadTime" : "1:12:39.41517" , "LeadTimeCalculatedFromVersion" : "2022.3.0" , "TimeSincePreviouslySuccessfulDeployment" : null , "PreviousSuccessfulDeploymentId" : null , "TimeToRecovery" : null , "DeploymentsUntilRecovery" : null , "RecoveredFromFailedDeploymentId" : null , "RecoveredFromFailedReleaseVersion" : null }, { "Id" : "Deployments-2" , "ReleaseVersion" : "2022.3.1" , "TaskState" : "Success" , "CompletedTime" : "2022-08-18T15:28:15.9395818Z" , "HadGuidedFailure" : false , "LeadTime" : "0:01:00.0" , "LeadTimeCalculatedFromVersion" : "2022.3.1" , "TimeSincePreviouslySuccessfulDeployment" : "0:01:00.0" , "PreviousSuccessfulDeploymentId" : "Deployments-1" , "TimeToRecovery" : null , "DeploymentsUntilRecovery" : null , "RecoveredFromFailedDeploymentId" : null , "RecoveredFromFailedReleaseVersion" : null } ] } ] } Properties
Property Description ReportName The name of the report Streams An array of streams. A stream is a sequence of deployments used to calculate metrics
Streams properties
Property Description ProjectId The id of the project for this stream. ProjectName The name of the project for this stream. Will be null if you don’t have access to this project. ChannelId The id of the channel for this stream. ChannelName The name of the channel for this stream. Will be null if you don’t have access to this channel. EnvironmentId The id of the environment for this stream. EnvironmentName The name of the environment for this stream. Will be null if you don’t have access to this environment. TenantId The id of the tenant for this stream. TenantName The name of the tenant for this stream. Will be null if you don’t have access to this tenant. Deployments An array of the deployments in this stream.
Deployments properties
Property Description Id The id of the deployment. ReleaseVersion The version of the release that was deployed. TaskState Indicates the state of the deployment task. CompletedTime When the deployment completed. HadGuidedFailure Whether or not the deployment had a guided failure. LeadTime The lead time of the deployment. LeadTimeCalculatedFromVersion The version of the release containing the earliest change included in the deployment. TimeSincePreviouslySuccessfulDeployment The time period since the previous successful deployment. PreviousSuccessfulDeploymentId The id of the previous successful deployment. TimeToRecovery The period of time taken to recover from one or more failed deployments, until this deployment (if successful). DeploymentsUntilRecovery Number of attempted deployments until this deployment occurred (if successful). RecoveredFromFailedDeploymentId The id of the first failed deployment in a series of one or more failed deployments. RecoveredFromFailedReleaseVersion The first version which had a failed deployment in a series of one or more failed deployments.
Get deployment level aggregated insights metrics
GET: /api/{spaceId}/insights/reports/{reportId}/metrics
Parameters
Name Description spaceId Id of the space containing the report. reportId The id of the Insights report to retrieve details for. split How to split the metrics. Should be ‘None’, ‘Project’, ‘ProjectGroup’, ‘Environment’, ‘EnvironmentGroup’, ‘Tenant’, ‘TenantTagSet’. tenantTagSetId If TenantTagSet is chosen for Split, this is required, otherwise it is ignored. It is the tag set to split on. timeRange The time period to get data for. Should be ‘LastMonth’, ‘LastQuarter’, or ‘LastYear’ granularity The data grouping granularity, defaults to weekly if not supplied. Should be ‘Monthly’, ‘Weekly’, or ‘Daily’.
Sample response
{ "Series" : [ { "Name" : "All" , "Intervals" : [ { "StartOfInterval" : "2022-06-05" , "NumberOfSuccessfulDeployments" : 247 , "LeadTime" : { "Count" : 243 , "Mean" : "-2:32:31.0" , "Median" : "3:17:51.0" , "Min" : "-426:53:44.0" , "Max" : "93:32:33.0" , "NinetyFifth" : "28:15:32.0" }, "DeploymentFailureRate" : { "Successful" : 247 , "DeploymentFailure" : 8 , "SuccessfulButHadGuidedFailure" : 0 , "Total" : 255 , "Failed" : 8 , "Rate" : 0.03137 }, "TimeSincePreviousDeployment" : { "Count" : 241 , "Mean" : "2:12:32.0" , "Median" : "1:21:56.0" , "Min" : "0:10:00.0" , "Max" : "12:40:01.0" , "NinetyFifth" : "7:29:43.0" }, "MeanTimeToRecovery" : { "Count" : 8 , "Mean" : "5:26:50.0" , "Median" : "2:17:17.0" , "Min" : "0:41:12.0" , "Max" : "17:11:09.0" , "NinetyFifth" : "14:55:01.0" }, "DeploymentsUntilRecovery" : { "Count" : 8 , "Mean" : 1.0 , "Median" : 1.0 , "Min" : 1.0 , "Max" : 1.0 , "NinetyFifth" : 1.0 } } ] } ] } Properties
Property Description Series An array of the series returned, each containing the values for the split provided
Series Properties
Property Description Name The name of the series. If no split is provided, this will be ‘All’ Intervals An array of the time periods containing the data returned
LeadTime, TimeSincePreviousDeployment, MeanTimeToRecovery and DeploymentsUntilRecovery Properties
Property Description Count The number of deployments aggregated in the current metric for the interval Mean The mean value for the current metric for the interval Median The median value for the current metric for the interval Min The minimum value for the current metric for the interval Max The maximum value for the current metric for the interval NinetyFifth The 95th percentile value for the current metric for the interval
DeploymentFailureRate Properties
Property Description Successful The number of successful deployments for the interval DeploymentFailure The number of deployments with failures SuccessfulButHadGuidedFailure The number of deployments which succeeded, but only with guided failures Total The total number of deployments for the interval Failed The number of failed deployments for the interval Rate The percentage of failed deployments to successful deployments for the interval
Help us continuously improve Please let us know if you have any feedback about this page.
Send feedback
Previous article CSV download
Next article Overview