# API

## 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
```json
{
  "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](#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
```json
{
    "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
```json
{
  "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](https://fontawesome.com) icon name | 
| IconColor | The icon color in hex format (example: '#0D80D8') | 
| Links     | Links to other resources.  See [REST API Links](https://octopus.com/docs/octopus-rest-api#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
```json
{
    "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
```json
{
  "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
```json
{
  "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 |