Nixtla Cross Validation API

openapi: 3.1.0
info:
  title: Nixtla Forecast Anomaly Detection Cross Validation API
  description: API for TimeGPT forecast. Just send your data as json and get results. We do the heavy lifting.
  version: 0.2.8
servers:
- url: https://api.nixtla.io
tags:
- name: Cross Validation
paths:
  /v2/cross_validation:
    post:
      summary: Foundational Time Series Model Multi Series Cross Validation
      description: Perform Cross Validation for multiple series
      operationId: v2_cross_validation_v2_cross_validation_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrossValidationInput'
              examples:
              - freq: D
                h: 2
                n_windows: 1
                series:
                  sizes:
                  - 5
                  - 3
                  y:
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  - 10
                  - 20
                  - 30
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrossValidationOutput'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      x-fern-sdk-method-name: v2/cross_validation
      tags:
      - Cross Validation
components:
  schemas:
    CrossValidationInput:
      properties:
        series:
          $ref: '#/components/schemas/SeriesWithFutureExogenous'
        freq:
          type: string
          title: Freq
          description: The frequency of the data represented as a string. 'D' for daily, 'M' for monthly, 'H' for hourly, and 'W' for weekly frequencies are available.
        n_windows:
          type: integer
          exclusiveMinimum: 0
          title: N Windows
          description: Number of windows to evaluate.
          default: 1
        h:
          type: integer
          exclusiveMinimum: 0
          title: H
          description: The forecasting horizon. This represents the number of time steps into the future that the forecast should predict.
        full_history:
          type: boolean
          title: Full History
          description: Forecast across the entire series history (the `add_history` use case). The horizon and number of windows are derived server-side (any supplied `h` / `n_windows` are ignored), and the exogenous model is refit a bounded number of times to keep whole-history requests fast. Has no effect without exogenous features.
          default: false
        model:
          type: string
          title: Model
          description: Model to use as a string. Common options are (but not restricted to) `timegpt-1` and `timegpt-1-long-horizon.` Full options vary by different users. Contact support@nixtla.io for more information. We recommend using `timegpt-1-long-horizon` for forecasting if you want to predict more than one seasonal period given the frequency of your data.
          default: timegpt-1
        clean_ex_first:
          type: boolean
          title: Clean Ex First
          description: A boolean flag that indicates whether the API should preprocess (clean) the exogenous signal before applying the large time model. If True, the exogenous signal is cleaned; if False, the exogenous variables are applied after the large time model.
          default: true
        level:
          anyOf:
          - items:
              anyOf:
              - type: integer
                exclusiveMaximum: 100
                minimum: 0
              - type: number
                exclusiveMaximum: 100
                minimum: 0
            type: array
            minItems: 1
          - type: 'null'
          title: Level
          description: A list of values representing the prediction intervals. Each value is a percentage that indicates the level of certainty for the corresponding prediction interval. For example, [80, 90] defines 80% and 90% prediction intervals.
        finetune_steps:
          type: integer
          minimum: 0
          title: Finetune Steps
          description: The number of tuning steps used to train the large time model on the data. Set this value to 0 for zero-shot inference, i.e., to make predictions without any further model tuning.
          default: 0
        finetune_loss:
          type: string
          enum:
          - default
          - mae
          - mse
          - rmse
          - mape
          - smape
          - poisson
          title: Finetune Loss
          description: The loss used to train the large time model on the data. Select from ['default', 'mae', 'mse', 'rmse', 'mape', 'smape', 'poisson']. It will only be used if finetune_steps larger than 0. Default is a robust loss function that is less sensitive to outliers.
          default: default
        finetune_depth:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          title: Finetune Depth
          description: The depth of the finetuning. Uses a scale from 1 to 5, where 1 means little finetuning, and 5 means that the entire model is finetuned. Note that this parameter is only effective for timegpt-1 and timegpt-1-long-horizon models, meanwhile it has no effect on the other models. By default, the value is set to 1.
          default: 1
        finetuned_model_id:
          anyOf:
          - type: string
            pattern: ^[a-zA-Z0-9\-_]{1,36}$
          - type: 'null'
          title: Finetuned Model Id
          description: ID of previously finetuned model
        step_size:
          anyOf:
          - type: integer
            exclusiveMinimum: 0
          - type: 'null'
          title: Step Size
          description: Step size between each cross validation window. If None it will be equal to the forecasting horizon.
        hist_exog:
          anyOf:
          - items:
              type: integer
              minimum: 0
            type: array
          - type: 'null'
          title: Hist Exog
          description: Zero-based indices of the exogenous features to treat as historical.
        refit:
          type: boolean
          title: Refit
          description: Fine-tune the model in each window. If `False`, only fine-tunes on the first window. Only used if `finetune_steps` > 0.
          default: true
        multivariate:
          type: boolean
          title: Multivariate
          description: Compute multivariate predictions across a batch of multiple time series. Requires all time series with overlapping dates. Note that this is only effective for timegpt-2.1 model and it has no effect on the other models. By default, the value is set to False.
          default: false
        model_parameters:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Model Parameters
          description: 'Optional dictionary of parameters to customize the behavior of the large time model. '
        feature_contributions:
          type: boolean
          title: Feature Contributions
          description: Compute the exogenous features contributions to the forecast.
          default: false
      type: object
      required:
      - series
      - freq
      - h
      title: CrossValidationInput
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SeriesWithFutureExogenous:
      properties:
        X_future:
          anyOf:
          - items:
              items:
                anyOf:
                - type: number
                - type: string
              type: array
            type: array
          - type: 'null'
          title: X Future
          description: Future values of the exogenous features. Each feature must be a list of size number of series times the forecast horizon (h).
        X:
          anyOf:
          - items:
              items:
                anyOf:
                - type: number
                - type: string
              type: array
            type: array
          - type: 'null'
          title: X
          description: Historic values of the exogenous features. Each feature must be a list of the same size as the target (y).
        categorical_exog:
          anyOf:
          - items:
              type: integer
              minimum: 0
            type: array
          - type: 'null'
          title: Categorical Exog
          description: Zero-based indices of the columns in X that are categorical features.
        y:
          items:
            type: number
          type: array
          title: Y
          description: Historic values of the target.
        sizes:
          items:
            type: integer
          type: array
          title: Sizes
          description: Sizes of the individual series.
      type: object
      required:
      - y
      - sizes
      title: SeriesWithFutureExogenous
    CrossValidationOutput:
      properties:
        input_tokens:
          type: integer
          minimum: 0
          title: Input Tokens
        output_tokens:
          type: integer
          minimum: 0
          title: Output Tokens
        finetune_tokens:
          type: integer
          minimum: 0
          title: Finetune Tokens
        mean:
          items:
            type: number
          type: array
          title: Mean
        sizes:
          items:
            type: integer
          type: array
          title: Sizes
        idxs:
          items:
            type: integer
          type: array
          title: Idxs
        intervals:
          anyOf:
          - additionalProperties:
              items:
                type: number
              type: array
            type: object
          - type: 'null'
          title: Intervals
        feature_contributions:
          anyOf:
          - items:
              items:
                type: number
              type: array
            type: array
          - type: 'null'
          title: Feature Contributions
      type: object
      required:
      - input_tokens
      - output_tokens
      - finetune_tokens
      - mean
      - sizes
      - idxs
      title: CrossValidationOutput
  securitySchemes:
    HTTPBearer:
      type: http
      description: HTTPBearer
      scheme: bearer