post-insight-result
dci post-insight-result sourceID insightKey
Creates or updates a single insight for the given source and key. If an insight with the same key already exists for the source, it will be updated. Resource results are managed separately via the resource-results endpoint.
Request
Content-Type: application/json
Schema
{
"type": "object",
"description": "Request body for creating or updating a single insight's metadata. Resource results are managed separately via the resource-results endpoint.",
"required": [
"key",
"title",
"shortDescription",
"cloudProvider",
"categories"
],
"properties": {
"key": {
"type": "string",
"description": "A unique key for this insight within the source."
},
"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."
},
"cloudProvider": {
"type": "string",
"example": "aws",
"description": "The cloud provider associated with the resource."
},
"categories": {
"description": "One or more categories this insight belongs to.",
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string",
"description": "Allowed categories when creating insights via the public API.",
"enum": [
"FinOps",
"Security"
]
}
},
"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."
},
"status": {
"type": "string",
"enum": [
"actionable",
"acknowledged",
"optimized",
"dismissed",
"in progress",
"upgrade needed",
"permissions needed"
],
"description": "The display status of the insight."
},
"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."
}
}
}
}
}
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 |
|---|---|---|
source | string | The source that generated the insight. |
key | string | The unique key identifying this insight. |
title | string | The display title of the insight. |
shortDescription | string | A brief summary of the insight. |
detailedDescriptionMdx | string | A detailed description of the insight in MDX format. |
displayStatus | string | The display status of the insight. One of: "actionable", "acknowledged", "optimized", "dismissed", "in progress", "upgrade needed", "permissions needed". |
cloudProvider | string | The cloud provider associated with the resource. |
categories | array of string | Categories this insight belongs to. |
summary | object | Aggregate summary of risks and savings across all resource results for an insight. |
summary.operationalRisks | number (double) | Total number of operational risks. |
summary.performanceRisks | number (double) | Total number of performance risks. |
summary.potentialDailySavings | number (double) | Total potential daily savings in USD. |
summary.reliabilityRisks | number (double) | Total number of reliability risks. |
summary.securityRisks | number (double) | Total number of security risks. |
summary.sustainabilityRisks | number (double) | Total number of sustainability risks. |
lastStatusChange | object | If set, this object contains the last status change made by a user for this insight |
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. |
lastStatusChange.lastChangedAt | string (date-time) | |
lastUpdated | string (date-time) | Timestamp of the last update to this insight. |
tags | array of string | Tags for the insight, primarily used for security certification labels (e.g. ISO). |
reportUrl | string | URL to an external report related to this insight. |
cloudFlowTemplateId | string | ID of a CloudFlow template that can automate the remediation of this insight. |
easyWinDescription | string | A description of why this insight is considered an easy win. |
dismissalDetails | object | Details for why an insight was dismissed. |
dismissalDetails.reason | string | The reason for dismissal. One of: "not relevant", "not enough information", "not worth the effort", "inaccurate optimization opportunities". |
dismissalDetails.comment | string | An optional free-text comment providing additional context. |
Raw JSON schema
{
"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."
}
}
}
}
}
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. |
| 500 | 40 | API_SERVER_ERROR | The API failed to process the request. Retryable; contact DoiT support if it persists. |
Aliases: postinsightresult