---
title: List Widget
description: >-
  Display filterable lists of events and issues from logs, RUM, events, and
  other sources in dashboard widgets.
breadcrumbs: Docs > Dashboards > Widgets > List Widget
---

# List Widget

The list widget displays a list of events and issues, which can come from a variety of sources such as Logs, RUM, or Events. Search and query across sources to narrow down the events you want the widget to highlight and display.

*List widget displaying error tracking issues*

{% image
   source="https://docs.dd-static.net/images/dashboards/widgets/list/list_overview.c77df3932b551d11e3666ee928f7c1c6.png?auto=format"
   alt="List widget displaying a list of errors, their error count and volume." /%}

## Setup{% #setup %}

{% image
   source="https://docs.dd-static.net/images/dashboards/widgets/list/list_setup.86974be29615c48859d2dae826cc5c8d.png?auto=format"
   alt="List widget configuration modal" /%}

### Configuration{% #configuration %}

1. Choose the type of data to graph. You can create a list widget from Issues, Logs, Audit Trail, Watchdog Alerts, or Events depending on which products are available for your organization.

1. Set display preferences. On screenboards and notebooks, choose whether your widget has a custom timeframe or uses the global timeframe.

1. Optional: Give your graph a title (or leave blank for suggested title).

### Options{% #options %}

Each type of list widget has its own configuration.

### Issues{% #issues %}

#### Sorting by{% #sorting-by %}

For issues, you can sort by:

- Number of errors (default)
- First seen
- Impacted sessions

**Note:** Changing the "Sorting by" selection does not change the columns displayed. If you change your list to sort by impacted sessions, and want to see this on your widget, you must also select or add "Impacted Sessions" to the graph editor.

### Logs{% #logs %}

#### Grouping by{% #grouping-by %}

For logs, you can group by:

- Patterns
- Transactions

### RUM event list options{% #rum-event-list-options %}

#### Sorting by{% #sorting-by-1 %}

For RUM, you can sort by:

- Session type
- Time spent
- View count
- Error count
- Action count
- Session frustration count
- Initial view name
- Last view name

Ascending or descending

### Events{% #events %}

#### Report format size:{% #report-format-size %}

For Events, you can choose how they're displayed in the widget:

- Small (title only)
- Large (full event)

### Incidents{% #incidents %}

#### Sorting by{% #sorting-by-2 %}

For incidents, you can sort by:

- Created time
- Detected time
- Last modified time
- Resolved time
- Severity
- Status
- Title

Ascending or descending

### CD deployments{% #cd-deployments %}

#### Sorting by{% #sorting-by-3 %}

For CD deployments, you can sort by:

- Deployment Status
- Service
- Deployment Name
- Environment
- Duration
- Revision Value
- Repository URL
- Timestamp

Ascending or descending

### CI pipelines{% #ci-pipelines %}

#### Sorting by{% #sorting-by-4 %}

For CI pipelines, you can sort by:

- CI Status
- Pipeline Name
- Duration
- Pipeline ID
- Branch
- Timestamp

Ascending or descending

## API{% #api %}

This widget can be used with the **[Dashboards API](https://docs.datadoghq.com/api/latest/dashboards/)**. See the following table for the [widget JSON schema definition](https://docs.datadoghq.com/dashboards/graphing_json/widget_json/):

{% tab %}
ModelExample
{% tab title="-model" %}
Expand AllFieldTypeDescriptiondescriptionstringThe description of the widget.legend_sizestringAvailable legend sizes for a widget. Should be one of "0", "2", "4", "8", "16", or "auto". requests [*required*][object]Request payload used to query items. columns [*required*][object]Widget columns.field [*required*]stringWidget column field.width [*required*]enumWidget column width. Allowed enum values: `auto,compact,full` query [*required*]objectUpdated list stream widget.clustering_pattern_field_pathstringSpecifies the field for logs pattern clustering. Usable only with logs_pattern_stream. compute[object]Compute configuration for the List Stream Widget. Compute can be used only with the logs_transaction_stream (from 1 to 5 items) list stream source.aggregation [*required*]enumAggregation value. Allowed enum values: `count,cardinality,median,pc75,pc90,pc95,pc98,pc99,sum,min`Show 5 more`,max,avg,earliest,latest,most_frequent`

facetstringFacet name.data_source [*required*]enumSource from which to query items to display in the stream. Allowed enum values: `logs_stream,audit_stream,ci_pipeline_stream,ci_test_stream,rum_issue_stream,apm_issue_stream,trace_stream,logs_issue_stream,logs_pattern_stream,logs_transaction_stream`Show 3 more`,event_stream,rum_stream,llm_observability_stream`


default: `apm_issue_stream`
event_sizeenumSize to use to display an event. Allowed enum values: `s,l` group_by[object]Group by configuration for the List Stream Widget. Group by can be used only with logs_pattern_stream (up to 4 items) or logs_transaction_stream (one group by item is required) list stream source.facet [*required*]stringFacet name.indexes[string]List of indexes.query_string [*required*]stringWidget query. sortobjectWhich column and order to sort bycolumn [*required*]stringFacet path for the columnorder [*required*]enumWidget sorting methods. Allowed enum values: `asc,desc`storagestringOption for storage location. Feature in Private Beta.response_format [*required*]enumWidget response format. Allowed enum values: `event_list`show_legendbooleanWhether or not to display the legend on this widget. time <oneOf>Time setting for the widget. Option 1objectWrapper for live spanhide_incomplete_cost_databooleanWhether to hide incomplete cost data in the widget.live_spanenumThe available timeframes depend on the widget you are using. Allowed enum values: `1m,5m,10m,15m,30m,1h,4h,1d,2d,1w`Show 7 more`,1mo,3mo,6mo,week_to_date,month_to_date,1y,alert`

 Option 2objectUsed for arbitrary live span times, such as 17 minutes or 6 hours.hide_incomplete_cost_databooleanWhether to hide incomplete cost data in the widget.type [*required*]enumType "live" denotes a live span in the new format. Allowed enum values: `live`unit [*required*]enumUnit of the time span. Allowed enum values: `minute,hour,day,week,month,year`value [*required*]int64Value of the time span. Option 3objectUsed for fixed span times, such as 'March 1 to March 7'.from [*required*]int64Start time in milliseconds since epoch.hide_incomplete_cost_databooleanWhether to hide incomplete cost data in the widget.to [*required*]int64End time in milliseconds since epoch.type [*required*]enumType "fixed" denotes a fixed span. Allowed enum values: `fixed`titlestringTitle of the widget.title_alignenumHow to align the text on the widget. Allowed enum values: `center,left,right`title_sizestringSize of the title.type [*required*]enumType of the list stream widget. Allowed enum values: `list_stream`
default: `list_stream`
{% /tab %}

{% tab title="example" %}

```json
{
  "description": "string",
  "legend_size": "string",
  "requests": [
    {
      "columns": [
        {
          "field": "content",
          "width": "compact"
        }
      ],
      "query": {
        "clustering_pattern_field_path": "message",
        "compute": [
          {
            "aggregation": "count",
            "facet": "resource_name"
          }
        ],
        "data_source": "apm_issue_stream",
        "event_size": "string",
        "group_by": [
          {
            "facet": "resource_name"
          }
        ],
        "indexes": [],
        "query_string": "@service:app",
        "sort": {
          "column": "",
          "order": "desc"
        },
        "storage": "indexes"
      },
      "response_format": "event_list"
    }
  ],
  "show_legend": false,
  "time": {
    "hide_incomplete_cost_data": false,
    "live_span": "5m"
  },
  "title": "string",
  "title_align": "string",
  "title_size": "string",
  "type": "list_stream"
}
```

{% /tab %}

{% /tab %}

## Further Reading{% #further-reading %}

- [Building Dashboards using JSON](https://docs.datadoghq.com/dashboards/graphing_json/)
- [Notebooks](https://docs.datadoghq.com/notebooks/)