# List insight groups

GET https://app.launchdarkly.com/api/v2/engineering-insights/insights/groups

List groups for which you are collecting insights

### Expanding the insight groups collection response

LaunchDarkly supports expanding the insight groups collection response to include additional fields.

To expand the response, append the `expand` query parameter and include the following:

* `scores` includes details on all of the scores used in the engineering insights metrics views for each group
* `environment` includes details on each environment associated with each group
* `metadata` includes counts of the number of insight groups with particular indicators, such as "excellent," "good," "fair," and so on.

For example, use `?expand=scores` to include the `scores` field in the response. By default, this field is **not** included in the response.


Reference: https://launchdarkly.com/docs/api/insights-scores-beta/get-insight-groups

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: LaunchDarkly REST API
  version: 1.0.0
paths:
  /api/v2/engineering-insights/insights/groups:
    get:
      operationId: get-insight-groups
      summary: List insight groups
      description: >
        List groups for which you are collecting insights


        ### Expanding the insight groups collection response


        LaunchDarkly supports expanding the insight groups collection response
        to include additional fields.


        To expand the response, append the `expand` query parameter and include
        the following:


        * `scores` includes details on all of the scores used in the engineering
        insights metrics views for each group

        * `environment` includes details on each environment associated with
        each group

        * `metadata` includes counts of the number of insight groups with
        particular indicators, such as "excellent," "good," "fair," and so on.


        For example, use `?expand=scores` to include the `scores` field in the
        response. By default, this field is **not** included in the response.
      tags:
        - subpackage_insightsScoresBeta
      parameters:
        - name: limit
          in: query
          description: >-
            The number of insight groups to return. Default is 20. Must be
            between 1 and 20 inclusive.
          required: false
          schema:
            type: integer
            format: int64
        - name: offset
          in: query
          description: >-
            Where to start in the list. Use this with pagination. For example,
            an offset of 10 skips the first ten items and then returns the next
            items in the list, up to the query `limit`.
          required: false
          schema:
            type: integer
            format: int64
        - name: sort
          in: query
          description: >-
            Sort flag list by field. Prefix field with <code>-</code> to sort in
            descending order. Allowed fields: name
          required: false
          schema:
            type: string
            format: string
        - name: query
          in: query
          description: Filter list of insights groups by name.
          required: false
          schema:
            type: string
            format: string
        - name: expand
          in: query
          description: 'Options: `scores`, `environment`, `metadata`'
          required: false
          schema:
            type: string
            format: string
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Insight groups collection response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsightGroupCollection'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationFailedErrorRep'
        '401':
          description: Invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorRep'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorRep'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedErrorRep'
servers:
  - url: https://app.launchdarkly.com
  - url: https://app.launchdarkly.us
components:
  schemas:
    Link:
      type: object
      properties:
        href:
          type: string
          description: The URL of the link
        type:
          type: string
          description: The type of the link
      title: Link
    ActionIdentifier:
      type: string
      title: ActionIdentifier
    ActionSpecifier:
      type: string
      title: ActionSpecifier
    AccessDeniedReasonEffect:
      type: string
      enum:
        - allow
        - deny
      description: Whether this statement should allow or deny actions on the resources.
      title: AccessDeniedReasonEffect
    AccessDeniedReason:
      type: object
      properties:
        resources:
          type: array
          items:
            type: string
          description: Resource specifier strings
        notResources:
          type: array
          items:
            type: string
          description: >-
            Targeted resources are the resources NOT in this list. The
            <code>resources</code> and <code>notActions</code> fields must be
            empty to use this field.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/ActionSpecifier'
          description: Actions to perform on a resource
        notActions:
          type: array
          items:
            $ref: '#/components/schemas/ActionSpecifier'
          description: >-
            Targeted actions are the actions NOT in this list. The
            <code>actions</code> and <code>notResources</code> fields must be
            empty to use this field.
        effect:
          $ref: '#/components/schemas/AccessDeniedReasonEffect'
          description: >-
            Whether this statement should allow or deny actions on the
            resources.
        role_name:
          type: string
      required:
        - effect
      title: AccessDeniedReason
    AccessDenied:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/ActionIdentifier'
        reason:
          $ref: '#/components/schemas/AccessDeniedReason'
      required:
        - action
        - reason
      title: AccessDenied
    AccessAllowedReasonEffect:
      type: string
      enum:
        - allow
        - deny
      description: Whether this statement should allow or deny actions on the resources.
      title: AccessAllowedReasonEffect
    AccessAllowedReason:
      type: object
      properties:
        resources:
          type: array
          items:
            type: string
          description: Resource specifier strings
        notResources:
          type: array
          items:
            type: string
          description: >-
            Targeted resources are the resources NOT in this list. The
            <code>resources</code> and <code>notActions</code> fields must be
            empty to use this field.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/ActionSpecifier'
          description: Actions to perform on a resource
        notActions:
          type: array
          items:
            $ref: '#/components/schemas/ActionSpecifier'
          description: >-
            Targeted actions are the actions NOT in this list. The
            <code>actions</code> and <code>notResources</code> fields must be
            empty to use this field.
        effect:
          $ref: '#/components/schemas/AccessAllowedReasonEffect'
          description: >-
            Whether this statement should allow or deny actions on the
            resources.
        role_name:
          type: string
      required:
        - effect
      title: AccessAllowedReason
    AccessAllowedRep:
      type: object
      properties:
        action:
          $ref: '#/components/schemas/ActionIdentifier'
        reason:
          $ref: '#/components/schemas/AccessAllowedReason'
      required:
        - action
        - reason
      title: AccessAllowedRep
    Access:
      type: object
      properties:
        denied:
          type: array
          items:
            $ref: '#/components/schemas/AccessDenied'
        allowed:
          type: array
          items:
            $ref: '#/components/schemas/AccessAllowedRep'
      required:
        - denied
        - allowed
      title: Access
    ApprovalSettings:
      type: object
      properties:
        required:
          type: boolean
          description: If approvals are required for this environment
        bypassApprovalsForPendingChanges:
          type: boolean
          description: Whether to skip approvals for pending changes
        minNumApprovals:
          type: integer
          description: >-
            Sets the amount of approvals required before a member can apply a
            change. The minimum is one and the maximum is five.
        canReviewOwnRequest:
          type: boolean
          description: >-
            Allow someone who makes an approval request to apply their own
            change
        canApplyDeclinedChanges:
          type: boolean
          description: >-
            Allow applying the change as long as at least one person has
            approved
        autoApplyApprovedChanges:
          type: boolean
          description: >-
            Automatically apply changes that have been approved by all
            reviewers. This field is only applicable for approval services other
            than LaunchDarkly.
        serviceKind:
          type: string
          description: Which service to use for managing approvals
        serviceConfig:
          type: object
          additionalProperties:
            description: Any type
        requiredApprovalTags:
          type: array
          items:
            type: string
          description: >-
            Require approval only on flags with the provided tags. Otherwise all
            flags will require approval.
        serviceKindConfigurationId:
          type: string
          description: >-
            Optional field for integration configuration ID of a custom approval
            integration. This is an Enterprise-only feature.
      required:
        - required
        - bypassApprovalsForPendingChanges
        - minNumApprovals
        - canReviewOwnRequest
        - canApplyDeclinedChanges
        - serviceKind
        - serviceConfig
        - requiredApprovalTags
      title: ApprovalSettings
    Environment:
      type: object
      properties:
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
        _id:
          type: string
          description: >-
            The ID for the environment. Use this as the client-side ID for
            authorization in some client-side SDKs, and to associate
            LaunchDarkly environments with CDN integrations in edge SDKs.
        key:
          type: string
          description: A project-unique key for the new environment
        name:
          type: string
          description: A human-friendly name for the new environment
        apiKey:
          type: string
          description: >-
            The SDK key for the environment. Use this for authorization in
            server-side SDKs.
        mobileKey:
          type: string
          description: >-
            The mobile key for the environment. Use this for authorization in
            mobile SDKs.
        color:
          type: string
          description: The color used to indicate this environment in the UI
        defaultTtl:
          type: integer
          description: >-
            The default time (in minutes) that the PHP SDK can cache feature
            flag rules locally
        secureMode:
          type: boolean
          description: >-
            Ensures that one end user of the client-side SDK cannot inspect the
            variations for another end user
        _access:
          $ref: '#/components/schemas/Access'
        defaultTrackEvents:
          type: boolean
          description: Enables tracking detailed information for new flags by default
        requireComments:
          type: boolean
          description: >-
            Whether members who modify flags and segments through the
            LaunchDarkly user interface are required to add a comment
        confirmChanges:
          type: boolean
          description: >-
            Whether members who modify flags and segments through the
            LaunchDarkly user interface are required to confirm those changes
        tags:
          type: array
          items:
            type: string
          description: A list of tags for this environment
        approvalSettings:
          $ref: '#/components/schemas/ApprovalSettings'
          description: Details about the approval settings for flags in this environment
        resourceApprovalSettings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ApprovalSettings'
          description: >-
            Details about the approval settings for other resources in this
            environment, organized by resource kind (for example, "aiconfig" and
            "segment")
        critical:
          type: boolean
          description: Whether the environment is critical
      required:
        - _links
        - _id
        - key
        - name
        - apiKey
        - mobileKey
        - color
        - defaultTtl
        - secureMode
        - defaultTrackEvents
        - requireComments
        - confirmChanges
        - tags
        - critical
      title: Environment
    InsightsMetricScoreIndicator:
      type: string
      title: InsightsMetricScoreIndicator
    InsightsMetricIndicatorRange:
      type: object
      properties:
        min:
          type: integer
          description: The minimum value for the indicator range
        max:
          type: integer
          description: The maximum value for the indicator range
      required:
        - min
        - max
      title: InsightsMetricIndicatorRange
    InsightsMetricScore:
      type: object
      properties:
        score:
          type: integer
          description: The score for the metric
        aggregateOf:
          type: array
          items:
            type: string
          description: The keys of the metrics that were aggregated to calculate this score
        diffVsLastPeriod:
          type: integer
        indicator:
          $ref: '#/components/schemas/InsightsMetricScoreIndicator'
          description: The indicator for the score
        indicatorRange:
          $ref: '#/components/schemas/InsightsMetricIndicatorRange'
          description: The indicator range for the score
        lastPeriod:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The score for the metric in the last period
      required:
        - score
        - indicator
        - indicatorRange
      title: InsightsMetricScore
    InsightGroupScores:
      type: object
      properties:
        overall:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The overall score for the insight group
        deploymentFrequency:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The deployment frequency score for the insight group
        deploymentFailureRate:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The deployment failure rate score for the insight group
        leadTime:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The lead time score for the insight group
        impactSize:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The impact size score for the insight group
        experimentationCoverage:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The Experimentation coverage score for the insight group
        flagHealth:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The flag health score for the insight group
        velocity:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The velocity score for the insight group
        risk:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The risk score for the insight group
        efficiency:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The efficiency score for the insight group
        creationRatio:
          $ref: '#/components/schemas/InsightsMetricScore'
          description: The creation ratio score for the insight group
      required:
        - overall
        - deploymentFrequency
        - deploymentFailureRate
        - leadTime
        - impactSize
        - experimentationCoverage
        - flagHealth
        - velocity
        - risk
        - efficiency
      title: InsightGroupScores
    UnixMillis:
      type: integer
      format: int64
      title: UnixMillis
    InsightPeriod:
      type: object
      properties:
        startTime:
          $ref: '#/components/schemas/UnixMillis'
          description: The start time of the period
        endTime:
          $ref: '#/components/schemas/UnixMillis'
          description: The end time of the period
      required:
        - startTime
        - endTime
      title: InsightPeriod
    InsightGroupCollectionScoreMetadata:
      type: object
      properties:
        period:
          $ref: '#/components/schemas/InsightPeriod'
          description: The time period for the score calculations
        lastPeriod:
          $ref: '#/components/schemas/InsightPeriod'
          description: The time period for the score calculations in the last period
      required:
        - period
        - lastPeriod
      title: InsightGroupCollectionScoreMetadata
    InsightGroup:
      type: object
      properties:
        environment:
          $ref: '#/components/schemas/Environment'
          description: Expanded details about the environment
        scores:
          $ref: '#/components/schemas/InsightGroupScores'
          description: The scores for the insight group
        scoreMetadata:
          $ref: '#/components/schemas/InsightGroupCollectionScoreMetadata'
          description: Metadata about the insight scores, when expanded
        key:
          type: string
          description: The insight group key
        name:
          type: string
          description: The insight group name
        projectKey:
          type: string
          description: The project key
        environmentKey:
          type: string
          description: The environment key
        applicationKeys:
          type: array
          items:
            type: string
          description: The application keys
        createdAt:
          $ref: '#/components/schemas/UnixMillis'
          description: The time the insight group was created
      required:
        - key
        - name
        - projectKey
        - environmentKey
        - createdAt
      title: InsightGroup
    InsightGroupsCountByIndicator:
      type: object
      properties:
        excellent:
          type: integer
          description: The number of insight groups with an excellent indicator
        good:
          type: integer
          description: The number of insight groups with a good indicator
        fair:
          type: integer
          description: The number of insight groups with a fair indicator
        needsAttention:
          type: integer
          description: The number of insight groups with a needs attention indicator
        notCalculated:
          type: integer
          description: The number of insight groups with a not calculated indicator
        unknown:
          type: integer
          description: The number of insight groups with an unknown indicator
        total:
          type: integer
          description: The total number of insight groups
      required:
        - excellent
        - good
        - fair
        - needsAttention
        - notCalculated
        - unknown
        - total
      title: InsightGroupsCountByIndicator
    InsightGroupCollectionMetadata:
      type: object
      properties:
        countByIndicator:
          $ref: '#/components/schemas/InsightGroupsCountByIndicator'
      required:
        - countByIndicator
      title: InsightGroupCollectionMetadata
    InsightGroupCollection:
      type: object
      properties:
        totalCount:
          type: integer
          description: The total number of insight groups
        items:
          type: array
          items:
            $ref: '#/components/schemas/InsightGroup'
          description: A list of insight groups
        _links:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Link'
          description: The location and content type of related resources
        metadata:
          $ref: '#/components/schemas/InsightGroupCollectionMetadata'
          description: Metadata about the insight groups
        scoreMetadata:
          $ref: '#/components/schemas/InsightGroupCollectionScoreMetadata'
          description: Metadata about the insight scores, when expanded
      required:
        - totalCount
        - items
      title: InsightGroupCollection
    FailureReasonRep:
      type: object
      properties:
        attribute:
          type: string
          description: The attribute that failed validation
        reason:
          type: string
          description: The reason the attribute failed validation
      required:
        - attribute
        - reason
      title: FailureReasonRep
    ValidationFailedErrorRep:
      type: object
      properties:
        code:
          type: string
          description: Specific error code encountered
        message:
          type: string
          description: Description of the error
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FailureReasonRep'
          description: List of validation errors
      required:
        - code
        - message
        - errors
      title: ValidationFailedErrorRep
    UnauthorizedErrorRep:
      type: object
      properties:
        code:
          type: string
          description: Specific error code encountered
        message:
          type: string
          description: Description of the error
      required:
        - code
        - message
      title: UnauthorizedErrorRep
    ForbiddenErrorRep:
      type: object
      properties:
        code:
          type: string
          description: Specific error code encountered
        message:
          type: string
          description: Description of the error
      required:
        - code
        - message
      title: ForbiddenErrorRep
    RateLimitedErrorRep:
      type: object
      properties:
        code:
          type: string
          description: Specific error code encountered
        message:
          type: string
          description: Description of the error
      required:
        - code
        - message
      title: RateLimitedErrorRep
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization

```

## SDK Code Examples

```python
import requests

url = "https://app.launchdarkly.com/api/v2/engineering-insights/insights/groups"

headers = {"Authorization": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://app.launchdarkly.com/api/v2/engineering-insights/insights/groups';
const options = {method: 'GET', headers: {Authorization: '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.launchdarkly.com/api/v2/engineering-insights/insights/groups"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://app.launchdarkly.com/api/v2/engineering-insights/insights/groups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://app.launchdarkly.com/api/v2/engineering-insights/insights/groups")
  .header("Authorization", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://app.launchdarkly.com/api/v2/engineering-insights/insights/groups', [
  'headers' => [
    'Authorization' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://app.launchdarkly.com/api/v2/engineering-insights/insights/groups");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://app.launchdarkly.com/api/v2/engineering-insights/insights/groups")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```