Nixtla Finetune API

openapi: 3.1.0
info:
  title: Nixtla Forecast Anomaly Detection Finetune 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: Finetune
paths:
  /v2/finetune:
    post:
      summary: Foundational Time Series Model Multi Series Finetuning
      description: Fine-tune the large time model to your data and save it for later use. It takes a JSON as an input containing information like the series frequency and historical data. (See below for a full description of the parameters.) The response contains the ID of the finetuned model, which you can provide in other endpoints to use that model to make the forecasts. Get your token at https://nixtla.io/free-trial?utm_source=nixtla.io&utm_campaign=/docs/api-reference.
      operationId: v2_finetune_v2_finetune_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FinetuneInput'
              examples:
              - finetune_steps: 10
                freq: MS
                model: timegpt-1
                series:
                  sizes:
                  - 36
                  y:
                  - 0
                  - 1
                  - 2
                  - 3
                  - 4
                  - 5
                  - 6
                  - 7
                  - 8
                  - 9
                  - 10
                  - 11
                  - 12
                  - 13
                  - 14
                  - 15
                  - 16
                  - 17
                  - 18
                  - 19
                  - 20
                  - 21
                  - 22
                  - 23
                  - 24
                  - 25
                  - 26
                  - 27
                  - 28
                  - 29
                  - 30
                  - 31
                  - 32
                  - 33
                  - 34
                  - 35
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinetuneOutput'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
      x-fern-sdk-method-name: v2/finetune
      tags:
      - Finetune
components:
  schemas:
    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
    FinetuneInput:
      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.
        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
        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: 10
        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
        output_model_id:
          anyOf:
          - type: string
            pattern: ^[a-zA-Z0-9\-_]{1,36}$
          - type: 'null'
          title: Output Model Id
          description: ID to assign to the finetuned model
        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
        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.
        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. '
      type: object
      required:
      - series
      - freq
      title: FinetuneInput
    FinetuneOutput:
      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
        finetuned_model_id:
          type: string
          pattern: ^[a-zA-Z0-9\-_]{1,36}$
          title: Finetuned Model Id
      type: object
      required:
      - input_tokens
      - output_tokens
      - finetune_tokens
      - finetuned_model_id
      title: FinetuneOutput
    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
  securitySchemes:
    HTTPBearer:
      type: http
      description: HTTPBearer
      scheme: bearer