Skip to content

Predict

Generate accurate predictions from structured data using a custom Predictor ML model trained on your data.

Perfect for making yes/no decisions, classifying into categories (based on attributes), predicting numbers, making recommendations, or forecasting outcomes based on historical patterns in your data.

Example Use Cases
  • Forecast monthly sales for each product
  • Predict customer lifetime value based on early interactions
  • Estimate how long a project will take based on task characteristics
  • Predict optimal pricing based on market conditions
  • Predict if a customer is likely to churn based on their activity patterns
  • Determine if a transaction is potentially fraudulent
  • Forecast subscription renewal based on engagement metrics
  • Predict equipment failure based on performance metrics
  • Categorize financial transactions based on attributes
  • Classify customer segments based on behavioral metrics
  • Determine product quality grades from manufacturing parameters
  • Categorize risk levels based on financial indicators
  • Recommend products based on user history
  • Recommend personalized content based on user behavior
  • Recommend new features for a user to try
  • Recommend optimal subscription tiers based on usage metrics
  • Predict the most effective marketing channel for each customer segment
  • Determine optimal inventory levels based on seasonal patterns
  • Suggest the best shipping method based on order details
  • Forecast resource allocation needs based on project attributes
Categorize vs. Classify vs. Predict

See this page for details on selecting the right endpoint for your classification task.

Endpoint

POST /v20241104/predict

API Request

  • Required Parameters

    input object

    JSON object specifying structured data for which to predict a label.

    Info

    • You can find the input parameter format (for a custom ML model you've trained) in your Gainly Dashboard under Settings > Custom Models > Details > API Request.

    • Example: 

      "input": {
    "user_watch_time_mins": 45,
    "completion_rate": 0.85,
    "current_video_id": "video_89271",
    "time_of_day": "evening",
    "day_of_week": "saturday",
    "device_type": "mobile",
    "preferred_duration": "medium",
    "last_interaction": "like"
}

    model_id string required

    ID of your custom ML model to use for prediction.

    Info
    • You can find the model ID in your Gainly Dashboard under Settings > Custom Models.

    MinLength: 1   MaxLength: 128

    Optional Parameters

    max_labels integer

    Maximum number of labels (classifications) to assign.

    Default is 3.

    Min: 1   Max: 10

    version string required

    Version of your custom ML model to use for classification. Default is default.

    Info
    • You can find the version number in your Gainly Dashboard under Settings > Custom Models.

    • You can also mark a version as default in your Gainly Dashboard.

    • Examples: 

      "version": "2"

      "version": "default"

    MinLength: 1   MaxLength: 10

  • POST /v20241104/predict

    curl -X POST "https://api.gainly.ai/v20241104/predict" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY_HERE" \  # (1)!
  -d '{
    "input": {
        "user_watch_time_mins": 45,
        "completion_rate": 0.85,
        "current_video_id": "video_89271",
        "time_of_day": "evening",
        "day_of_week": "saturday",
        "device_type": "mobile",
        "preferred_duration": "medium",
        "last_interaction": "like"
    },
    "model_id": "video_recommender_v2"
  }'
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    # Prompt for AI coding assistants/IDEs (e.g., ChatGPT, Claude, GitHub Copilot, Cursor, Windsurf)

Using the Gainly API:
1. Write code to call the predict operation (see OpenAPI spec: https://api.gainly.ai/v20241104/openapi.json)
2. Implement authentication using the header "X-API-Key" as described in the docs: https://docs.gainly.ai/latest/api-reference/authentication/
3. Implement rate limit handling as described in the docs: https://docs.gainly.ai/latest/api-reference/rate-limits/
4. Implement error handling
5. Handle the response according to the PredictResults schema in the OpenAPI spec

    using System.Net.Http;
using System.Text.Json;
using System.Text;

var client = new HttpClient();

var url = "https://api.gainly.ai/v20241104/predict";

var payload = new {
    input = new {
        user_watch_time_mins = 45,
        completion_rate = 0.85,
        current_video_id = "video_89271",
        time_of_day = "evening",
        day_of_week = "saturday",
        device_type = "mobile",
        preferred_duration = "medium",
        last_interaction = "like"
    },
    model_id = "video_recommender_v2"
};

var content = new StringContent(
    JsonSerializer.Serialize(payload),
    Encoding.UTF8,
    "application/json"
);

client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY_HERE"); // (1)!

var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://api.gainly.ai/v20241104/predict"

    payload := map[string]interface{}{
        "input": map[string]interface{}{
            "user_watch_time_mins": 45,
            "completion_rate": 0.85,
            "current_video_id": "video_89271",
            "time_of_day": "evening",
            "day_of_week": "saturday",
            "device_type": "mobile",
            "preferred_duration": "medium",
            "last_interaction": "like",
        },
        "model_id": "video_recommender_v2",
    }

    jsonData, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "YOUR_API_KEY_HERE") // (1)!

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result)
}
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

var client = HttpClient.newHttpClient();

var url = "https://api.gainly.ai/v20241104/predict";

var payload = """
    {
        "input": {
            "user_watch_time_mins": 45,
            "completion_rate": 0.85,
            "current_video_id": "video_89271",
            "time_of_day": "evening",
            "day_of_week": "saturday",
            "device_type": "mobile",
            "preferred_duration": "medium",
            "last_interaction": "like"
        },
        "model_id": "video_recommender_v2"
    }
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Content-Type", "application/json")
    .header("X-API-Key", "YOUR_API_KEY_HERE") // (1)!
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

var response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    const axios = require('axios');  // or: import axios from 'axios';

const url = 'https://api.gainly.ai/v20241104/predict';

const payload = {
    input: {
        user_watch_time_mins: 45,
        completion_rate: 0.85,
        current_video_id: "video_89271",
        time_of_day: "evening",
        day_of_week: "saturday",
        device_type: "mobile",
        preferred_duration: "medium",
        last_interaction: "like"
    },
    model_id: "video_recommender_v2"
};

const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY_HERE' // (1)!
};

axios.post(url, payload, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error('Error:', error.message));
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    <?php

$client = new \GuzzleHttp\Client();

$url = 'https://api.gainly.ai/v20241104/predict';

$payload = [
    'input' => [
        'user_watch_time_mins' => 45,
        'completion_rate' => 0.85,
        'current_video_id' => 'video_89271',
        'time_of_day' => 'evening',
        'day_of_week' => 'saturday',
        'device_type' => 'mobile',
        'preferred_duration' => 'medium',
        'last_interaction' => 'like'
    ],
    'model_id' => 'video_recommender_v2'
];

$response = $client->request('POST', $url, [
    'json' => $payload,
    'headers' => [
        'Content-Type' => 'application/json',
        'X-API-Key' => 'YOUR_API_KEY_HERE' # (1)!
    ],
]);

echo $response->getBody();
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    import requests

url = "https://api.gainly.ai/v20241104/predict"

payload = {
    "input": {
        "user_watch_time_mins": 45,
        "completion_rate": 0.85,
        "current_video_id": "video_89271",
        "time_of_day": "evening",
        "day_of_week": "saturday",
        "device_type": "mobile",
        "preferred_duration": "medium",
        "last_interaction": "like"
    },
    "model_id": "video_recommender_v2"
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY_HERE" # (1)!
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(data)
    1. Replace YOUR_API_KEY_HERE with the value of your API key.
    require 'json'
require 'uri'
require 'net/http'
require 'openssl'

url = URI('https://api.gainly.ai/v20241104/predict')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request['Content-Type'] = 'application/json'
request['X-API-Key'] = 'YOUR_API_KEY_HERE' # (1)!
request.body = {
    input: {
        user_watch_time_mins: 45,
        completion_rate: 0.85,
        current_video_id: "video_89271",
        time_of_day: "evening",
        day_of_week: "saturday",
        device_type: "mobile",
        preferred_duration: "medium",
        last_interaction: "like"
    },
    model_id: "video_recommender_v2"
}.to_json

response = http.request(request)
puts response.read_body
    1. Replace YOUR_API_KEY_HERE with the value of your API key.

API Response

{
    "object": "predict_result",
    "url": "/v20241104/predict",
    "data": [
      {
        "prediction": {
            "label": "video_92731",
            "confidence_score": 0.42,
            "alternatives": [
                {
                    "label": "video_83156",
                    "confidence_score": 0.38
                },
                {
                    "label": "video_77239",
                    "confidence_score": 0.32
                }
            ]
        }
      }
    ],
    "input": {
        "user_watch_time_mins": 45,
        "completion_rate": 0.85,
        "current_video_id": "video_89271",
        "time_of_day": "evening",
        "day_of_week": "saturday",
        "device_type": "mobile",
        "preferred_duration": "medium",
        "last_interaction": "like"
    },
    "model_id": "video_recommender_v2",
    "version": "default",
    "token_usage": {
        "semantic_tokens": 0,
        "llm_tokens": {
            "llm_output_tokens": 0,
            "llm_input_tokens": 0,
            "model": null
        }
    },
    "livemode": true
}

Label

label indicates the predicted label assigned by the custom model to the input data.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
"data": [
    {
        "prediction": {
            "label": "video_92731",         // The predicted label
            "confidence_score": 0.42,       // Confidence score (0-1)
            "alternatives": [               // Optional: other possible labels
                {
                    "label": "video_83156",
                    "confidence_score": 0.38
                },
                {
                    "label": "video_77239",
                    "confidence_score": 0.32
                }
            ]
        }
    }
],

This example is from a model that was trained to recommend videos to users on a video app based on their watch time, completion rate, current video, time of day, day of week, device type, and preferred duration.