Runs

Runs represent individual monitoring executions for your AI projects. Each run captures performance metrics, validation results, and system health data during a specific time period.

Run Object

interface Run {
  id: string;
  projectId: string;
  name: string;
  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
  startTime?: string;
  endTime?: string;
  metadata?: {
    duration?: number;
    metrics?: Record<string, number>;
    logs?: string[];
    artifacts?: string[];
    environment?: string;
    version?: string;
  };
  createdAt: string;
  updatedAt: string;
}

List Runs

Retrieve runs with filtering and pagination options.

GET /api/runs?page=1&limit=10&status=completed&projectId=proj_123
Cookie: session-token=your_session_token

Query Parameters:

page (optional): Page number (default: 1)
limit (optional): Items per page (default: 10, max: 100)
status (optional): Filter by run status
projectId (optional): Filter by specific project
startDate (optional): Filter runs after this date (ISO 8601)
endDate (optional): Filter runs before this date (ISO 8601)

{
  "success": true,
  "data": [
    {
      "id": "run_456",
      "projectId": "proj_123",
      "name": "Daily Model Validation",
      "status": "completed",
      "startTime": "2024-01-15T14:00:00Z",
      "endTime": "2024-01-15T14:25:00Z",
      "metadata": {
        "duration": 1500,
        "metrics": {
          "accuracy": 0.987,
          "precision": 0.982,
          "recall": 0.991,
          "f1_score": 0.986,
          "latency_p95": 45,
          "throughput": 1200
        },
        "environment": "production",
        "version": "1.2.0",
        "artifacts": [
          "model_validation_report.pdf",
          "performance_metrics.json"
        ]
      },
      "createdAt": "2024-01-15T14:00:00Z",
      "updatedAt": "2024-01-15T14:25:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 156,
    "totalPages": 16
  }
}

curl -X GET "https://api.cortif.ai/api/runs?status=completed&projectId=proj_123" \
  -H "Cookie: session-token=your_session_token"

Create Run

Start a new monitoring run for a project.

POST /api/runs
Content-Type: application/json
Cookie: session-token=your_session_token

{
  "projectId": "proj_123",
  "name": "Weekly Performance Check",
  "metadata": {
    "environment": "staging",
    "version": "1.3.0-beta",
    "config": {
      "batch_size": 32,
      "timeout": 300,
      "validation_split": 0.2
    }
  }
}

Required Fields:

projectId: Associated project ID
name: Run name (string, 1-200 characters)

Optional Fields:

metadata: Additional run configuration and context

{
  "success": true,
  "data": {
    "id": "run_789",
    "projectId": "proj_123",
    "name": "Weekly Performance Check",
    "status": "pending",
    "startTime": null,
    "endTime": null,
    "metadata": {
      "environment": "staging",
      "version": "1.3.0-beta",
      "config": {
        "batch_size": 32,
        "timeout": 300,
        "validation_split": 0.2
      }
    },
    "createdAt": "2024-01-15T16:00:00Z",
    "updatedAt": "2024-01-15T16:00:00Z"
  }
}

curl -X POST https://api.cortif.ai/api/runs \
  -H "Content-Type: application/json" \
  -H "Cookie: session-token=your_session_token" \
  -d '{
    "projectId": "proj_123",
    "name": "Weekly Performance Check",
    "metadata": {
      "environment": "staging",
      "version": "1.3.0-beta"
    }
  }'

Get Run

Retrieve a specific run by ID with detailed information.

GET /api/runs/run_456
Cookie: session-token=your_session_token

{
  "success": true,
  "data": {
    "id": "run_456",
    "projectId": "proj_123",
    "name": "Daily Model Validation",
    "status": "completed",
    "startTime": "2024-01-15T14:00:00Z",
    "endTime": "2024-01-15T14:25:00Z",
    "metadata": {
      "duration": 1500,
      "metrics": {
        "accuracy": 0.987,
        "precision": 0.982,
        "recall": 0.991,
        "f1_score": 0.986,
        "latency_p95": 45,
        "throughput": 1200,
        "error_rate": 0.003
      },
      "logs": [
        "2024-01-15T14:00:00Z - Starting validation pipeline",
        "2024-01-15T14:05:00Z - Loading test dataset (10,000 samples)",
        "2024-01-15T14:10:00Z - Running model inference",
        "2024-01-15T14:20:00Z - Computing metrics",
        "2024-01-15T14:25:00Z - Validation completed successfully"
      ],
      "environment": "production",
      "version": "1.2.0",
      "artifacts": [
        "model_validation_report.pdf",
        "performance_metrics.json",
        "confusion_matrix.png"
      ]
    },
    "createdAt": "2024-01-15T14:00:00Z",
    "updatedAt": "2024-01-15T14:25:00Z"
  }
}

curl -X GET https://api.cortif.ai/api/runs/run_456 \
  -H "Cookie: session-token=your_session_token"

Update Run

Update run status and add metrics or logs during execution.

PATCH /api/runs/run_789
Content-Type: application/json
Cookie: session-token=your_session_token

{
  "status": "running",
  "startTime": "2024-01-15T16:05:00Z",
  "metadata": {
    "metrics": {
      "progress": 0.45,
      "samples_processed": 4500
    },
    "logs": [
      "2024-01-15T16:05:00Z - Starting model validation",
      "2024-01-15T16:07:00Z - Processing batch 1/10"
    ]
  }
}

Status Transitions:

pending → running, cancelled
running → completed, failed, cancelled
completed/failed/cancelled → No further transitions

{
  "success": true,
  "data": {
    "id": "run_789",
    "projectId": "proj_123",
    "name": "Weekly Performance Check",
    "status": "running",
    "startTime": "2024-01-15T16:05:00Z",
    "endTime": null,
    "metadata": {
      "environment": "staging",
      "version": "1.3.0-beta",
      "metrics": {
        "progress": 0.45,
        "samples_processed": 4500
      },
      "logs": [
        "2024-01-15T16:05:00Z - Starting model validation",
        "2024-01-15T16:07:00Z - Processing batch 1/10"
      ]
    },
    "createdAt": "2024-01-15T16:00:00Z",
    "updatedAt": "2024-01-15T16:07:00Z"
  }
}

curl -X PATCH https://api.cortif.ai/api/runs/run_789 \
  -H "Content-Type: application/json" \
  -H "Cookie: session-token=your_session_token" \
  -d '{
    "status": "running",
    "startTime": "2024-01-15T16:05:00Z",
    "metadata": {
      "metrics": {
        "progress": 0.45
      }
    }
  }'

Complete Run

Mark a run as completed with final metrics and results.

POST /api/runs/run_789/complete
Content-Type: application/json
Cookie: session-token=your_session_token

{
  "endTime": "2024-01-15T16:30:00Z",
  "metadata": {
    "duration": 1500,
    "metrics": {
      "accuracy": 0.991,
      "precision": 0.988,
      "recall": 0.994,
      "f1_score": 0.991,
      "latency_p95": 42,
      "throughput": 1350,
      "error_rate": 0.002
    },
    "artifacts": [
      "validation_report_v1.3.0-beta.pdf",
      "metrics_summary.json"
    ],
    "summary": "Model performance improved across all metrics"
  }
}

{
  "success": true,
  "data": {
    "id": "run_789",
    "projectId": "proj_123",
    "name": "Weekly Performance Check",
    "status": "completed",
    "startTime": "2024-01-15T16:05:00Z",
    "endTime": "2024-01-15T16:30:00Z",
    "metadata": {
      "duration": 1500,
      "environment": "staging",
      "version": "1.3.0-beta",
      "metrics": {
        "accuracy": 0.991,
        "precision": 0.988,
        "recall": 0.994,
        "f1_score": 0.991,
        "latency_p95": 42,
        "throughput": 1350,
        "error_rate": 0.002
      },
      "artifacts": [
        "validation_report_v1.3.0-beta.pdf",
        "metrics_summary.json"
      ],
      "summary": "Model performance improved across all metrics"
    },
    "createdAt": "2024-01-15T16:00:00Z",
    "updatedAt": "2024-01-15T16:30:00Z"
  }
}

curl -X POST https://api.cortif.ai/api/runs/run_789/complete \
  -H "Content-Type: application/json" \
  -H "Cookie: session-token=your_session_token" \
  -d '{
    "endTime": "2024-01-15T16:30:00Z",
    "metadata": {
      "metrics": {
        "accuracy": 0.991,
        "precision": 0.988
      }
    }
  }'

Cancel Run

Cancel a pending or running execution.

POST /api/runs/run_789/cancel
Content-Type: application/json
Cookie: session-token=your_session_token

{
  "reason": "Resource constraints - rescheduling for later"
}

{
  "success": true,
  "data": {
    "id": "run_789",
    "status": "cancelled",
    "cancelledAt": "2024-01-15T16:15:00Z",
    "reason": "Resource constraints - rescheduling for later"
  }
}

curl -X POST https://api.cortif.ai/api/runs/run_789/cancel \
  -H "Content-Type: application/json" \
  -H "Cookie: session-token=your_session_token" \
  -d '{
    "reason": "Resource constraints"
  }'

Run Analytics

Get analytics and trends for runs across projects.

GET /api/runs/analytics?projectId=proj_123&period=30d&groupBy=status
Cookie: session-token=your_session_token

Query Parameters:

projectId (optional): Filter by project
period: Time period (1d, 7d, 30d, 90d)
groupBy: Group results by (status, environment, version)

{
  "success": true,
  "data": {
    "period": "30d",
    "totalRuns": 124,
    "breakdown": {
      "completed": 118,
      "failed": 4,
      "cancelled": 2
    },
    "metrics": {
      "averageDuration": 1245,
      "successRate": 0.952,
      "averageAccuracy": 0.987,
      "averageLatency": 43.2
    },
    "trends": [
      {
        "date": "2024-01-15",
        "runs": 4,
        "avgAccuracy": 0.989,
        "avgLatency": 41.5,
        "successRate": 1.0
      }
    ]
  }
}

curl -X GET "https://api.cortif.ai/api/runs/analytics?period=30d&projectId=proj_123" \
  -H "Cookie: session-token=your_session_token"

Run Comparison

Compare metrics between multiple runs.

POST /api/runs/compare
Content-Type: application/json
Cookie: session-token=your_session_token

{
  "runIds": ["run_456", "run_789", "run_101"],
  "metrics": ["accuracy", "precision", "recall", "latency_p95"]
}

{
  "success": true,
  "data": {
    "comparison": [
      {
        "runId": "run_456",
        "name": "Daily Model Validation",
        "version": "1.2.0",
        "metrics": {
          "accuracy": 0.987,
          "precision": 0.982,
          "recall": 0.991,
          "latency_p95": 45
        }
      },
      {
        "runId": "run_789",
        "name": "Weekly Performance Check",
        "version": "1.3.0-beta",
        "metrics": {
          "accuracy": 0.991,
          "precision": 0.988,
          "recall": 0.994,
          "latency_p95": 42
        }
      }
    ],
    "summary": {
      "bestAccuracy": {
        "runId": "run_789",
        "value": 0.991
      },
      "bestLatency": {
        "runId": "run_789",
        "value": 42
      }
    }
  }
}

Error Handling

Common error responses for run operations:

Status Code	Error	Description
`400`	`INVALID_INPUT`	Invalid request data
`401`	`UNAUTHORIZED`	Authentication required
`403`	`FORBIDDEN`	Insufficient permissions
`404`	`RUN_NOT_FOUND`	Run doesn't exist
`409`	`INVALID_STATUS_TRANSITION`	Cannot change to requested status
`422`	`VALIDATION_ERROR`	Input validation failed

SDK Examples

JavaScript/TypeScript

import { CortifClient } from '@cortif/sdk';

const client = new CortifClient();

// Create and start a run
const run = await client.runs.create({
  projectId: 'proj_123',
  name: 'Model Validation Run',
  metadata: {
    environment: 'production',
    version: '2.0.0'
  }
});

// Update run with progress
await client.runs.update(run.id, {
  status: 'running',
  startTime: new Date().toISOString(),
  metadata: {
    metrics: { progress: 0.5 },
    logs: ['Processing batch 5/10']
  }
});

// Complete the run
await client.runs.complete(run.id, {
  endTime: new Date().toISOString(),
  metadata: {
    metrics: {
      accuracy: 0.995,
      latency_p95: 38
    },
    summary: 'Validation completed successfully'
  }
});

// Get run analytics
const analytics = await client.runs.getAnalytics({
  projectId: 'proj_123',
  period: '7d'
});

Python

from cortif import CortifClient
from datetime import datetime

client = CortifClient()

# Create and start a run
run = client.runs.create({
    'project_id': 'proj_123',
    'name': 'Model Validation Run',
    'metadata': {
        'environment': 'production',
        'version': '2.0.0'
    }
})

# Update run with progress
client.runs.update(run['id'], {
    'status': 'running',
    'start_time': datetime.utcnow().isoformat(),
    'metadata': {
        'metrics': {'progress': 0.5},
        'logs': ['Processing batch 5/10']
    }
})

# Complete the run
client.runs.complete(run['id'], {
    'end_time': datetime.utcnow().isoformat(),
    'metadata': {
        'metrics': {
            'accuracy': 0.995,
            'latency_p95': 38
        }
    }
})

Best Practices

Run Management Tips

Descriptive Names: Use clear, descriptive names that include context
Structured Metadata: Organize metrics and logs consistently
Progress Updates: Provide regular status updates for long-running operations
Error Handling: Properly handle and log failures
Resource Cleanup: Cancel runs that are no longer needed
Artifact Management: Store important outputs and reports

Automated Runs

Scheduled Runs

Configure automated runs using cron expressions:

{
  "schedule": "0 2 * * *",
  "timezone": "UTC",
  "enabled": true,
  "template": {
    "name": "Daily Validation - {{date}}",
    "metadata": {
      "environment": "production",
      "automated": true
    }
  }
}

Triggered Runs

Set up event-triggered runs:

{
  "triggers": [
    {
      "type": "model_deployment",
      "conditions": {
        "environment": "production"
      }
    },
    {
      "type": "data_drift_detected",
      "conditions": {
        "threshold": 0.1
      }
    }
  ]
}

Next Steps

Configure alerts based on run results
Generate evidence packs from run data
Set up integrations for automated runs
Manage team access to run results

Runs

On this page