> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboards API

## Programmatically Creating Dashboards

### Creating a Dashboard Using a Template

Programmatically create a dashboard using one of our predefined templates, streamlining the setup process for common use cases

```php theme={null}
mutation create(
  $name:String!
  $modelId:ID!
  $template:DashboardTemplates!
  $postiveClass: String!
){
  createDashboardFromTemplate(input:
  {
    name:$name
    modelId:$modelId
    template: $template
    positiveClass: $postiveClass
  }
  ){
    dashboard{
      id
    }
  }
}
```

**variables**

```json theme={null}
{
  "name": "dashboard-name",
  "modelId": "model_id",
  "template": "templateName", 
  "postiveClass": "fraud"
}
```

### **Create an Empty Dashboard**

When creating a new custom dashboard, you first need to create an empty state dashboard to add widgets to:

```php theme={null}
mutation createDashTest($name: String!, $spaceId: ID!) {
  createDashboard(input: { name: $name, spaceId: $spaceId }) {
    dashboard {
      id
    }
  }
}
```

This will return the dashboard id to use in mutations to add widgets.

### Add a Distribution Widget

To visualize data variations and overall distribution patterns on your dashboard, use the `createBarChartWidget` mutation.

```php theme={null}
mutation createBarChartWidget(
  $title:String!
  $dashboardId:ID!
  $plots:[BarChartPlotInputInput!]!
){
  createBarChartWidget(
    input:
  {
    title:$title
    dashboardId: $dashboardId 
    plots: $plots
  }
  ){
    barChartWidget{
      id
    }
  }
}
```

**variable**

```json theme={null}
{
  "title": "widget-title",
  "dashboardId": "dashboard_id",
  "plots": [
    {
      "title": "plot-title",
      "position": 1,
      "modelId": "model_id",
      "dimension": {
        "id": "dimension_id",
        "name": "dimension_name",
        "dataType": "STRING"
      },
      "dimensionCategory": "featureLabel",
      "filters": [],
      "modelVersionIds": []
    }
  ]
}
```

### Add a Time Series Widget

Use the `createLineChartWidget` to add a time series widget to your dashboard, which is perfect for visualizing performance over time, data quality, and analyzing trends with options to add multiple lines or split data by specific criteria.

<Tabs>
  <Tab title="Performance Metrics">
    ```php theme={null}
    mutation createLineChartWidget(
      $title:String!
      $dashboardId:ID!
      $plots:[LineChartPlotInputInput!]!
      $timeSeriesMetricType: TimeSeriesMetricCategory!
    ){
      createLineChartWidget(
        input:
      {
        title:$title
        timeSeriesMetricType: $timeSeriesMetricType
        dashboardId: $dashboardId 
        plots: $plots
        widgetType: lineChartWidget
      }
      ){
        lineChartWidget{
          id
        }
      }
    }
    ```

    **variables**

    ```json theme={null}
    {
      "title": "widget-name",
      "dashboardId": "model_id",
      "timeSeriesMetricType": "evaluationMetric",
      "plots": {
        "modelId": "model_id",
        "modelVersionIds": [],
        "dimensionCategory": "prediction",
        "metric": "auc",
        "positiveClass": "fraud",
        "title": "AUC Over Time",
        "position": 1,
        "modelEnvironmentName": "production",
        "filters": []
        }
    }
    ```
  </Tab>

  <Tab title="Data Quality">
    ```php theme={null}
    mutation createLineChartWidget(
      $title:String!
      $dashboardId:ID!
      $plots:[LineChartPlotInputInput!]!
      $timeSeriesMetricType: TimeSeriesMetricCategory!
    ){
      createLineChartWidget(
        input:
      {
        title:$title
        timeSeriesMetricType: $timeSeriesMetricType
        dashboardId: $dashboardId 
        plots: $plots
        widgetType: lineChartWidget
      }
      ){
        lineChartWidget{
          id
        }
      }
    }
    ```

    variables

    ```json theme={null}
    {
      "title": "widget-name",
      "dashboardId": "dashboard_id",
      "timeSeriesMetricType": "evaluationMetric",
      "plots": {
        "modelId": "model_id",
        "modelVersionIds": [],
        "dimensionCategory": "featureLabel",
        "metric": "percentEmpty",
        "dimension": {
          "id": "dimension_id",
          "name": "dimension_name",
          "dataType": "STRING"
          },
        "title": "plot-title",
        "position": 1,
        "modelEnvironmentName": "production",
        "filters": []
      }
    }
    ```
  </Tab>

  <Tab title="Multiple Plots">
    ```php theme={null}
    mutation createLineChartWidget(
      $title:String!
      $dashboardId:ID!
      $plots:[LineChartPlotInputInput!]!
      $timeSeriesMetricType: TimeSeriesMetricCategory!
    ){
      createLineChartWidget(
        input:
      {
        title:$title
        timeSeriesMetricType: $timeSeriesMetricType
        dashboardId: $dashboardId 
        plots: $plots
        widgetType: lineChartWidget
      }
      ){
        lineChartWidget{
          id
        }
      }
    }
    ```

    variables

    ```json theme={null}
    {
      "title": "widget-name",
      "dashboardId": "dashboard_id",
      "timeSeriesMetricType": "evaluationMetric",
      "plots": [{
        "modelId": "model_id",
        "modelVersionIds": [],
        "dimensionCategory": "prediction",
        "metric": "auc",
        "positiveClass": "fraud",
        "title": "plot-1-title",
        "position": 1,
        "modelEnvironmentName": "production",
        "filters": []
      },
        {
        "modelId": "model_id",
        "modelVersionIds": [],
        "dimensionCategory": "prediction",
        "metric": "count",
        "positiveClass": "fraud",
        "title": "plot-2-title",
        "position": 2,
        "modelEnvironmentName": "production",
        "filters": []
        
      }
      ]
    }
    ```
  </Tab>

  <Tab title="Split By">
    ```php theme={null}
    mutation createLineChartWidget(
      $title:String!
      $dashboardId:ID!
      $plots:[LineChartPlotInputInput!]!
      $timeSeriesMetricType: TimeSeriesMetricCategory!
    ){
      createLineChartWidget(
        input:
      {
        title:$title
        timeSeriesMetricType: $timeSeriesMetricType
        dashboardId: $dashboardId 
        plots: $plots
        widgetType: lineChartWidget
      }
      ){
        lineChartWidget{
          id
        }
      }
    }
    ```

    variables

    ```json theme={null}
    {
      "title": "split-by-widget",
      "dashboardId": "dashboard_id",
      "timeSeriesMetricType": "evaluationMetric",
      "plots": [{
        "modelId": "model_id",
        "modelVersionIds": [],
        "dimensionCategory": "prediction",
        "metric": "auc",
        "positiveClass": "fraud",
        "title": "plot-name",
        "position": 1,
        "modelEnvironmentName": "production",
        "filters": [],
        "splitByEnabled": true,
        "splitByDimension": "state",
        "splitByDimensionCategory": "featureLabel",
        "cohorts": [
                        "state='CA'",
                        "state='CO'",
                        "state='NY'"
                      ]
      }
      ]
    }
    ```
  </Tab>
</Tabs>

### Add a Drift Widget

To effectively monitor data drift, utilize the `createLineChartWidget` mutation with the `widgetType` input set to `driftLineChartWidget`. Below is an example that demonstrates using the PSI. You also have the flexibility to opt for other statistical methods such as Jensen-Shannon distance (JS) or Kullback-Leibler (KL) divergence, depending on your analysis needs.

```php theme={null}
mutation createDriftWidget(
$title:String!
  $dashboardId:ID!
  $plots:[LineChartPlotInputInput!]!
  $timeSeriesMetricType: TimeSeriesMetricCategory!
){
  createLineChartWidget(
    input:
  {
    title:$title
    timeSeriesMetricType: $timeSeriesMetricType
    dashboardId: $dashboardId 
    plots: $plots
    widgetType: driftLineChartWidget
  }
  ){
    lineChartWidget{
      id
    }
  }
}
```

**variables**

```json theme={null}
{
  "title": "drift-widget-title",
  "dashboardId": "dashbaord_id",
  "timeSeriesMetricType": "evaluationMetric",
  "plots": [{
    "modelId": "model_id",
    "modelVersionIds": [],
    "dimensionCategory": "prediction",
    "metric": "psi",
    "title": "drift-plot-title",
    "position": 1,
    "modelEnvironmentName": "production",
    "filters": [],
    "comparisonDatasetModelBaselineId": "baseline_id" 
  }
  ]
}
```

To get your baselineId you can query your model:

```javascript theme={null}
query getBaseline($modelID:ID!){
  node(id: $modelID) {
    ... on Model {
      modelPrimaryBaseline{
        id
      }
    }
  }
}
```

### Add a Monitor Widget

Visualize your monitors using a monitor widget.

```php theme={null}
mutation createMonitorChartWidget(
  $title:String!
  $dashboardId:ID!
  $monitorId: ID!
){
  createLineChartWidget(
    input:
  {
    title:$title
    timeSeriesMetricType: evaluationMetric
    dashboardId: $dashboardId 
    monitorId: $monitorId
    widgetType: monitorLineChartWidget
  }
  ){
    lineChartWidget{
      id
    }
  }
}
```

**variables**

```json theme={null}
{
  "title": "widget-title",
  "dashboardId": "dashboard_id",
  "monitorId": "monitor_id"
}
```

### Add a Statistic Widget

Add a statistics widget that displays key metrics, tailored to focus on either performance indicators or data quality metrics. This widget provides a quick overview and valuable insights at a glance.

<Tabs>
  <Tab title="Performance Metric">
    ```php theme={null}
    mutation createStatWidget(
      $title:String!
      $dashboardId:ID!
      $timeSeriesMetricType: TimeSeriesMetricCategory!
      $modelId:ID!
      $performanceMetric: PerformanceMetric
      $positiveClass:String!
      $filters: [StatisticWidgetFilterItemInput!]!
    ){
      createStatisticWidget(
        input:
      {
        dashboardId: $dashboardId
        title:$title
        timeSeriesMetricType:$timeSeriesMetricType
        modelId:$modelId
        performanceMetric:$performanceMetric
        positiveClass: $positiveClass
        filters:$filters
        modelVersionEnvironmentMetadataIds:[]
        modelVersionIds:[]
      })
      {
        statisticWidget{
          id
        }
      }
    }
    ```

    **variables**

    ```json theme={null}
    {
      "title": "widget-title",
      "dashboardId": "dashboard_id",
      "timeSeriesMetricType": "modelDataMetric",
      "modelId": "model_id",
      "aggregation":"DQ Metric",
      "dimension":{
        "id":"dimension_id"
        "name": "dimension_name",
        "dataType": "dimension_datatype"
      },
      "dimensionCategory": "prediction",
      "filters": []
    }
    ```
  </Tab>

  <Tab title="Data Quality Metric">
    ```php theme={null}
    mutation createStatWidget(
      $title:String!
      $dashboardId:ID!
      $timeSeriesMetricType: TimeSeriesMetricCategory!
      $modelId:ID!
      $aggregation: DataQualityMetric
      $dimension:DimensionInput
      $dimensionCategory: DimensionCategory
      $filters: [StatisticWidgetFilterItemInput!]!

    ){
      createStatisticWidget(
        input:
      {
        dashboardId: $dashboardId
        title:$title
        timeSeriesMetricType:$timeSeriesMetricType
        modelId:$modelId
        aggregation:$aggregation
        dimensionCategory:$dimensionCategory
        dimension:$dimension
        filters:$filters
        creationStatus:published
        modelVersionEnvironmentMetadataIds:[]
        modelVersionIds:[]
      })
      {
        statisticWidget{
          id
        }
      }
    }
    ```

    **variables**

    ```json theme={null}
    {
      "title": "widget-title",
      "dashboardId": "dashboard_id",
      "timeSeriesMetricType": "modelDataMetric",
      "modelId": "model_id",
      "aggregation":"count",
      "dimension":{
        "id":"dimension_id",
        "name": "dimesnion_name",
        "dataType": "dimension_datatype"
      },
      "dimensionCategory": "prediction",
      "filters": []
    }
    ```
  </Tab>
</Tabs>

### Add a Text Widget

Add a text widget to your dashboard to offer explanatory text, headings, or contextual information, enriching the dashboard's narrative and usability.

```php theme={null}
mutation createTextWidget(
  $title:String!
  $dashboardId:ID!
  $content:String!

){
  createTextWidget(
    input:
  {
    dashboardId: $dashboardId
    title:$title
    content: $content
    creationStatus:published
    
  })
  {
    textWidget{
      id
    }
  }
}
```

**variables**

```json theme={null}
{
  "title": "text-widget-title",
  "dashboardId": "dashboard_id",
  "content": "content for the text widget"
}
```

## Query for Widget IDs

```python theme={null}
query DashboardsPublic {
  dashboard: node(id: "DASHBOARD_ID") {
    ... on Dashboard {
      id
      name
      status
      creator {
        id
        name
      }
      models {
        edges {
          node {
            id
            modelType
            modelEnvironments {
              name
              id
            }
          }
        }
      }
      statisticWidgets {
        edges {
          node {
            id
            title
            gridPosition
            creationStatus
          }
        }
      }
      barChartWidgets {
        edges {
          node {
            id
            title
            gridPosition
            creationStatus
            performanceMetric
            yMin
            yMax
            sortOrder
          }
        }
      }
      lineChartWidgets {
        edges {
          node {
            id
            title
            gridPosition
            creationStatus
            yMin
            yMax
          }
        }
      }
      driftLineChartWidgets {
        edges {
          node {
            id
            title
            gridPosition
            creationStatus
            yMin
            yMax
          }
        }
      }
      textWidgets {
        edges {
          node {
            id
            title
            gridPosition
            creationStatus
            content
          }
        }
      }
      monitorLineChartWidgets {
        edges {
          node {
            id
            title
            gridPosition
            creationStatus
            yMin
            yMax
            monitor {
              __typename
              ... on WidgetMonitor {
                id
                name
                monitorTypeGlobalId
              }
              ... on MonitorEntityState {
                code
              }
            }
          }
        }
      }
    }
  }
}
```

## Query Widget Data

Query for the underlying data in a dashboard widget.

<Tabs>
  <Tab title="Distribution">
    ```php theme={null}
    query GetDistributionData {
      node(id: "WIDGET_ID") {
        ...on BarChartWidget {
          config {
            indexBy
            keys
            axisBottom {
              legend
            }
            axisLeft {
              legend
            }
          }
          bars(
            startDate: "2024-09-08T07:00:00.000Z"
            endDate: "2024-10-09T06:59:59.999Z"
            filters: []
            first: 96
            barsStartCursor: 0
          ) {
            edges {
              node {
                keysAndValues {
                  k
                  v
                  vType
                  secondaryValue
                  secondaryValueType
                  secondaryValueColorIndex
                  plotKey
                }
                evalMetricMin
                evalMetricMax
                __typename
              }
              cursor
            }
            total
            pageInfo {
              startCursor
              endCursor
              hasNextPage
              hasPreviousPage
            }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Timeseries">
    ```php theme={null}
    query GetTimeseriesData {
      node(id: "WIDGET_ID") {
        ...on LineChartWidget {
          config {
            
            axisBottom {
              legend
            }
            axisLeft {
              legend
            }
          }
          lines(
            startDate: "2024-09-08T07:00:00.000Z"
            endDate: "2024-10-09T06:59:59.999Z"
            filters: []
            timeSeriesDataGranularity: day
            timeZone: "UTC"
          ) {
            key
            dataPoints {
              x
              y
            }
              }
          
        }
      }
    }
    ```
  </Tab>

  <Tab title="Statistic Widget">
    ```php theme={null}
    query GetStatisticData {
      node(id: "WIDGET_ID") {
        ...on StatisticWidget {
          statisticValue(
            startDate: "2024-09-08T07:00:00.000Z"
            endDate: "2024-10-09T06:59:59.999Z"
            filters: [])
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Examples

| Use case                   | Example Colab                                                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Create a custom dashboard  | [Colab](https://colab.research.google.com/github/Arize-ai/tutorials_python/blob/main/Arize_Tutorials/GraphQL/create_dashbaords_graphql_tutorial.ipynb) |
| Copy an existing dashboard | [Colab](https://colab.research.google.com/github/Arize-ai/tutorials_python/blob/main/Arize_Tutorials/GraphQL/copy_dashboard_graphql_tutorial.ipynb)    |