list_jobs
Retrieve recent fine-tuning training jobs on Tuning Engines with status, base model, agent type, GPU usage, and cost. Filter by status or limit results to monitor existing runs or find job IDs.
Instructions
List fine-tuning training jobs on Tuning Engines. Returns recent jobs with status, base model, agent type, GPU usage, and cost. Use this to check on existing training runs or find a job ID.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by status: queued, running, succeeded, failed, canceled | |
| limit | No | Max results (default 20) |
Implementation Reference
- src/mcp.ts:699-704 (handler)The MCP tool handler for 'list_jobs' — calls client.listJobs() with optional status and limit arguments.
case "list_jobs": result = await getClient().listJobs({ status: args?.status as string | undefined, limit: args?.limit as number | undefined, }); break; - src/client.ts:26-37 (handler)The HTTP client method that executes the API request to GET /api/v1/jobs with optional query parameters.
async listJobs(options?: { status?: string; limit?: number; offset?: number; }): Promise<any> { const params = new URLSearchParams(); if (options?.status) params.set("status", options.status); if (options?.limit) params.set("limit", String(options.limit)); if (options?.offset) params.set("offset", String(options.offset)); const qs = params.toString(); return this.request("GET", `/api/v1/jobs${qs ? `?${qs}` : ""}`); } - src/mcp.ts:57-75 (schema)The MCP tool schema/registration for 'list_jobs' — defines the tool name, description, and input parameters.
{ name: "list_jobs", description: "List fine-tuning training jobs on Tuning Engines. Returns recent jobs with status, base model, agent type, GPU usage, and cost. Use this to check on existing training runs or find a job ID.", inputSchema: { type: "object" as const, properties: { status: { type: "string", description: "Filter by status: queued, running, succeeded, failed, canceled", }, limit: { type: "number", description: "Max results (default 20)", }, }, }, }, - src/mcp.ts:54-689 (registration)Registration of all MCP tools via ListToolsRequestSchema — list_jobs is registered as one of the available tools.
// List available tools server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: "list_jobs", description: "List fine-tuning training jobs on Tuning Engines. Returns recent jobs with status, base model, agent type, GPU usage, and cost. Use this to check on existing training runs or find a job ID.", inputSchema: { type: "object" as const, properties: { status: { type: "string", description: "Filter by status: queued, running, succeeded, failed, canceled", }, limit: { type: "number", description: "Max results (default 20)", }, }, }, }, { name: "show_job", description: "Get full details of a specific fine-tuning job including status, base model, agent type, GPU minutes, cost, error messages, and whether it can be retried from checkpoint.", inputSchema: { type: "object" as const, properties: { job_id: { type: "string", description: "Job ID (UUID)" }, }, required: ["job_id"], }, }, { name: "create_job", description: "Fine-tune an LLM on a GitHub repository using Tuning Engines. " + "This trains a custom model that learns from the code patterns, style, and conventions in the repo. " + "Choose an agent to control the training approach:\n\n" + "AVAILABLE AGENTS:\n" + "- agent='code_repo' (Cody) — LoRA-based code fine-tuning using QLoRA (4-bit quantized LoRA) via the Axolotl framework. " + "Trains on your repo's code patterns, naming conventions, and project structure to produce a fast, lightweight adapter. " + "Best for: code autocomplete, inline suggestions, tab-complete, code style matching.\n" + "- agent='sera_code_repo' (SIERA) — Bug-fix specialist using the Open Coding Agents approach from AllenAI. " + "Generates synthetic error-resolution training pairs from your repo, producing a model that understands your " + "codebase's failure patterns and fix conventions. Best for: debugging, error resolution, patch generation, root cause analysis. " + "Supports quality_tier='low' (faster) or quality_tier='high' (deeper analysis, more training data).\n\n" + "SUPPORTED BASE MODELS (by size):\n" + "- 3B: Qwen/Qwen2.5-Coder-3B-Instruct\n" + "- 7-8B: codellama/CodeLlama-7b-hf, deepseek-ai/deepseek-coder-7b-instruct-v1.5, Qwen/Qwen2.5-Coder-7B-Instruct, Qwen/Qwen3-8B\n" + "- 13-15B: codellama/CodeLlama-13b-Instruct-hf, bigcode/starcoder2-15b, Qwen/Qwen2.5-Coder-14B-Instruct, Qwen/Qwen3-14B\n" + "- 22-27B: mistralai/Codestral-22B-v0.1, google/gemma-2-27b\n" + "- 30-34B: deepseek-ai/deepseek-coder-33b-instruct, codellama/CodeLlama-34b-Instruct-hf, Qwen/Qwen2.5-Coder-32B-Instruct, Qwen/Qwen3-Coder-30B-A3B, Qwen/Qwen3-32B\n" + "- 70-72B: codellama/CodeLlama-70b-Instruct-hf, meta-llama/Llama-3.1-70B-Instruct, Qwen/Qwen2.5-72B-Instruct\n\n" + "TYPICAL WORKFLOW: estimate_job first to check cost, then create_job, then job_status to monitor progress.", inputSchema: { type: "object" as const, properties: { base_model: { type: "string", description: "HuggingFace model ID to fine-tune (e.g. 'Qwen/Qwen2.5-Coder-7B-Instruct'). Required unless base_user_model_id is provided. Use list_supported_models to see all options.", }, base_user_model_id: { type: "string", description: "ID of a previously trained model to fine-tune further (iterative training). The base model is resolved automatically. Use list_models to find IDs.", }, output_name: { type: "string", description: "Name for the resulting fine-tuned model (e.g. 'my-project-cody-7b')", }, repo_url: { type: "string", description: "GitHub repository URL to train on (e.g. 'https://github.com/org/repo')", }, branch: { type: "string", description: "Git branch to use (default: main)", }, num_epochs: { type: "number", description: "Number of training epochs (more = better quality but higher cost)", }, max_examples: { type: "number", description: "Maximum training examples to extract from the repo (minimum: 2)", }, agent: { type: "string", enum: ["code_repo", "sera_code_repo"], description: "Training agent to use. 'code_repo' (Cody) = QLoRA-based fine-tuning for code autocomplete and inline suggestions. " + "'sera_code_repo' (SIERA) = bug-fix specialist using AllenAI's Open Coding Agents approach. " + "Default: 'code_repo'.", }, quality_tier: { type: "string", enum: ["low", "high"], description: "Quality tier (SIERA agent only). 'low' = faster, fewer synthetic pairs. 'high' = deeper analysis, more training data, better results. Default: 'low'.", }, s3_output_bucket: { type: "string", description: "S3 bucket to export the trained model to. If omitted, model is stored in Tuning Engines cloud storage.", }, s3_access_key_id: { type: "string", description: "AWS access key ID for S3 export", }, s3_secret_access_key: { type: "string", description: "AWS secret access key for S3 export", }, s3_region: { type: "string", description: "AWS region for S3 export (e.g. us-east-1)", }, }, required: ["output_name", "repo_url"], }, }, { name: "cancel_job", description: "Cancel a running or queued fine-tuning job. The job will be charged for any GPU time already used.", inputSchema: { type: "object" as const, properties: { job_id: { type: "string", description: "Job ID to cancel" }, }, required: ["job_id"], }, }, { name: "job_status", description: "Get live status of a fine-tuning job including current status, GPU minutes used, estimated charges, remaining balance, and delivery progress. Use this to monitor a running job.", inputSchema: { type: "object" as const, properties: { job_id: { type: "string", description: "Job ID" }, }, required: ["job_id"], }, }, { name: "retry_job", description: "Retry a failed fine-tuning job from its last checkpoint. Creates a new job that resumes training where the failed one stopped, saving GPU time. Each retry is billed separately.\n\n" + "IMPORTANT: This tool fetches a cost estimate and includes it in the response. " + "You MUST show the estimate to the user and get their explicit approval before considering the retry confirmed. " + "The retry is submitted automatically (the server validates balance), but always present the cost to the user.", inputSchema: { type: "object" as const, properties: { job_id: { type: "string", description: "ID of the failed job to retry", }, github_token: { type: "string", description: "GitHub Personal Access Token (required if original job used a private repo). Not stored — only sent to the training backend.", }, }, required: ["job_id"], }, }, { name: "estimate_job", description: "Get a cost estimate for a fine-tuning job before submitting it. Returns estimated cost, cost range, current balance, and whether balance is sufficient. Always estimate before creating a job.", inputSchema: { type: "object" as const, properties: { base_model: { type: "string", description: "HuggingFace model ID (e.g. 'Qwen/Qwen2.5-Coder-7B-Instruct'). Required unless base_user_model_id is provided.", }, base_user_model_id: { type: "string", description: "ID of a previously trained model. The base model is resolved automatically.", }, num_epochs: { type: "number", description: "Training epochs" }, max_examples: { type: "number", description: "Maximum examples" }, repo_size_mb: { type: "number", description: "Approximate repository size in MB (helps refine the estimate)", }, use_case: { type: "string", description: "Agent to use for the estimate (e.g. 'code_repo' for Cody, 'sera_code_repo' for SIERA). Defaults to code_repo.", }, }, }, }, { name: "validate_s3", description: "Validate S3 credentials by testing read/write access to the specified bucket. Use before submitting a job with S3 export.", inputSchema: { type: "object" as const, properties: { s3_bucket: { type: "string", description: "S3 bucket name" }, s3_access_key_id: { type: "string", description: "AWS access key ID" }, s3_secret_access_key: { type: "string", description: "AWS secret access key" }, s3_region: { type: "string", description: "AWS region (e.g. us-east-1)" }, }, required: ["s3_bucket", "s3_access_key_id", "s3_secret_access_key", "s3_region"], }, }, { name: "list_models", description: "List your trained and imported models on Tuning Engines.", inputSchema: { type: "object" as const, properties: {}, }, }, { name: "show_model", description: "Get details of a specific trained model.", inputSchema: { type: "object" as const, properties: { model_id: { type: "string", description: "Model ID (UUID)" }, }, required: ["model_id"], }, }, { name: "delete_model", description: "Delete a trained model from cloud storage.", inputSchema: { type: "object" as const, properties: { model_id: { type: "string", description: "Model ID to delete" }, }, required: ["model_id"], }, }, { name: "get_balance", description: "Check your Tuning Engines account balance and recent transactions.", inputSchema: { type: "object" as const, properties: {}, }, }, { name: "get_account", description: "Get your Tuning Engines account details and settings.", inputSchema: { type: "object" as const, properties: {}, }, }, { name: "list_supported_models", description: "List the supported base HuggingFace models available for fine-tuning on Tuning Engines. Optionally filter by agent to see only compatible models.", inputSchema: { type: "object" as const, properties: { agent: { type: "string", description: "Filter models compatible with this agent (e.g. 'code_repo', 'sera_code_repo'). Omit to see all models.", }, }, }, }, { name: "import_model", description: "Import a model from S3 into Tuning Engines cloud storage so it can be used as a base for future fine-tuning jobs.", inputSchema: { type: "object" as const, properties: { name: { type: "string", description: "Name for the imported model" }, source_s3_url: { type: "string", description: "S3 URL of the model to import (e.g. s3://bucket/path/to/model)", }, base_model: { type: "string", description: "HuggingFace model ID that this model was fine-tuned from", }, s3_access_key_id: { type: "string", description: "AWS access key ID" }, s3_secret_access_key: { type: "string", description: "AWS secret access key" }, s3_region: { type: "string", description: "AWS region (e.g. us-east-1)" }, }, required: ["name", "source_s3_url", "base_model", "s3_access_key_id", "s3_secret_access_key", "s3_region"], }, }, { name: "export_model", description: "Export a trained model from Tuning Engines cloud storage to your S3 bucket.", inputSchema: { type: "object" as const, properties: { model_id: { type: "string", description: "Model ID (UUID) to export" }, s3_bucket: { type: "string", description: "Destination S3 bucket name" }, s3_prefix: { type: "string", description: "Optional S3 key prefix for the exported model", }, s3_access_key_id: { type: "string", description: "AWS access key ID" }, s3_secret_access_key: { type: "string", description: "AWS secret access key" }, s3_region: { type: "string", description: "AWS region (e.g. us-east-1)" }, delete_after: { type: "boolean", description: "Delete the model from Tuning Engines storage after export (default: false)", }, }, required: ["model_id", "s3_bucket", "s3_access_key_id", "s3_secret_access_key", "s3_region"], }, }, { name: "model_status", description: "Check the status of a model import or export operation.", inputSchema: { type: "object" as const, properties: { model_id: { type: "string", description: "Model ID (UUID)" }, }, required: ["model_id"], }, }, { name: "list_catalog_models", description: "List available pre-built models and datasets from the Tuning Engines Marketplace. " + "These are platform-owned, ready-to-use assets that can be exported to your S3 bucket. " + "Returns name, description, base model, size, export price, and category.", inputSchema: { type: "object" as const, properties: { category: { type: "string", description: "Filter by category (e.g. 'code', 'bug-fix', 'general'). Omit to see all.", }, }, }, }, { name: "get_catalog_model", description: "Get detailed information about a specific pre-built model or dataset from the Marketplace including description, pricing, and export options.", inputSchema: { type: "object" as const, properties: { model_id: { type: "string", description: "Catalog model ID (UUID)" }, }, required: ["model_id"], }, }, { name: "export_catalog_model", description: "Export a pre-built model or dataset from the Marketplace to your S3 bucket. " + "Credits will be charged based on the export price upon successful completion.", inputSchema: { type: "object" as const, properties: { model_id: { type: "string", description: "Catalog model ID (UUID) to export" }, s3_bucket: { type: "string", description: "Destination S3 bucket name" }, s3_prefix: { type: "string", description: "Optional S3 key prefix for the exported model", }, s3_access_key_id: { type: "string", description: "AWS access key ID" }, s3_secret_access_key: { type: "string", description: "AWS secret access key" }, s3_region: { type: "string", description: "AWS region (e.g. us-east-1)" }, }, required: ["model_id", "s3_bucket", "s3_access_key_id", "s3_secret_access_key", "s3_region"], }, }, { name: "catalog_export_status", description: "Check the status of a Marketplace export operation. Returns status, charge info, and any error messages.", inputSchema: { type: "object" as const, properties: { model_id: { type: "string", description: "Catalog model ID (UUID)" }, export_id: { type: "string", description: "Export operation ID (UUID)" }, }, required: ["model_id", "export_id"], }, }, // --- Datasets --- { name: "list_datasets", description: "List datasets available for training and evaluation. Datasets can be uploaded from S3 and used for fine-tuning or model evaluation.", inputSchema: { type: "object" as const, properties: { limit: { type: "number", description: "Max results (default 20)" }, }, }, }, { name: "show_dataset", description: "Get details of a specific dataset including status, source, and metadata.", inputSchema: { type: "object" as const, properties: { dataset_id: { type: "string", description: "Dataset ID (UUID)" }, }, required: ["dataset_id"], }, }, { name: "create_dataset", description: "Create a new dataset by importing from S3. Datasets can be used for fine-tuning or model evaluation.", inputSchema: { type: "object" as const, properties: { name: { type: "string", description: "Name for the dataset" }, description: { type: "string", description: "Description of the dataset contents" }, source_type: { type: "string", description: "Source type (e.g. 's3')" }, s3_url: { type: "string", description: "S3 URL of the dataset (e.g. s3://bucket/path/data.jsonl)" }, s3_access_key_id: { type: "string", description: "AWS access key ID" }, s3_secret_access_key: { type: "string", description: "AWS secret access key" }, s3_region: { type: "string", description: "AWS region (e.g. us-east-1)" }, for_evaluation: { type: "boolean", description: "Whether this dataset is for evaluation (default: false)" }, }, required: ["name", "source_type"], }, }, { name: "delete_dataset", description: "Delete a dataset from the platform.", inputSchema: { type: "object" as const, properties: { dataset_id: { type: "string", description: "Dataset ID to delete" }, }, required: ["dataset_id"], }, }, { name: "dataset_status", description: "Check the status of a dataset import or processing operation.", inputSchema: { type: "object" as const, properties: { dataset_id: { type: "string", description: "Dataset ID (UUID)" }, }, required: ["dataset_id"], }, }, // --- Evaluations --- { name: "list_evaluations", description: "List model evaluations. Evaluations run your trained models against benchmark datasets using various evaluators to measure quality.", inputSchema: { type: "object" as const, properties: { status: { type: "string", description: "Filter by status: queued, running, succeeded, failed, canceled", }, limit: { type: "number", description: "Max results (default 20)" }, }, }, }, { name: "show_evaluation", description: "Get full details of a specific evaluation including status, scores, metrics, and comparison data.", inputSchema: { type: "object" as const, properties: { evaluation_id: { type: "string", description: "Evaluation ID (UUID)" }, }, required: ["evaluation_id"], }, }, { name: "create_evaluation", description: "Create a new model evaluation. Run your trained model or a base model against a dataset using selected evaluators. " + "Use list_evaluators to see available evaluators (e.g. code_execution, similarity, llm_judge).", inputSchema: { type: "object" as const, properties: { name: { type: "string", description: "Name for this evaluation run" }, user_model_id: { type: "string", description: "ID of your trained model to evaluate. Either this or base_model is required.", }, base_model: { type: "string", description: "HuggingFace model ID to evaluate (e.g. 'Qwen/Qwen2.5-Coder-7B-Instruct'). Either this or user_model_id is required.", }, dataset_id: { type: "string", description: "ID of the evaluation dataset to use. Must be a dataset marked for_evaluation.", }, evaluator_ids: { type: "array", items: { type: "string" }, description: "List of evaluator IDs to run (use list_evaluators to see options)", }, max_samples: { type: "number", description: "Maximum samples to evaluate (default: all)", }, }, required: ["dataset_id", "evaluator_ids"], }, }, { name: "cancel_evaluation", description: "Cancel a running or queued evaluation.", inputSchema: { type: "object" as const, properties: { evaluation_id: { type: "string", description: "Evaluation ID to cancel" }, }, required: ["evaluation_id"], }, }, { name: "evaluation_status", description: "Get live status of an evaluation including progress and current metrics.", inputSchema: { type: "object" as const, properties: { evaluation_id: { type: "string", description: "Evaluation ID (UUID)" }, }, required: ["evaluation_id"], }, }, { name: "list_evaluators", description: "List available evaluators for model evaluation. Evaluators measure different aspects of model quality like code execution, similarity, or LLM-based judgment.", inputSchema: { type: "object" as const, properties: {}, }, }, { name: "estimate_evaluation", description: "Get a cost estimate for an evaluation before running it.", inputSchema: { type: "object" as const, properties: { user_model_id: { type: "string", description: "ID of your trained model" }, base_model: { type: "string", description: "Or a HuggingFace model ID" }, dataset_id: { type: "string", description: "Evaluation dataset ID" }, evaluator_ids: { type: "array", items: { type: "string" }, description: "List of evaluator IDs", }, max_samples: { type: "number", description: "Max samples to evaluate" }, }, required: ["dataset_id", "evaluator_ids"], }, }, // --- Inference --- { name: "list_inference_models", description: "List models available for inference through the Tuning Engines inference API. " + "Includes both platform models and your deployed trained models.", inputSchema: { type: "object" as const, properties: {}, }, }, { name: "inference_usage", description: "Get inference API usage statistics including request counts, token usage, and costs.", inputSchema: { type: "object" as const, properties: { start_date: { type: "string", description: "Start date (YYYY-MM-DD)" }, end_date: { type: "string", description: "End date (YYYY-MM-DD)" }, model: { type: "string", description: "Filter by model name" }, }, }, }, { name: "get_inference_jwt", description: "Get a JWT token for authenticating with the Tuning Engines inference API. " + "Use this to make direct API calls to the inference endpoint.", inputSchema: { type: "object" as const, properties: {}, }, }, // --- Agents --- { name: "list_agents", description: "List available agents configured for your organization. Agents are AI assistants with specific capabilities and tool access.", inputSchema: { type: "object" as const, properties: {}, }, }, { name: "show_agent", description: "Get details of a specific agent including capabilities, tools, and configuration.", inputSchema: { type: "object" as const, properties: { agent_id: { type: "string", description: "Agent ID" }, }, required: ["agent_id"], }, }, ], })); - src/commands/jobs.ts:5-52 (helper)CLI command registration for 'jobs list' — a helper command that also calls client.listJobs() for CLI usage.
export function registerJobCommands( program: Command, getClient: () => TuningEnginesClient ): void { const jobs = program.command("jobs").description("Manage training jobs"); jobs .command("list") .description("List training jobs") .option("-s, --status <status>", "Filter by status (queued, running, succeeded, failed, canceled)") .option("-l, --limit <n>", "Max results", "20") .option("--json", "Output as JSON") .action(async (opts) => { try { const client = getClient(); const result = await client.listJobs({ status: opts.status, limit: parseInt(opts.limit), }); const jobs = result.data || []; if (opts.json) { output.json(jobs); return; } if (jobs.length === 0) { console.log("No jobs found."); return; } output.table( ["ID", "Status", "Base Model", "Output", "GPU Min", "Cost", "Created"], jobs.map((j: any) => [ j.id, j.status, j.base_model || "-", j.output_name || "-", String(j.gpu_minutes || 0), j.estimated_charges ? output.formatUsdAsCredits(Number(j.estimated_charges)) : "-", new Date(j.created_at).toLocaleDateString(), ]) ); } catch (err: any) { console.error(err.message); process.exit(1); } });