Trial Schema

This document describes the Trial object schema returned by the globalMOO API.

Structure

{
  "id": 789,                                     // Unique identifier
  "created_at": "2025-01-31T11:00:00.000Z",      // Creation timestamp
  "updated_at": "2025-01-31T11:15:00.000Z",      // Last update timestamp
  "disabled_at": null,                           // Optional disable timestamp
  "project_id": 456,                             // Parent project ID
  "status": "completed",                         // Trial status
  "start_time": "2025-01-31T11:00:10.000Z",      // Execution start time
  "end_time": "2025-01-31T11:14:55.000Z",        // Execution end time
  "duration": 885,                               // Duration in seconds
  "iteration_count": 257,                        // Number of iterations executed
  "stop_reason": "convergence",                  // Reason for stopping
  "configuration": {                             // Trial-specific configuration
    "seed": 12345,
    "parameters": {
      "max_iterations": 1000,
      "convergence_threshold": 0.001
    }
  },
  "metrics": {                                   // Trial performance metrics
    "convergence_rate": 0.0034,
    "final_loss": 0.00089
  },
  "results": [                                   // Objective results
    {
      "objective_id": 321,
      "name": "Maximize Revenue",
      "value": 1520000,
      "unit": "USD",
      "improvement": 12.5
    }
  ],
  "checkpoints": [                               // Trial checkpoints
    {
      "iteration": 100,
      "timestamp": "2025-01-31T11:05:25.000Z",
      "metrics": {
        "loss": 0.0245
      }
    },
    {
      "iteration": 200,
      "timestamp": "2025-01-31T11:10:40.000Z",
      "metrics": {
        "loss": 0.0028
      }
    }
  ]
}

Fields

Field	Type	Description
id	integer	Unique identifier for the trial
created_at	string (ISO 8601)	Timestamp when the trial was created
updated_at	string (ISO 8601)	Timestamp when the trial was last updated
disabled_at	string (ISO 8601) or null	Timestamp when the trial was disabled, null if active
project_id	integer	ID of the parent project
status	string	Current status of the trial (pending, running, completed, failed)
start_time	string (ISO 8601)	Timestamp when trial execution started
end_time	string (ISO 8601) or null	Timestamp when trial execution ended, null if not completed
duration	number	Duration of the trial in seconds
iteration_count	integer	Number of iterations completed
stop_reason	string	Reason for trial stopping (convergence, max_iterations, error, manual)
configuration	object	Trial-specific configuration parameters
metrics	object	Performance metrics for the trial
results	array of Result objects	Results for each objective
checkpoints	array	List of checkpoint data during trial execution

Status Values

Status	Description
pending	Trial has been created but execution has not started
running	Trial is currently executing
completed	Trial has completed successfully
failed	Trial failed to complete due to an error
cancelled	Trial was manually cancelled

Stop Reason Values

Stop Reason	Description
convergence	Trial stopped due to convergence (reached threshold)
max_iterations	Trial stopped after reaching maximum number of iterations
error	Trial stopped due to an error
manual	Trial was manually stopped by a user
timeout	Trial stopped due to reaching maximum allowed execution time

Examples

Running Trial

{
  "id": 789,
  "created_at": "2025-01-31T11:00:00.000Z",
  "updated_at": "2025-01-31T11:05:00.000Z",
  "disabled_at": null,
  "project_id": 456,
  "status": "running",
  "start_time": "2025-01-31T11:00:10.000Z",
  "end_time": null,
  "duration": 290,
  "iteration_count": 85,
  "stop_reason": null,
  "configuration": {
    "seed": 12345,
    "parameters": {
      "max_iterations": 1000,
      "convergence_threshold": 0.001
    }
  },
  "metrics": {
    "current_loss": 0.0124
  },
  "results": [],
  "checkpoints": [
    {
      "iteration": 50,
      "timestamp": "2025-01-31T11:03:45.000Z",
      "metrics": {
        "loss": 0.0325
      }
    }
  ]
}

Completed Trial

{
  "id": 790,
  "created_at": "2025-01-30T09:00:00.000Z",
  "updated_at": "2025-01-30T09:30:00.000Z",
  "disabled_at": null,
  "project_id": 456,
  "status": "completed",
  "start_time": "2025-01-30T09:00:15.000Z",
  "end_time": "2025-01-30T09:29:45.000Z",
  "duration": 1770,
  "iteration_count": 524,
  "stop_reason": "convergence",
  "configuration": {
    "seed": 98765,
    "parameters": {
      "max_iterations": 1000,
      "convergence_threshold": 0.001,
      "algorithm": "genetic",
      "population_size": 100
    }
  },
  "metrics": {
    "convergence_rate": 0.0021,
    "final_loss": 0.00076
  },
  "results": [
    {
      "objective_id": 321,
      "name": "Maximize Revenue",
      "value": 1645000,
      "unit": "USD",
      "improvement": 15.2
    },
    {
      "objective_id": 322,
      "name": "Minimize Costs",
      "value": 820000,
      "unit": "USD",
      "improvement": 8.7
    }
  ],
  "checkpoints": [
    {
      "iteration": 100,
      "timestamp": "2025-01-30T09:06:20.000Z",
      "metrics": {
        "loss": 0.0215
      }
    },
    {
      "iteration": 250,
      "timestamp": "2025-01-30T09:15:45.000Z",
      "metrics": {
        "loss": 0.0083
      }
    },
    {
      "iteration": 500,
      "timestamp": "2025-01-30T09:28:10.000Z",
      "metrics": {
        "loss": 0.0009
      }
    }
  ]
}

Related Endpoints

• Trial Endpoints
• Read Trial