> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nx1cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit an AutoML training job

> Validate the request, render the DAG, persist a queued job.



## OpenAPI

````yaml post /api/automl/train
openapi: 3.1.0
info:
  title: Nx1 AI API
  description: |

    AI API for Nx1 Data Platform Management and Automated Data Tasks.

    Authentication is required via PSK in Authorization header.

    Default PSK is | [ask a friend] |
  version: 0.10.2
servers: []
security: []
paths:
  /api/automl/train:
    post:
      tags:
        - AutoML Training
      summary: Submit an AutoML training job
      description: Validate the request, render the DAG, persist a queued job.
      operationId: submit_training_api_automl_train_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/api__models__automl_training_models__AutoMLTrainingRequest
        required: true
      responses:
        '201':
          description: Job created with rendered DAG.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoMLTrainingJobResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - OAuth2AuthorizationCodeBearer: []
        - APIKeyHeader: []
components:
  schemas:
    api__models__automl_training_models__AutoMLTrainingRequest:
      properties:
        name:
          type: string
          title: Name
          description: Human-readable training run name.
        domain:
          type: string
          title: Domain
          description: Business domain for governance.
        owner:
          type: string
          title: Owner
          description: Username who owns this run.
        source_table:
          type: string
          title: Source Table
          description: >-
            Fully qualified Iceberg training table in `catalog.schema.table`
            format.
        problem_type:
          $ref: '#/components/schemas/ProblemType'
        algorithm:
          $ref: '#/components/schemas/AutoMLAlgorithm'
        preset:
          $ref: '#/components/schemas/Preset'
          default: balanced
        label_column:
          anyOf:
            - type: string
            - type: 'null'
          title: Label Column
        positive_class_value:
          anyOf:
            - {}
            - type: 'null'
          title: Positive Class Value
          description: Value treated as the positive class for binary classification.
        feature_columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Feature Columns
          description: >-
            Override feature columns. If omitted, the job infers features from
            the table schema, excluding the label, time/group/bandit role
            columns, and any `exclude_columns`.
        exclude_columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Exclude Columns
          description: >-
            Columns to drop from inferred features. For example, ID columns,
            entity-grain columns, or columns like `trans_num`. Ignored when the
            caller sets `feature_columns`.
        group_column:
          anyOf:
            - type: string
            - type: 'null'
          title: Group Column
          description: Group/query identifier for ranking.
        action_column:
          anyOf:
            - type: string
            - type: 'null'
          title: Action Column
        reward_column:
          anyOf:
            - type: string
            - type: 'null'
          title: Reward Column
        probability_column:
          anyOf:
            - type: string
            - type: 'null'
          title: Probability Column
        context_columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Context Columns
        train_split_cutoff:
          anyOf:
            - type: string
            - type: 'null'
          title: Train Split Cutoff
          description: >-
            Date cutoff string in International Organization for Standardization
            (ISO) 8601 format. Rows with the time column before the cutoff go to
            train, those at or after go to test. Defaults to an 80/20 random
            split when omitted.
        time_column:
          anyOf:
            - type: string
            - type: 'null'
          title: Time Column
          description: >-
            Column used by `train_split_cutoff`. Required when you configure
            `train_split_cutoff`.
        hyperparameter_overrides:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Hyperparameter Overrides
        resources:
          anyOf:
            - $ref: '#/components/schemas/SparkResourceSpec'
            - type: 'null'
        enable_shap:
          type: boolean
          title: Enable Shap
          default: true
        experiment_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Experiment Name
        registered_model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Registered Model Name
        feature_engineering_job_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Feature Engineering Job Id
        trigger_now:
          type: boolean
          title: Trigger Now
          default: true
      type: object
      required:
        - name
        - domain
        - owner
        - source_table
        - problem_type
        - algorithm
      title: AutoMLTrainingRequest
      description: |-
        Request to train an AutoML model.

        Required fields depend on ``problem_type``. See each field's description
        for details. Invalid combinations return a 422 validation error.
    AutoMLTrainingJobResponse:
      properties:
        job_id:
          type: string
          format: uuid
          title: Job Id
        name:
          type: string
          title: Name
        domain:
          type: string
          title: Domain
        owner:
          type: string
          title: Owner
        source_table:
          type: string
          title: Source Table
        problem_type:
          $ref: '#/components/schemas/ProblemType'
        algorithm:
          $ref: '#/components/schemas/AutoMLAlgorithm'
        preset:
          $ref: '#/components/schemas/Preset'
        status:
          $ref: '#/components/schemas/AutoMLTrainingJobStatus'
        rendered_dag:
          anyOf:
            - type: string
            - type: 'null'
          title: Rendered Dag
          description: The rendered DAG source. Populated on creation.
        mlflow_run_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Mlflow Run Id
        mlflow_experiment_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Mlflow Experiment Name
        registered_model_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Registered Model Name
        airflow_dag_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Airflow Dag Id
        airflow_dag_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Airflow Dag Url
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
        feature_engineering_job_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Feature Engineering Job Id
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - job_id
        - name
        - domain
        - owner
        - source_table
        - problem_type
        - algorithm
        - preset
        - status
        - created_at
        - updated_at
      title: AutoMLTrainingJobResponse
      description: A persisted training job.
    ErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: A brief description of the error that occurred.
        code:
          type: integer
          title: Code
          description: The HTTP status code associated with the error.
          default: 500
      type: object
      required:
        - error
      title: ErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProblemType:
      type: string
      enum:
        - binary_classification
        - multiclass_classification
        - regression
        - ranking
        - anomaly_detection
        - contextual_bandit
      title: ProblemType
      description: Supervised / unsupervised problem categories.
    AutoMLAlgorithm:
      type: string
      enum:
        - lightgbm_classifier
        - lightgbm_regressor
        - lightgbm_ranker
        - xgboost_classifier
        - xgboost_regressor
        - xgboost_ranker
        - isolation_forest
        - vw_classifier
        - vw_regressor
        - vw_contextual_bandit
      title: AutoMLAlgorithm
      description: Supported AutoML algorithms.
    Preset:
      type: string
      enum:
        - fast
        - balanced
        - best_quality
      title: Preset
      description: Tuning presets shared across algorithms.
    SparkResourceSpec:
      properties:
        executor_instances:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Executor Instances
        executor_cores:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Executor Cores
        executor_memory:
          anyOf:
            - type: string
            - type: 'null'
          title: Executor Memory
          examples:
            - 8g
        executor_memory_overhead:
          anyOf:
            - type: string
            - type: 'null'
          title: Executor Memory Overhead
          examples:
            - 1g
        driver_memory:
          anyOf:
            - type: string
            - type: 'null'
          title: Driver Memory
          examples:
            - 4g
        driver_cores:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Driver Cores
      type: object
      title: SparkResourceSpec
      description: |-
        Optional Spark resource overrides for the training DAG.

        Any field you omit auto-sizes from the dataset's row count,
        byte size, and feature width via ``automl_resource_sizing``. A field
        you provide always wins over the derived value. Memory follows
        Spark's ``<n>g`` / ``<n>m`` format. For example, ``"8g"``.
    AutoMLTrainingJobStatus:
      type: string
      enum:
        - ready
        - queued
        - running
        - complete
        - failed
      title: AutoMLTrainingJobStatus
      description: |-
        Lifecycle of an AutoML training job.

        - `READY`: DAG uploaded but not yet triggered. The user opted out of
          auto-trigger at create time. Manual trigger flips it to `QUEUED`.
        - `QUEUED`: DAG triggered, waiting for Airflow to pick it up.
        - `RUNNING`: Airflow has the run going.
        - `COMPLETE`/`FAILED`: terminal.
    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
  securitySchemes:
    OAuth2AuthorizationCodeBearer:
      type: oauth2
      flows:
        authorizationCode:
          scopes: {}
          authorizationUrl: >-
            https://sso-rapid.rapid.nx1cloud.com/realms/rapid/protocol/openid-connect/auth
          tokenUrl: >-
            https://sso-rapid.rapid.nx1cloud.com/realms/rapid/protocol/openid-connect/token
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization-PSK

````