> ## Documentation Index > Fetch the complete documentation index at: https://docs.coval.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get widget > Retrieve a specific widget by ID. ## OpenAPI ````yaml get /dashboards/{dashboard_id}/widgets/{widget_id} openapi: 3.0.3 info: title: Coval Dashboards API version: 1.0.0 description: | Create and manage dashboards and widgets for visualizing evaluation metrics. contact: name: Coval API Support email: support@coval.dev url: https://docs.coval.ai license: name: Proprietary url: https://coval.dev/terms servers: - url: https://api.coval.dev/v1 description: Production API security: - ApiKeyAuth: [] tags: - name: Dashboards description: Dashboard CRUD operations - name: Widgets description: Dashboard widget CRUD operations paths: /dashboards/{dashboard_id}/widgets/{widget_id}: get: tags: - Widgets summary: Get widget description: Retrieve a specific widget by ID. operationId: getWidget parameters: - $ref: '#/components/parameters/DashboardId' - $ref: '#/components/parameters/WidgetId' responses: '200': description: Widget retrieved successfully content: application/json: schema: $ref: '#/components/schemas/GetWidgetResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalError' security: - ApiKeyAuth: [] components: parameters: DashboardId: name: dashboard_id in: path required: true schema: type: string description: Dashboard resource ID (22-character ShortUUID) example: abc123def456ghi789jklm WidgetId: name: widget_id in: path required: true schema: type: string description: Widget resource ID (22-character ShortUUID) example: wgt456xyz789abc012defg schemas: GetWidgetResponse: type: object required: - widget properties: widget: $ref: '#/components/schemas/WidgetResource' WidgetResource: type: object description: Widget resource required: - name - type - create_time - update_time properties: name: type: string description: Resource name in format `dashboards/{dashboard_id}/widgets/{id}` example: dashboards/abc123def456ghi789jklm/widgets/wgt456xyz789abc012defg display_name: type: string nullable: true maxLength: 255 description: Human-readable widget name example: Response Time Chart type: description: Widget type. allOf: - $ref: '#/components/schemas/WidgetType' grid_x: type: integer nullable: true description: Grid column position grid_y: type: integer nullable: true description: Grid row position grid_w: type: integer nullable: true description: Grid column span grid_h: type: integer nullable: true description: Grid row span config: $ref: '#/components/schemas/WidgetConfig' create_time: type: string format: date-time description: Creation timestamp (ISO 8601) example: '2025-10-14T12:00:00Z' update_time: type: string format: date-time description: Last update timestamp (ISO 8601) example: '2025-10-15T14:30:00Z' ErrorResponse: type: object description: Standard error response required: - error properties: error: type: object required: - code - message - details properties: code: type: string description: Error code enum: - INVALID_ARGUMENT - UNAUTHENTICATED - NOT_FOUND - INTERNAL example: INVALID_ARGUMENT message: type: string description: Human-readable error message example: Invalid request parameter details: type: array description: Detailed error information items: type: object properties: field: type: string nullable: true description: Field that caused the error description: type: string description: Detailed error description WidgetType: type: string description: > Type of widget. - **chart**: Visualization widget (line, bar, area, pie, histogram, statistic, top-list) - **table**: Tabular data widget with multiple metrics - **text**: Free-form text/markdown widget enum: - chart - table - text example: chart WidgetConfig: anyOf: - $ref: '#/components/schemas/ChartWidgetConfig' - $ref: '#/components/schemas/TableWidgetConfig' - $ref: '#/components/schemas/TextWidgetConfig' description: Widget configuration, structure depends on widget type ChartWidgetConfig: type: object description: Configuration for chart-type widgets properties: metricId: type: string description: ID of the metric to visualize visualizationType: $ref: '#/components/schemas/VisualizationType' monitoring: $ref: '#/components/schemas/DataSourceType' aggregation: $ref: '#/components/schemas/AggregationType' metricOutputType: $ref: '#/components/schemas/MetricOutputType' bucketInterval: type: string description: Time bucket interval for aggregation enum: - 15 minutes - 1 hour - 4 hours - 1 day stacked: type: boolean description: Stack series in the chart grouped: type: boolean description: Group series in the chart showAsPercentage: type: boolean description: Display values as percentages groupBy: $ref: '#/components/schemas/GroupByType' customColorMap: type: object additionalProperties: type: string description: Custom color assignments for series (max 200 entries) xAxisLabel: type: string maxLength: 200 description: Custom X-axis label yAxisLabel: type: string maxLength: 200 description: Custom Y-axis label customSeriesNames: type: object additionalProperties: type: string description: Custom display names for series (max 200 entries) hiddenSeries: type: array items: type: string description: Series to hide by default (max 200) precision: type: integer minimum: 0 maximum: 3 description: Decimal precision for displayed values units: type: string maxLength: 10 description: Unit label for values showCount: type: boolean description: Show count alongside metric showRange: type: boolean description: Show min/max range showStdDev: type: boolean description: Show standard deviation showBoxPlot: type: boolean description: Show box plot overlay showTargetZone: type: boolean description: Show target zone overlay filters: $ref: '#/components/schemas/FilterConfig' metricFilter: type: array items: $ref: '#/components/schemas/MetricFilter' description: Metric value filters (max 50) TableWidgetConfig: type: object description: Configuration for table-type widgets properties: metricIds: type: array items: type: string description: IDs of metrics to display (max 50) maxItems: 50 monitoring: $ref: '#/components/schemas/DataSourceType' aggregation: $ref: '#/components/schemas/AggregationType' groupBy: $ref: '#/components/schemas/GroupByType' filters: $ref: '#/components/schemas/FilterConfig' metricFilter: type: array items: $ref: '#/components/schemas/MetricFilter' description: Metric value filters (max 50) TextWidgetConfig: type: object description: Configuration for text-type widgets properties: text: type: string maxLength: 10000 description: Free-form text content VisualizationType: type: string description: Chart visualization style enum: - line - bar - area - statistic - pie - histogram - top-list example: line DataSourceType: type: string description: Data source for the widget enum: - Monitoring - Simulations example: Monitoring AggregationType: type: string description: Aggregation function for metric data enum: - sum - count - avg - max - min - success - p90 - p95 - p99 example: avg MetricOutputType: type: string description: Output type of the metric values enum: - string - float example: float GroupByType: type: string description: Field to group metric results by enum: - agent - mutation - persona - template - test_set example: agent FilterConfig: type: object description: Scope filters to narrow widget data properties: metricIds: type: array items: type: string description: Filter to specific metric IDs agentIds: type: array items: type: string description: Filter to specific agent IDs agentMutationIds: type: array items: type: string description: Filter to specific agent mutation IDs personaIds: type: array items: type: string description: Filter to specific persona IDs templateNames: type: array items: type: string description: Filter to specific template names testSetIds: type: array items: type: string description: Filter to specific test set IDs metadata: type: array items: type: object description: Metadata-based filters MetricFilter: type: object description: Filter condition applied to metric values required: - metricId - operator - value - metricOutputType properties: metricId: type: string description: ID of the metric to filter on operator: $ref: '#/components/schemas/MetricFilterOperator' value: oneOf: - type: number - type: string description: Threshold value for the filter metricOutputType: $ref: '#/components/schemas/MetricOutputType' MetricFilterOperator: type: string description: Comparison operator for metric filters enum: - '>' - < - '>=' - <= - '=' - '!=' example: '>=' responses: Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UNAUTHENTICATED message: Authentication failed details: - field: X-API-Key description: Invalid or missing API key NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Resource not found details: - field: dashboard_id description: Dashboard not found or not accessible by your organization InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL message: Internal server error details: - description: An unexpected error occurred securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ````