list-insights

dci list-insights [flags]

Returns a paginated list of insights with their aggregate summaries (savings, risk counts). Use query parameters to filter by status, category, provider, or priority. Does not include individual resource-level results — use the resource-results endpoint for those.

CLI default view

dci list-insights shapes the raw API response before rendering:

Dismissed insights are excluded by default. Pass --include-dismissed to keep them; when rows were removed, the response carries a dismissedOmitted count.
Results are sorted by summary.potentialDailySavings (USD), highest first, in every output format, so the most valuable insights lead the list.
The default table shows a curated column set: title, dailySavings (formatted as USD, e.g. $500.00; blank when zero), provider (from cloudProvider), categories, lastUpdated, and source. Easy wins carry an (easy win) title suffix and, in interactive terminals, a green title; an insight's reportUrl becomes a clickable link on its title.
--output json and explicit -C/--fields selections return the raw fields documented below.

Flags

--search-term: (string)

--display-status: (array)

--category: (string enum:"FinOps","OperationalExcellence","PerformanceEfficiency","Reliability","Security","Sustainability")

--cloud-provider: (string) The cloud provider associated with the resource.

--source: (array)

--priority: (array)

--tag: (array)

--easy-win: (boolean)

--cloud-flows: (boolean)

--page-token: (string)

--max-results: (integer default:50)

Output

Successful operation

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

Field	Type	Description
`results`	array of object	List of insight results.
`results[].source`	string	The source that generated the insight.
`results[].key`	string	The unique key identifying this insight.
`results[].title`	string	The display title of the insight.
`results[].shortDescription`	string	A brief summary of the insight.
`results[].detailedDescriptionMdx`	string	A detailed description of the insight in MDX format.
`results[].displayStatus`	string	The display status of the insight. One of: `"actionable"`, `"acknowledged"`, `"optimized"`, `"dismissed"`, `"in progress"`, `"upgrade needed"`, `"permissions needed"`.
`results[].cloudProvider`	string	The cloud provider associated with the resource.
`results[].categories`	array of string	Categories this insight belongs to.
`results[].summary`	object	Aggregate summary of risks and savings across all resource results for an insight.
`results[].summary.operationalRisks`	number (double)	Total number of operational risks.
`results[].summary.performanceRisks`	number (double)	Total number of performance risks.
`results[].summary.potentialDailySavings`	number (double)	Total potential daily savings in USD.
`results[].summary.reliabilityRisks`	number (double)	Total number of reliability risks.
`results[].summary.securityRisks`	number (double)	Total number of security risks.
`results[].summary.sustainabilityRisks`	number (double)	Total number of sustainability risks.
`results[].lastStatusChange`	object	If set, this object contains the last status change made by a user for this insight
`results[].lastStatusChange.userId`	string	the reference to the user who made the change (if it was made by a user) If the change was made by an automated system, this reference is empty.
`results[].lastStatusChange.lastChangedAt`	string (date-time)
`results[].lastUpdated`	string (date-time)	Timestamp of the last update to this insight.
`results[].tags`	array of string	Tags for the insight, primarily used for security certification labels (e.g. ISO).
`results[].reportUrl`	string	URL to an external report related to this insight.
`results[].cloudFlowTemplateId`	string	ID of a CloudFlow template that can automate the remediation of this insight.
`results[].easyWinDescription`	string	A description of why this insight is considered an easy win.
`results[].dismissalDetails`	object	Details for why an insight was dismissed.
`results[].dismissalDetails.reason`	string	The reason for dismissal. One of: `"not relevant"`, `"not enough information"`, `"not worth the effort"`, `"inaccurate optimization opportunities"`.
`results[].dismissalDetails.comment`	string	An optional free-text comment providing additional context.
`pagination`	object	Cursor-based pagination metadata.
`pagination.pageToken`	string	Token to retrieve the next page. Absent when there are no more pages.
`pagination.rowCount`	integer	Number of items in this page.

Raw JSON schema

{
  "type": "object",
  "description": "Paginated list of insight results.",
  "properties": {
    "results": {
      "description": "List of insight results.",
      "type": "array",
      "items": {
        "type": "object",
        "description": "An insight result containing summary information and metadata.",
        "properties": {
          "source": {
            "type": "string",
            "description": "The source that generated the insight.",
            "example": "aws-trusted-advisor, aws-cost-optimization-hub, aws-security-hub, azure-advisor, custom, gcp-recommender"
          },
          "key": {
            "type": "string",
            "description": "The unique key identifying this insight."
          },
          "title": {
            "type": "string",
            "description": "The display title of the insight."
          },
          "shortDescription": {
            "type": "string",
            "description": "A brief summary of the insight."
          },
          "detailedDescriptionMdx": {
            "type": "string",
            "description": "A detailed description of the insight in MDX format."
          },
          "displayStatus": {
            "type": "string",
            "enum": [
              "actionable",
              "acknowledged",
              "optimized",
              "dismissed",
              "in progress",
              "upgrade needed",
              "permissions needed"
            ],
            "description": "The display status of the insight."
          },
          "cloudProvider": {
            "type": "string",
            "example": "aws",
            "description": "The cloud provider associated with the resource."
          },
          "categories": {
            "description": "Categories this insight belongs to.",
            "type": "array",
            "items": {
              "type": "string",
              "description": "The insight category.",
              "enum": [
                "FinOps",
                "Operational excellence",
                "Performance efficiency",
                "Reliability",
                "Security",
                "Sustainability"
              ]
            }
          },
          "summary": {
            "type": "object",
            "description": "Aggregate summary of risks and savings across all resource results for an insight.",
            "properties": {
              "operationalRisks": {
                "type": "number",
                "format": "double",
                "description": "Total number of operational risks."
              },
              "performanceRisks": {
                "type": "number",
                "format": "double",
                "description": "Total number of performance risks."
              },
              "potentialDailySavings": {
                "type": "number",
                "format": "double",
                "description": "Total potential daily savings in USD."
              },
              "reliabilityRisks": {
                "type": "number",
                "format": "double",
                "description": "Total number of reliability risks."
              },
              "securityRisks": {
                "type": "number",
                "format": "double",
                "description": "Total number of security risks."
              },
              "sustainabilityRisks": {
                "type": "number",
                "format": "double",
                "description": "Total number of sustainability risks."
              }
            }
          },
          "lastStatusChange": {
            "description": "If set, this object contains the last status change made by a user for this insight",
            "type": "object",
            "properties": {
              "userId": {
                "description": "the reference to the user who made the change (if it was made by a user) If the change was made by an automated system, this reference is empty.\n",
                "type": "string",
                "example": "/users/0Rkrkeq5P0XLe8QFHKq2"
              },
              "lastChangedAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "userId",
              "lastChangedAt"
            ]
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the last update to this insight."
          },
          "tags": {
            "description": "Tags for the insight, primarily used for security certification labels (e.g. ISO).",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "reportUrl": {
            "type": "string",
            "description": "URL to an external report related to this insight."
          },
          "cloudFlowTemplateId": {
            "type": "string",
            "description": "ID of a CloudFlow template that can automate the remediation of this insight."
          },
          "easyWinDescription": {
            "type": "string",
            "description": "A description of why this insight is considered an easy win."
          },
          "dismissalDetails": {
            "type": "object",
            "description": "Details for why an insight was dismissed.",
            "properties": {
              "reason": {
                "type": "string",
                "description": "The reason for dismissal.",
                "enum": [
                  "not relevant",
                  "not enough information",
                  "not worth the effort",
                  "inaccurate optimization opportunities"
                ]
              },
              "comment": {
                "type": "string",
                "description": "An optional free-text comment providing additional context."
              }
            }
          }
        }
      }
    },
    "pagination": {
      "type": "object",
      "description": "Cursor-based pagination metadata.",
      "required": [
        "rowCount"
      ],
      "properties": {
        "pageToken": {
          "type": "string",
          "description": "Token to retrieve the next page. Absent when there are no more pages."
        },
        "rowCount": {
          "type": "integer",
          "description": "Number of items in this page."
        }
      }
    }
  }
}

Errors

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status	Exit code	Error code	Meaning
400	30	`VALIDATION_ERROR`	The arguments or request body were rejected. Review the command's flags and payload.
401	10	`AUTHENTICATION_FAILED`	Not signed in, or the API token is invalid. Run `dci login` or check `DCI_API_KEY`.
403	11	`PERMISSION_DENIED`	The DoiT user or the active customer context does not have access.
404	20	`RESOURCE_NOT_FOUND`	The requested resource does not exist. Check the identifier argument.
500	40	`API_SERVER_ERROR`	The API failed to process the request. Retryable; contact DoiT support if it persists.

Aliases: get-insight-results

Flags​

Output​

Errors​

Flags

Output

Errors