Documentation for automated readers
A curated documentation index is available at: https://grafana.com/llms.txt
A complete documentation index is available at: https://grafana.com/llms-full.txt
These indexes can help with page discovery before fetching individual documents.
This page is also available in Markdown, which may be easier for automated readers and AI tools to parse than HTML. The Markdown version is available at https://grafana.com/docs/grafana-cloud/ai-tools/machine-learning/additional-configuration/gcx.md, or by sending Accept: text/markdown to https://grafana.com/docs/grafana-cloud/ai-tools/machine-learning/additional-configuration/gcx/. For broader documentation discovery, the curated index is available at https://grafana.com/llms.txt and the complete index is available at https://grafana.com/llms-full.txt.
Use gcx to manage Machine Learning resources
gcx is a command-line interface (CLI) that you and coding agents can use to manage Grafana resources. With gcx ml, you and coding agents can list, inspect, create, update, and delete forecasts, holidays, outlier detectors, and their alerts. Use it to check what is configured on your stack and make changes from the command line.
Before you begin
Authenticate
gcxwith the preferred method for your Grafana Cloud stack.To check which configuration
gcxuses, run:Bashgcx config view
Manage resources with gcx ml
Use gcx ml to inspect and manage Machine Learning resources:
| Command | Purpose | Operations |
|---|---|---|
gcx ml jobs | Manage forecasts and their alerts | list, get, create, update, delete, list-alerts, get-alert, create-alert, update-alert, delete-alert |
gcx ml holidays | Manage holidays | list, get, create, update, delete |
gcx ml outlier-detectors | Manage outlier detectors and their alerts | list, get, create, update, delete, list-alerts, get-alert, create-alert, update-alert, delete-alert |
The following examples use forecasts. To run them on holidays or outlier detectors, replace jobs with holidays or outlier-detectors:
List all forecasts. By default, the list shows up to 50 records. Use
--limitto change the number, or--limit 0to show all records:Bashgcx ml jobs listGet a single forecast by its ID. Use
-o yamlor-o jsonto save it to a file you can read or edit:Bashgcx ml jobs get <ID> -o yaml > forecast.yamlCreate a forecast from a file. For example, save the following definition as
forecast.yamland replace the data source UID and the query with the values for your stack:YAMLname: request-forecast metric: request_forecast algorithm: grafana_prophet_1_0_1 datasourceType: prometheus datasourceUid: <DATA_SOURCE_UID> queryParams: expr: sum(rate(http_requests_total[5m])) interval: 300 trainingWindow: 7776000 trainingFrequency: 86400Then create the forecast:
Bashgcx ml jobs create --filename forecast.yamlCreating a forecast can start model training. To check the file without making changes, add
--dry-run. This validates the input locally only.Update a forecast. Edit the file and run
updatewith the forecast ID. Updating a forecast can also start model training:Bashgcx ml jobs update <ID> --filename forecast.yamlDelete a forecast by its ID:
Bashgcx ml jobs delete <ID>gcxasks for confirmation before it deletes the forecast. To skip the prompt, add--force.
Manage alerts
Forecasts and outlier detectors can have alerts. Alerts belong to a forecast or outlier detector, so every alert command needs the job or outlier detector ID:
gcx ml jobs list-alerts <JOB_ID>The following operations are available on gcx ml jobs:
list-alerts <JOB_ID>get-alert <JOB_ID> <ALERT_ID>create-alert <JOB_ID> --filename alert.yamlupdate-alert <JOB_ID> <ALERT_ID> --filename alert.yamldelete-alert <JOB_ID> <ALERT_ID>
To run the alert commands on outlier detectors, run gcx ml outlier-detectors and replace <JOB_ID> with the <OUTLIER_DETECTOR_ID>.
Note
Alerts for outlier detectors need a non-zero
window, for example5m. Don’t setthresholdoranomalyConditionon them.
Was this page helpful?
Related resources from Grafana Labs


