MetricPredictor API reference

MetricPredictor configures metric history, training and forecast models. Use the predictive trigger reference to connect its predictions to a ScaledObject.

API details

Applies to Predictor v0.1.6.

Group: keda.kedify.io. Kind: MetricPredictor. Scope: Namespaced. The older standalone controller used kedify.io; do not mix those API groups.

Defaults below are schema defaults. Required fields are required within their containing object. Controller behavior can impose additional conditions.

v1alpha1 fields

Served: true; storage: true.

spec

Field	Type	Required	Schema default	Meaning and validation
`spec`	object	Yes	Not specified	spec defines the desired state of MetricPredictor .spec.model is optional, however .spec.source is always required
`spec.model`	object	No	Not specified	Model further specifies the model itself.
`spec.model.changepointPriorScale`	string	No	Not specified	By default, this parameter is set to 0.1. Increasing it will make the trend more flexible. Large values will allow many changepoints, small values will allow few changepoints. https://facebook.github.io/prophet/docs/trend_changepoints.html#automatic-changepoint-detection-in-prophet
`spec.model.defaultHorizon`	string	No	`"1m"`	When asking the trained model for predictions, what interval, to the future, should be used from now. default: “1m”
`spec.model.holidays`	object	No	Not specified
`spec.model.holidays.countryCode`	string	No	`"US"`	Country code for holidays (ISO 3166-1 alpha-2), if left empty, no holidays will be used. Example: “US”,“CZ”,“CA”,“CN”,“DE”,“JP”, etc. default: US
`spec.model.holidays.strength`	string	No	`"10"`	Parameter (float) modulating the strength of the holiday components model corresponds to holidays_prior_scale parameter in Prophet Reducing this parameter dampens holiday effects default: 10
`spec.model.lookBackPeriod`	string	No	`"2y"`	When retraining the model to fit the data. What portion of the data should be used. If not specified or set to 0, all the available measurements will be used, otherwise only those from interval [now-lookBackPeriod, now] default: “2y” minLength: 1; pattern: ”^(\d+y)?(\d+mo)?(\d+d)?(\d+h)?(\d+m)?(\d+s)?$”
`spec.model.name`	string	No	Not specified	Explicit name for the model, if not provided it will be inferred from this MetricPredictor CR instance metadata default: “{namespace}*{name}”
`spec.model.retention`	string	No	`"2y"`	How long the metric data should be stored in the internal database. When calling retrain, we will delete the older metric data than this period default: 2y minLength: 1; pattern: ”^(\d+y)?(\d+mo)?(\d+d)?(\d+h)?(\d+m)?(\d+s)?$”
`spec.model.retrainInterval`	string	No	`"1h"`	How often the model should be automatically retrained to fit the new data. minLength: 1; pattern: ”^(\d+y)?(\d+mo)?(\d+d)?(\d+h)?(\d+m)?(\d+s)?$”
`spec.model.seasonality`	object	No	Not specified	Further specifies the seasonality patterns that model should be looking for.
`spec.model.seasonality.custom`	object	No	Not specified	Allows specifying custom length and resolution of the seasonality pattern to look for. By default, we create for each model also 6-hr custom seasonality called ‘six’ with fourierOrder=10.
`spec.model.seasonality.custom.fourierOrder`	integer	No	`16`	Number of components of Fourier series approximation https://en.wikipedia.org/wiki/Fourier_series higher numbers can capture more sophisticated seasonal patterns, but can also lead to model overfitting. In a broader sense this can be thought of as ‘resolution’. default: 16
`spec.model.seasonality.custom.name`	string	Yes	Not specified	Name of the custom seasonality, it will be displayed on the component graph minLength: 1
`spec.model.seasonality.custom.period`	string	Yes	Not specified	Custom length of the expected seasonal pattern. For example if we expect our data to exhibit an 8-hour repeating pattern, put 8h here. minLength: 1; pattern: ”^(\d+y)?(\d+mo)?(\d+d)?(\d+h)?(\d+m)?(\d+s)?$”
`spec.model.seasonality.daily`	string	No	`"auto"`	Can be ‘auto’ (default), ‘true’, ‘false’, or a number of Fourier terms to generate (all passed as string). pattern: ”^([Aa]uto)\|([Tt]rue)\|([Ff]alse)\|(\d+)$”
`spec.model.seasonality.mode`	string	No	`"additive"`	‘additive’ (default) or ‘multiplicative’. https://facebook.github.io/prophet/docs/multiplicative_seasonality.html enum: [“additive”,“multiplicative”]
`spec.model.seasonality.weekly`	string	No	`"auto"`	Can be ‘auto’ (default), ‘true’, ‘false’, or a number of Fourier terms to generate (all passed as string). pattern: ”^([Aa]uto)\|([Tt]rue)\|([Ff]alse)\|(\d+)$”
`spec.model.seasonality.yearly`	string	No	`"false"`	Can be ‘auto’, ‘true’, ‘false’ (default), or a number of Fourier terms to generate (all passed as string). pattern: ”^([Aa]uto)\|([Tt]rue)\|([Ff]alse)\|(\d+)$”
`spec.model.type`	string	No	`"Prophet"`	What type of model predictor should be used, allowed values: prophet default: prophet
`spec.source`	object	Yes	Not specified	Source describes the metric source for the predictive model. x-kubernetes-validations: [{“message”:“At least one of the fields: ‘keda’, ‘oneShotCsv’, ‘oneShotPrometheus’ or ‘otel’ must be specified”,“rule”:“has(self.keda) \|\| has(self.oneShotCsv) \|\| has(self.oneShotPrometheus) \|\| has(self.otel)”}]
`spec.source.collectionInterval`	string	No	`"1m"`	How often we should be ingesting the metric data for model KEDA typically send the metric each 15s, this way we can downsample the metrics and save space. default: 1m todo: this
`spec.source.keda`	object	No	Not specified	What KEDA Resource (ScaledObject, ScaledJob) should be used as metric source for this model. It is assumed that the KEDA resource is located in the same namespace as MP resource. x-kubernetes-validations: [{“message”:“When Scaled{Object,Job} is used as metric source, trigger name and name must be both specified”,“rule”:“has(self.name) == has(self.triggerName)”}]
`spec.source.keda.active`	boolean	No	`true`	Marks the metric subscription as ON or OFF. false -> ignore default: true
`spec.source.keda.kind`	string	No	Not specified	Kind can be either ‘scaledjob’ or ‘scaledobject’ default: scaledobject enum: [“scaledjob”,“scaledobject”]
`spec.source.keda.name`	string	Yes	Not specified	Name of the ScaledObject or ScaledJob located in the same namespace as this MetricPredictor resource minLength: 1
`spec.source.keda.triggerName`	string	Yes	Not specified	What trigger name in the referenced Scaled{Object,Job} should be used as metric source for the model. The controller will subscribe to KEDA metrics and based on the trigger name and scaled object name, it will only those metrics that it is interested to minLength: 1
`spec.source.oneShotCsv`	object	No	Not specified	Use this field for bootstraping the model with initial data.
`spec.source.oneShotCsv.active`	boolean	No	`true`	Marks the CSV source as ON or OFF. false -> ignore When the CSV is imported, it will update the .status sub-resource and subsequent ingestion will not be made. default: true
`spec.source.oneShotCsv.addTimestamps`	boolean	No	`false`	When enabled, the timestamp column will be added to the CSV data even if not present. Use this option together with timestampPeriod to set up the correct timing. default: false
`spec.source.oneShotCsv.timestampColumnName`	string	No	`"ds"`	Name of column that contains timestamps in the referenced CSV file default: ‘ds’
`spec.source.oneShotCsv.timestampPeriod`	string	No	`"30s"`	If addTimestamps is true, what should be the time delta between the two samples The timestamp will be calculated so that last data sample in the CSV file represents the time.now() and the very first one will have timestamp time.now() - number_of_samples*timestampPeriod default: ’30s’
`spec.source.oneShotCsv.timezone`	string	No	`"UTC"`	Timezone used when parsing CSV timestamps or when generating them with addTimestamps=true. All timestamps are converted to UTC before they are stored. Example: Europe/Prague default: ‘UTC’
`spec.source.oneShotCsv.url`	string	Yes	Not specified	Url that points to a CSV file that should be used to bootstrap the model with initial metric data example: https://raw.githubusercontent.com/facebook/prophet/main/examples/example_wp_log_peyton_manning.csv it is assumed that first line of the file contains header with column names and CSV contains columns called ‘ds’ and ‘y’. if not, use TimestampColumnName and ValueColumnName to select some other columns
`spec.source.oneShotCsv.valueColumnName`	string	No	`"y"`	Name of column that contains the measured values in the referenced CSV file default: ‘y’
`spec.source.oneShotPrometheus`	object	No	Not specified	Use this field for bootstrapping the model with initial data from a Prometheus HTTP API. x-kubernetes-validations: [{“message”:“start, end and step must be specified together”,“rule”:”!(has(self.start) \|\| has(self.end) \|\| has(self.step)) \|\| (has(self.start) && has(self.end) && has(self.step))”}]
`spec.source.oneShotPrometheus.active`	boolean	No	`true`	Marks the Prometheus one-shot source as ON or OFF. false -> ignore. When the Prometheus data is imported, it will update the .status sub-resource and subsequent ingestion will not be made. default: true
`spec.source.oneShotPrometheus.customHeaders`	string	No	Not specified	Optional comma-separated HTTP headers passed to Prometheus requests. Example: X-Client-Id=cid,X-Tenant-Id=tid
`spec.source.oneShotPrometheus.end`	string	No	Not specified	Inclusive end time for an explicit range query, as RFC3339 or a Unix timestamp. Must be specified together with Start and Step. Example: 2026-07-08T00:00:00Z minLength: 1
`spec.source.oneShotPrometheus.query`	string	Yes	Not specified	PromQL expression used to load samples. When Start, End and Step are omitted, the expression is evaluated as an instant query and may use a range-producing PromQL subquery such as avg(metric)[1w:30s]. When Start, End and Step are set, the expression is evaluated with /api/v1/query_range and must return a scalar or instant vector. minLength: 1
`spec.source.oneShotPrometheus.start`	string	No	Not specified	Inclusive start time for an explicit range query, as RFC3339 or a Unix timestamp. Must be specified together with End and Step. Omit all three fields to use the instant-query/subquery mode. Example: 2026-07-01T00:00:00Z minLength: 1
`spec.source.oneShotPrometheus.step`	string	No	Not specified	Query resolution for an explicit range query, as a Prometheus duration or a number of seconds. Must be greater than zero and specified together with Start and End. Example: 30s minLength: 1
`spec.source.oneShotPrometheus.timeout`	string	No	`"30s"`	Timeout used both for the Prometheus HTTP request and as the query timeout parameter. default: ’30s’
`spec.source.oneShotPrometheus.url`	string	Yes	Not specified	Url that points to a Prometheus server. The controller checks /version, uses /api/v1/parse_query to validate Query on Prometheus 3.4 and newer, and uses /api/v1/query or /api/v1/query_range to fetch the data. Example: http://prometheus-server.observability.svc.cluster.local minLength: 1
`spec.source.otel`	object	No	Not specified	Metric data will be obtained by OTLP receiver. For this metric source, make sure another OTel exporter is configured to feed this receiver.
`spec.source.otel.active`	boolean	No	`true`	Marks the metric subscription as ON or OFF. false -> ignore default: true
`spec.source.otel.metricName`	string	Yes	Not specified	Name of the metric whose values should be recorded for the model Example: http_requests_total
`spec.source.otel.metricType`	string	No	Not specified	default: gauge enum: [“gauge”,“sum”,“histogram”,“exponentialhistogram”,“summary”]
`spec.source.otel.requiredLabels`	object	No	Not specified	Only metric having all these labels is recorded this way you can further restrict the values pertaining to the model all the unspecified labels are then considered as matching Example: handler: /api app: myserver
`spec.source.otel.requiredLabels.*`	string	No	Not specified

status

Field	Type	Required	Schema default	Meaning and validation
`status`	object	No	Not specified	status defines the observed state of MetricPredictor
`status.conditions`	array	No	Not specified	The status of each condition is one of True, False, or Unknown.
`status.conditions[]`	object	No	Not specified
`status.conditions[].lastTransitionTime`	string	No	Not specified
`status.conditions[].message`	string	No	Not specified	A human-readable message indicating details about the transition.
`status.conditions[].reason`	string	No	Not specified	The reason for the condition’s last transition.
`status.conditions[].status`	string	Yes	Not specified	Status of the condition, one of True, False, Unknown.
`status.conditions[].type`	string	Yes	Not specified	Type of condition
`status.modelName`	string	No	Not specified	Name of the ML model that is used for forecasting.
`status.source`	object	No	Not specified	Details about the metric source
`status.source.active`	integer	No	Not specified
`status.source.detail`	string	No	Not specified
`status.source.kind`	string	No	Not specified
`status.source.name`	string	No	Not specified	pattern: ”^(KEDA\|OTel\|CSV\|Prometheus\|no sources)(,(KEDA\|OTel\|CSV\|Prometheus))*$”

Inspect the installed contract

kubectl get crd metricpredictors.keda.kedify.io -o yaml
kubectl explain metricpredictor.spec --api-version=keda.kedify.io/v1alpha1 --recursive

Example

This resource trains from a named trigger on an existing ScaledObject in the same namespace. Use strings for decimal model parameters and 7d for a week; the duration schema does not accept 1w.

apiVersion: keda.kedify.io/v1alpha1
kind: MetricPredictor
metadata:
  name: e-shop
  namespace: app
spec:
  model:
    type: Prophet
    defaultHorizon: 2m
    lookBackPeriod: 1y
    retention: 1y
    retrainInterval: 7d
    changepointPriorScale: "0.1"
    seasonality:
      weekly: "auto"
  source:
    keda:
      kind: scaledobject
      name: e-shop-nginx
      triggerName: http-requests
      active: true

Use, verify and diagnose

Install → train and scale a sample workload → inspect and tune the model. Check resource status and events after changes. Use predictive troubleshooting for missing history or inaccurate forecasts.