AutoML API

This document describes each endpoint of VecML RESTful API for Automated Maching Learning (AutoML), including:

• Endpoint URL
• Expected Request Body (JSON)
• Response Format (JSON)
• Relevant Details or Constraints
• Example Requests / Responses

All RESTful API calls to VecML cloud database should be sent to: https://aidb.vecml.com/api. All endpoints require a JSON body unless otherwise noted.

Rate and request size limit

For resource allocation and server stability, the server enforces a rate limit on the number of API calls per second. If exceeded, the server responds with:

400 Bad Request
Request limit reached, please try again later

Please avoid high-frequency API calls. For example, when inserting multiple vectors, please use /add_data_batch instead of iteratively calling /add_data.

The size of each request cannot pass 200MB.

Managing Unique IDs for vectors

Vectors are identified by UNIQUE string IDs. While VecML provide a way to maintain auto-generated string IDs internally, we highly encourage the users to maintain and specify unique IDs for the vectors, for the convenience of database operations. Multiple ways are available to specify the IDs, please check the data inserting functions for details.

---

Authentication (API key):

VecML RESTful API requests are authenticated through user's API key. The API key can be generated as follows:

1. Go to https://account.vecml.com/user-api-keys , sign up a free VecML account.
2. After registration, you can get an API key by clicking "Create New API Key".
3. This unique API key will only be seen once at the creation time, so please keep the API key safely. If you need to re-generate an API key, simply delete the previous one and then create a new key.

---

Getting Started: Project and Dataset Management

To use AutoML APIs, the user first needs to upload/insert a vector collection (dataset) to VecML cloud.

See the vector DB API documentation for Project Management and Dataset Management. Also check Job Management for managing the async job status for data insertion/upload.

---

An Example WorkFlow

VecML Database provides fast and performant built-in ML tools for your project and bussiness. Below is a standard workflow using VecML RESTful API for AutoML model training:

1. Call /create_project to create a new project.

2. Create a dataset (or collection, interchangably) within the project. Two convenient options are:

   (i) Call /init to initialize/create a new dataset. Then use /add_data_batch to (iteratively) add batch of vectors to the dataset.

   (ii) Upload a data file (supported types: csv, json, binary format, libsvm) as a dataset using /upload. You can iteratively upload files to a data collection.

   Note: When uploading data, attributes are required to train AutoML models. In this context, "attributes" should include the label (for classification) or response (for regression), and other categorical features that you want to include in the model. We provide easy ways to specify the attributes along with the data vectors, see the endpoint instruction for more details.

3. Train an AutoML model for the dataset using /train_automl_model.

   Note: Before starting model training, please call /get_upload_data_status to confirm that the data insertion has finished. Otherwise, model training may raise an error while inserting data.

4. Make predictions on predict/test dataset /automl_preidct.

   Note: Before search, please call /get_automl_training_status to confirm the training has finished.

The following is an example python code to demonstrate the API workflow.

Python

import requests
import json
import numpy as np
import time

# Configuration
API_KEY = "replace_this_with_your_api_key"
BASE_URL = "https://aidb.vecml.com/api"

def make_request(endpoint, data):
    """Helper function to make API calls"""
    url = f"{BASE_URL}/{endpoint}"
    response = requests.post(url, json=data)
    print(f"Request to {endpoint}: HTTP {response.status_code}")

    if response.text:
        try:
            json_response = response.json()
            print(f"Response: {json_response}")
            return response.status_code, json_response
        except requests.exceptions.JSONDecodeError:
            print(f"Response: {response.text}")
            return response.status_code, {"error": "Not JSON", "message": response.text}
    else:
        print("Response: Empty")
        return response.status_code, None

def wait_for_job_completion(job_id, status_endpoint, max_wait_time=60):
    """Wait for an async job to complete"""
    start_time = time.time()

    while True:
        status_data = {"user_api_key": API_KEY, "job_id": job_id}
        status, status_response = make_request(status_endpoint, status_data)

        if status_response and status_response.get("status") == "finished":
            return True
        elif status_response and status_response.get("status") == "failed":
            return False

        if time.time() - start_time > max_wait_time:
            return False

        time.sleep(2)

def generate_dataset(num_samples, vector_dim, id_prefix, seed=2025):
    """Generate dataset with linear decision boundary"""
    np.random.seed(seed)
    vectors = np.random.randn(num_samples, vector_dim).tolist()
    categories = [np.random.choice(['A', 'B', 'C']) for _ in range(num_samples)]

    labels = []
    for vec, category in zip(vectors, categories):
        # Linear combination of first few components plus category weight
        score = sum(vec[:20]) + {'A': 1.0, 'B': -0.5, 'C': 0.0}[category]
        label = '1' if score > 0 else '0'
        labels.append(label)

    # Generate IDs and attributes
    ids = [f"{id_prefix}_{i:03d}" for i in range(num_samples)]
    attributes = [{"label": str(label), "category": category} for label, category in zip(labels, categories)]

    return vectors, ids, attributes

# Clean up any existing project
status, response = make_request("delete_project", {"user_api_key": API_KEY, "project_name": "AutoML-Demo"})

# 1. Create a project
project_data = {"user_api_key": API_KEY, "project_name": "AutoML-Demo", "application": "Machine Learning"}
status, response = make_request("create_project", project_data)

# 2. Initialize training dataset
init_data = {"user_api_key": API_KEY, "project_name": "AutoML-Demo", "collection_name": "training_data",
             "vector_type": "dense", "vector_dim": 64}
status, response = make_request("init", init_data)

# 3. Generate and add training data using add_data_batch
vectors, ids, attributes = generate_dataset(num_samples=1000, vector_dim=64, id_prefix="train", seed=2025)

# Add training data in batch
batch_data = {"user_api_key": API_KEY, "project_name": "AutoML-Demo", "collection_name": "training_data",
              "string_ids": ids, "data": vectors, "attributes": attributes}
status, response = make_request("add_data_batch", batch_data)
train_upload_job_id = response["job_id"]

# Wait for training data upload to complete
if not wait_for_job_completion(train_upload_job_id, "get_upload_data_status", max_wait_time=30):
    exit(1)

# 4. Train AutoML model
train_data = {"user_api_key": API_KEY, "project_name": "AutoML-Demo", "collection_name": "training_data",
              "model_name": "model1", "training_mode": "high_speed", "task_type": "classification",
              "label_attribute": "label", "categorical_features": ["category"]}
status, response = make_request("train_automl_model", train_data)
train_job_id = response["job_id"]

# Wait for training to complete
if not wait_for_job_completion(train_job_id, "get_automl_training_status", max_wait_time=60):
    exit(1)

# 5. Initialize prediction dataset
pred_init_data = {"user_api_key": API_KEY, "project_name": "AutoML-Demo", "collection_name": "prediction_data",
                  "vector_type": "dense", "vector_dim": 64}
status, response = make_request("init", pred_init_data)

# 6. Generate and add prediction data
prediction_vectors, prediction_ids, prediction_attributes = generate_dataset(num_samples=100, vector_dim=64, id_prefix="pred", seed=2026)

# Add prediction data in batch
pred_batch_data = {"user_api_key": API_KEY, "project_name": "AutoML-Demo", "collection_name": "prediction_data",
                   "string_ids": prediction_ids, "data": prediction_vectors, "attributes": prediction_attributes}
status, response = make_request("add_data_batch", pred_batch_data)
pred_upload_job_id = response["job_id"]

# Wait for prediction data upload to complete
if not wait_for_job_completion(pred_upload_job_id, "get_upload_data_status"):
    exit(1)

# 7. Make predictions using the existing dataset
predict_data = {"user_api_key": API_KEY, "project_name": "AutoML-Demo", "collection_name": "training_data",
                "model_name": "model1", "prediction_dataset": "prediction_data"}
status, prediction_results = make_request("automl_predict", predict_data)

---

AutoML API Endpoints

/train_automl_model

Description: Initiates training of an AutoML model on a specified dataset. This is an asynchronous operation that returns a job ID for tracking progress.

Method - POST

Request Body

{
  "user_api_key": "string",
  "project_name": "string",
  "collection_name": "string", 
  "model_name": "string",
  "training_mode": "string",
  "task_type": "string",
  "label_attribute": "string",
  "categorical_features": ["string", ...],  // optional
  "validation_dataset": "string"            // optional
}

Request Fields

• model_name: Unique name for the model (max 128 characters, no special characters).
• training_mode: Training mode configuration: "high_speed", "balanced", "high_accuracy".
• task_type: Type of ML task - either "classification" or "regression".
• label_attribute: Name of the attribute/column to use as the target label.
• categorical_features: (Optional) Array of attribute names to treat as categorical features.
• validation_dataset: (Optional) Name of separate dataset to use for validation. If not set, default cross-validation will be used. If validation_dataset is provided, it must have the same vector dimensions as the training dataset.

Response Success Response (200 OK):

{
  "success": true,
  "job_id": "string"
}

Notes

• Model names must be unique within a dataset.
• Training is asynchronous - use /get_automl_training_status with the returned job_id to monitor progress.
• The training dataset must contain the specified label_attribute. Data samples without label will not be included in the final training set to train the model.

Example

POST /train_automl_model
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "project_name": "MLProject",
  "collection_name": "customer_data",
  "model_name": "customer_segmentation_v1",
  "training_mode": "auto",
  "task_type": "classification", 
  "label_attribute": "customer_segment",
  "categorical_features": ["region", "subscription_type"],
  "validation_dataset": "customer_validation_data"
}

Response:

{
  "success": true,
  "job_id": "user123_MLProject_customer_data_customer_segmentation_v1_TrainJob"
}

---

/automl_predict

Description: Use a trained AutoML model to make predictions on new data. Can accept data as a file upload or reference an existing dataset.

Method - POST

Request Body

Option 1: Using file upload

{
  "user_api_key": "string",
  "project_name": "string", 
  "collection_name": "string",
  "model_name": "string",
  "file_data": "string",          // base64 encoded file
  "file_format": "string",        // "csv", "json", or "libsvm"
  "has_field_names": boolean,     // required for CSV files
  "compression_type": "string"    // optional: "gzip"
}

Option 2: Using existing dataset

{
  "user_api_key": "string",
  "project_name": "string",
  "collection_name": "string", 
  "model_name": "string",
  "prediction_dataset": "string"
}

Request Fields

• collection_name: Name of the dataset the model was trained on
• model_name: Name of the trained model to use for prediction
• file_data: (Option 1) Base64 encoded file containing prediction data
• file_format: (Option 1) Format of uploaded file: "csv", "json", or "libsvm"
• has_field_names: (Option 1, CSV only) Whether the CSV file contains column headers
• compression_type: (Option 1, optional) Set to "gzip" if file is gzip compressed
• prediction_dataset: (Option 2) Name of existing dataset to make predictions on

Response For Classification Models:

{
  "success": true,
  "num_samples": 1000,
  "predictions": [0.0, 1.0, 2.0, ...],
  "prediction_metric": {
    "accuracy": 0.85,
    "micro_precision": 0.86, 
    "macro_precision": 0.84,
    "micro_recall": 0.85,
    "macro_recall": 0.83,
    "micro_f1": 0.855,
    "macro_f1": 0.835,
    "auc": 0.92
  }
}

For Regression Models:

{
  "success": true,
  "num_samples": 1000,
  "predictions": [12.5, 8.3, 15.7, ...],
  "prediction_metric": 0.045  // MSE value
}

Error Response:

{
  "success": false,
  "error_message": "Error description"
}

Response Fields

• num_samples: Number of samples that have a label and are used to compute the prediction matrics
• predictions: Array of prediction values (class labels for classification, numeric values for regression)
• prediction_metric: Performance metrics if true labels are available in the data
  • For classification: detailed metrics object
  • For regression: single MSE (Mean Squared Error) value

Notes

• The prediction data must have the same vector dimensions and format as the training data
• If using categorical features, all categorical attributes must be present in the prediction data
• When uploading files, supported formats are CSV, JSON, and LibSVM
• Prediction metrics are only calculated if the true labels are present in the prediction data
• Temporary datasets created from file uploads are automatically cleaned up after prediction

Example

POST /automl_predict
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "project_name": "MLProject",
  "collection_name": "customer_data", 
  "model_name": "customer_segmentation_v1",
  "prediction_dataset": "new_customers"
}

Response:

{
  "success": true,
  "num_samples": 393,
  "predictions": [0, 1, 2, 1, 0, 2, 1, 0, ...],
  "prediction_metric": {
    "accuracy": 0.89,
    "micro_precision": 0.91,
    "macro_precision": 0.88,
    "micro_recall": 0.89,
    "macro_recall": 0.87,
    "micro_f1": 0.90,
    "macro_f1": 0.875,
    "auc": 0.94
  }
}

---

/delete_automl_model

Description: Deletes a specific AutoML model from a dataset. This action cannot be undone.

Method - POST

Request Body

{
  "user_api_key": "string",
  "project_name": "string", 
  "collection_name": "string",
  "model_name": "string"
}

Response Success Response (200 OK):

{
  "success": true
}

Example

POST /delete_automl_model
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "project_name": "ProjectA",
  "collection_name": "MyDataset",
  "model_name": "old_classification_model"
}

Response:

{
  "success": true
}

---

/get_automl_training_status

Description: Retrieves the current status and progress of an AutoML training job.

Method - POST

Request Body

{
  "user_api_key": "string",
  "job_id": "string"
}

Response For In-Progress Jobs:

{
  "success": true,
  "task_type": "classification",
  "model_name": "model_123",
  "label_attribute": "category",
  "status": "in_progress",
  "start_time": "2025/01/15 14:30:25",
  "duration": "00:05:30"
}

For Completed Jobs:

{
  "success": true,
  "task_type": "classification",
  "model_name": "model_123", 
  "label_attribute": "category",
  "status": "finished",
  "start_time": "2025/01/15 14:30:25",
  "duration": "00:12:45",
  "validation_metric": {
    "accuracy": 0.85,
    "micro_precision": 0.86,
    "macro_precision": 0.84,
    "micro_recall": 0.85,
    "macro_recall": 0.83,
    "micro_f1": 0.855,
    "macro_f1": 0.835,
    "auc": 0.92
  }
}

For Failed Jobs:

{
  "success": true,
  "task_type": "regression",
  "model_name": "model_456",
  "label_attribute": "price", 
  "status": "failed",
  "start_time": "2025/01/15 15:00:10",
  "duration": "00:02:15",
  "error": "Training failed"
}

Notes

• Status values: "pending", "in_progress", "finished", "failed"

• For classification tasks, validation_metric contains detailed metrics

• For regression tasks, validation_metric contains a single MSE float value

• Duration is formatted as "HH:MM:SS"

Example

POST /get_automl_training_status
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "job_id": "training_job_789"
}

Response:

{
  "success": true,
  "task_type": "classification",
  "model_name": "customer_segment_model",
  "label_attribute": "segment",
  "status": "finished", 
  "start_time": "2025/01/15 14:30:25",
  "duration": "00:08:42",
  "validation_metric": {
    "accuracy": 0.91,
    "micro_precision": 0.92,
    "macro_precision": 0.90,
    "micro_recall": 0.91,
    "macro_recall": 0.89,
    "micro_f1": 0.915,
    "macro_f1": 0.895,
    "auc": 0.96
  }
}

---

/get_model_validation_metric

Description: Retrieves validation metrics for a specific trained AutoML model.

Method - POST

Request Body

{
  "user_api_key": "string",
  "project_name": "string",
  "collection_name": "string", 
  "model_name": "string"
}

Response: For Classification Models:

{
  "success": true,
  "validation_metric": {
    "accuracy": 0.85,
    "micro_precision": 0.86,
    "macro_precision": 0.84,
    "micro_recall": 0.85,
    "macro_recall": 0.83,
    "micro_f1": 0.855,
    "macro_f1": 0.835,
    "auc": 0.92
  }
}

For Regression Models:

{
  "success": true,
  "validation_metric": 0.045  // MSE value
}

Example

POST /get_model_validation_metric
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "project_name": "ProjectA", 
  "collection_name": "MyDataset",
  "model_name": "classification_model_1"
}

Response:

{
  "success": true,
  "validation_metric": {
    "accuracy": 0.89,
    "micro_precision": 0.90,
    "macro_precision": 0.88,
    "micro_recall": 0.89,
    "macro_recall": 0.87,
    "micro_f1": 0.895,
    "macro_f1": 0.875,
    "auc": 0.94
  }
}

---

/list_automl_model_infos

Description: Retrieves metadata for all AutoML models within a specific dataset.

Method - POST

Request Body

{
  "user_api_key": "string",
  "project_name": "string",
  "collection_name": "string"
}

Response Success Response (200 OK):

{
  "success": true,
  "model_infos": [
    [
      "model_name",
      "task_type",
      "training_mode", 
      "label_attribute",
      "create_time"
    ],
    ...
  ]
}

Example

POST /list_automl_model_infos
Content-Type: application/json

{
  "user_api_key": "api_key_123",
  "project_name": "ProjectA",
  "collection_name": "MyDataset"
}

Response:

{
  "success": true,
  "model_infos": [
    [
      "classification_model_1",
      "classification",
      "high_speed",
      "category",
      "2025/01/15, 14:30"
    ],
    [
      "regression_model_1", 
      "regression",
      "balanced",
      "price",
      "2025/01/16, 09:15"
    ]
  ]
}

---