> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-cloud-posture-management/dashboards-and-reports/monitor-dashboards-and-reports/advanced-configuration/create-custom-widgets/create-xql-widgets.md).

# Create XQL widgets

Custom XQL widgets allow you to build charts based on specific Cortex Query Language (XQL) queries. To create an XQL widget, from the **Widget Library** click **Create widget > XQL widget**.

{% stepper %}
{% step %}

### Basic configuration

1. Enter a widget name and description.
2. Select the visibility level (**Public** or **Restricted**).
   * **Restricted (Default):** Leave unselected to keep the widget visible only to you.
   * **Public:** Select this to make the widget visible to all users with **Widget Library** access.

{% hint style="info" %}
**Note:** For more information on how widget access works, see [Access to widgets](/cortex-cloud-posture-management/dashboards-and-reports/monitor-dashboards-and-reports/access-and-visibility-for-dashboards-and-reports/access-to-widgets.md).
{% endhint %}
{% endstep %}

{% step %}

### Define your query

1. In the query editor, define your XQL query.\\

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Tip:</strong> Select <strong>XQL Helper</strong> to view commonly used commands with example syntax. For more information, see <a href="/pages/naWsu9BGfIJu7V59HRqF">How to build XQL queries</a>.</p></div>
2. (Optional) Add parameters to your query to configure filters and drilldowns on your dashboard. For more information see [Add parameters to a custom XQL widget](/cortex-cloud-posture-management/dashboards-and-reports/monitor-dashboards-and-reports/advanced-configuration/create-custom-widgets/add-parameters-to-a-custom-xql-widget.md).
3. (Optional) Change the default time period using the time picker at the top right of the window. Select from the following options:

   * **Standard time frames:** Predefined ranges, such as *Last 24 hours* or *Last 30 days*.
   * **Relative time**: Define a custom window (e.g., the last `<number>` of minutes, hours, or days).
   * **Calendar:** Create a customized, static date/time period.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note:</strong> Changing the query window's time period automatically updates the config timeframe, however it is not visible in the query unless you add it manually.</p></div>
4. Click **Preview** to validate your data results.

{% hint style="info" %}
**Note:** XQL queries generated within the Widget Library do not appear in the Query Center; their results are used exclusively to build the custom widget.
{% endhint %}
{% endstep %}

{% step %}

### Define the graph visualization

In the **Widget** tab, select **Graph** and use the **Chart Editor** to configure the following fields:

* **Graph type & Subtype:** Select your visualization style (e.g., Area, Column, Pie, Single Value, Table).
* **Headers & labels:** Define header text and choose whether to display callouts or percentages.
* **Axis Mapping:** Map your data fields to the X-axis (string values) and Y-axis (numeric values).
* **Series (Optional):** Specify a field (column) to group chart results based on Y-axis values. **Note:** This option only appears for supported graph types when a single Y-axis value is selected.
* **Group additional values (Optional):** Select **Group additional values as Others** and set the maximum number of values to display. This reduces clutter by limiting the number of data values to display and grouping additional values in an “Others” category.
* **Apply default limit (Optional):** Select this to limit the number of returned results for optimal loading times. Alternatively, you can add the limit stage directly to your query.
* **Baseline (Optional):** Add a baseline reference value to the graph (available for select graph types).
* **Styling (Optional):** Customize colors, fonts, and legend placements as required.
  {% endstep %}

{% step %}

### Finalize and save widget

1. (Optional) Click **Add to query** to insert your chart preferences directly into the query syntax.
2. Click **Save widget** to add the widget to your library.
   {% endstep %}
   {% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/cortex-cloud-posture-management/dashboards-and-reports/monitor-dashboards-and-reports/advanced-configuration/create-custom-widgets/create-xql-widgets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.