List Custom Models

Retrieve a paginated list of all custom models in your organization.

Endpoint

GET /api/v3/custom_models

Authentication

Requires API key with custom_models:read scope.

Authorization: Bearer YOUR_API_KEY

Request

Headers

Header	Value	Required
Authorization	Bearer YOUR_API_KEY	Yes

Query Parameters

Parameter	Type	Required	Default	Description
page	integer	No	1	Page number (1-indexed)
per_page	integer	No	25	Items per page (max: 100)
status	integer	No	-	Filter by training_status (1-5)
language	string	No	-	Filter by language code (e.g., "en")
base_model	string	No	-	Filter by base model type

Example Request

GET /api/v3/custom_models?page=1&per_page=25&status=4&language=en

Response

Success Response

Status Code: 200 OK

{
  "count": 25,
  "total_results": 150,
  "result": [
    {
      "id": 123,
      "model_key": "custom_model_123",
      "name": "Medical Cardiology EN",
      "description": "Cardiology consultations and reports",
      "language": "en",
      "base_model": "medical",
      "training_status": 4,
      "status_message": "Training completed successfully",
      "training_progress": 100,
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-16T15:30:00Z",
      "started_training_at": "2025-01-16T08:00:00Z",
      "finished_training_at": "2025-01-16T15:30:00Z",
      "training_metrics": {
        "word_error_rate": 12.5,
        "accuracy_improvement": 18.7
      }
    },
    {
      "id": 124,
      "model_key": "custom_model_124",
      "name": "Legal Contracts NL",
      "description": null,
      "language": "nl",
      "base_model": "legal",
      "training_status": 3,
      "status_message": "Training in progress...",
      "training_progress": 65,
      "created_at": "2025-01-17T09:00:00Z",
      "updated_at": "2025-01-17T11:30:00Z",
      "started_training_at": "2025-01-17T10:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
count	integer	Number of items in current page
total_results	integer	Total items across all pages
result	array	Array of model objects

See Data Models for complete model object schema.

Examples

cURL

# List all models
curl https://api.scriptix.io/api/v3/custom_models \
  -H "Authorization: Bearer YOUR_API_KEY"

# List only completed models
curl "https://api.scriptix.io/api/v3/custom_models?status=4" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Pagination
curl "https://api.scriptix.io/api/v3/custom_models?page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

url = "https://api.scriptix.io/api/v3/custom_models"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# List all models with pagination
page = 1
all_models = []

while True:
    response = requests.get(
        url,
        headers=headers,
        params={"page": page, "per_page": 100}
    )
    data = response.json()

    all_models.extend(data['result'])

    # Check if more pages exist
    if len(data['result']) < 100:
        break
    page += 1

print(f"Total models: {len(all_models)}")

# Filter completed models
completed = [m for m in all_models if m['training_status'] == 4]
print(f"Completed models: {len(completed)}")

JavaScript

const axios = require('axios');

const listModels = async (filters = {}) => {
  const response = await axios.get(
    'https://api.scriptix.io/api/v3/custom_models',
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
      params: {
        page: filters.page || 1,
        per_page: filters.per_page || 25,
        status: filters.status,
        language: filters.language
      }
    }
  );

  return response.data;
};

// List all English medical models
listModels({ language: 'en', base_model: 'medical' })
  .then(data => {
    console.log(`Found ${data.total_results} models`);
    data.result.forEach(model => {
      console.log(`${model.name} - Status: ${model.status_message}`);
    });
  });

Filtering Examples

Filter by Training Status

# Not running (created, no data)
GET /api/v3/custom_models?status=1

# Ready to run (data uploaded)
GET /api/v3/custom_models?status=2

# Training in progress
GET /api/v3/custom_models?status=3

# Completed successfully
GET /api/v3/custom_models?status=4

# Failed
GET /api/v3/custom_models?status=5

Filter by Language

GET /api/v3/custom_models?language=en
GET /api/v3/custom_models?language=nl
GET /api/v3/custom_models?language=de

Filter by Base Model

GET /api/v3/custom_models?base_model=medical
GET /api/v3/custom_models?base_model=legal
GET /api/v3/custom_models?base_model=technical

Combined Filters

GET /api/v3/custom_models?language=en&base_model=medical&status=4

Pagination

Navigating Pages

# Get first page
response = requests.get(url, params={"page": 1, "per_page": 25})
data = response.json()

total_pages = (data['total_results'] + 24) // 25  # Round up
current_page = 1

print(f"Page {current_page} of {total_pages}")
print(f"Showing {data['count']} of {data['total_results']} total")

Best Practices

• Use maximum per_page=100 for batch operations
• Use smaller per_page for UI pagination
• Cache results when possible
• Consider filtering instead of fetching all pages

Error Responses

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

400 Bad Request

{
  "error": "Bad Request",
  "message": "Invalid query parameters",
  "details": {
    "per_page": "Maximum value is 100",
    "status": "Must be between 1 and 5"
  }
}

Rate Limits

• Requests: 100 requests/minute
• Concurrent: 10 concurrent requests

Related Endpoints

• Create Model - Create new model
• Get Model - Get model details
• Update Model - Update model
• Delete Model - Delete model

---

See Data Models for complete schema reference.