Octopus Deploy Documentation

API

Last updated

The DevOps Insights feature is still in development. You can use this API; however, please keep in mind that it could change at anytime.

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 belong to the same stream if they have the same project, channel, environment and tenant.

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

Need support? We're here to help.