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 |