> ## Documentation Index > Fetch the complete documentation index at: https://docs.mathfi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Start a training run on a dataset > Start a Crucible run against a dataset. The dataset must be `COMPLETED`. The run trains many attempts at once across three algorithm families, scores each on the 20% test data, ranks them by fewest wrong decisions, and keeps the best three as v1, v2 and v3 of one model. v1 becomes the champion; `POST /api/v1/training/{trainingJobKey}/champion` moves it. Two settings: * `performanceThreshold` — the accuracy each attempt aims for, between 0 and 1. **Set this to the dataset's `recommendedThreshold` when it has one.** A dataset that came from a refinement carries the target that refinement actually reached; a target far above it makes every attempt run to its time cap, and the run can settle on a model that predicts one class for every row. Where there is no `recommendedThreshold`, start near what the data plausibly supports rather than at 0.9. * `scalingFactor` — an integer, 0 to 499. 19 is the working default and rarely needs changing. Returns immediately. Poll `GET /api/v1/training/{trainingJobKey}/progress` until the status is terminal, honouring `nextPollAfterSeconds`. ## OpenAPI ````yaml api-reference/openapi.yaml POST /api/v1/training/datasets/{datasetKey} openapi: 3.0.1 info: title: MathFi.ai API description: > The MathFi.ai REST API runs the two products end to end. **Feature Refinery** takes your labelled data and works out which columns actually carry the signal. It returns a reduced train and test pair, a per-column keep/remove decision, and the performance target the refined data reached. **Model Crucible** takes a dataset, trains every algorithm family against it at once, ranks the results on held-out data by fewest wrong decisions, and keeps the best three as versions of one model. You pick which one predictions run against. Everything is asynchronous: you create a thing, upload to a signed URL, start it, then poll until the state is terminal. Nothing streams and nothing blocks. contact: name: MathFi.ai url: https://mathfi.ai email: support@mathfi.ai license: name: MathFi.ai url: https://mathfi.ai version: 1.0.0 servers: - url: https://{tenant}-api.mathfi.ai description: >- Your tenant's API. Each customer has their own, so the host varies. Replace {tenant} with the name issued when your tenant was created. variables: tenant: default: your-tenant description: The tenant name issued to you. security: - BearerAuth: [] tags: - name: Authentication description: Exchange credentials for a bearer token - name: Feature Refinery description: Reduce a dataset to the columns that earn their place - name: Datasets description: >- Prepare labelled data for training, from uploads or from a finished refinement - name: Training description: Run the Crucible against a dataset and choose the champion model - name: Models description: Trained models and their versions - name: Predictions description: Score unlabelled data against a champion model paths: /api/v1/training/datasets/{datasetKey}: post: tags: - Training summary: Start a training run on a dataset description: > Start a Crucible run against a dataset. The dataset must be `COMPLETED`. The run trains many attempts at once across three algorithm families, scores each on the 20% test data, ranks them by fewest wrong decisions, and keeps the best three as v1, v2 and v3 of one model. v1 becomes the champion; `POST /api/v1/training/{trainingJobKey}/champion` moves it. Two settings: * `performanceThreshold` — the accuracy each attempt aims for, between 0 and 1. **Set this to the dataset's `recommendedThreshold` when it has one.** A dataset that came from a refinement carries the target that refinement actually reached; a target far above it makes every attempt run to its time cap, and the run can settle on a model that predicts one class for every row. Where there is no `recommendedThreshold`, start near what the data plausibly supports rather than at 0.9. * `scalingFactor` — an integer, 0 to 499. 19 is the working default and rarely needs changing. Returns immediately. Poll `GET /api/v1/training/{trainingJobKey}/progress` until the status is terminal, honouring `nextPollAfterSeconds`. operationId: createTraining parameters: - name: datasetKey in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/TrainingRequest' examples: Example training request: summary: Successful training job creation request value: scalingFactor: 19 performanceThreshold: 0.85 required: true responses: '201': description: Training job successfully created content: application/json: schema: $ref: '#/components/schemas/TrainingJobCreationOutput' examples: Successful training job creation response: summary: Successful training job creation response value: | { "trainingJobKey": "41eac90e-de55-4d60-8b10-8a57ee27db2e", "datasetKey": "7215eec1-f233-419e-bad2-8fda560dff75", "status": "PENDING" } '400': description: Invalid training job submission '429': description: >- You already have as many training jobs running as you are allowed. Nothing was created — the same request works once one of yours finishes. '500': description: Internal server error components: schemas: TrainingRequest: required: - performanceThreshold - scalingFactor type: object properties: scalingFactor: maximum: 499 minimum: 0 type: integer format: int32 example: 19 performanceThreshold: maximum: 1 minimum: 0 type: number format: double description: >- Read this off the dataset's recommendedThreshold where it has one, rather than choosing a round number. See the endpoint description. example: 0.70336 TrainingJobCreationOutput: required: - datasetKey - status - targetPerformance - trainingJobKey type: object properties: trainingJobKey: type: string format: uuid datasetKey: type: string format: uuid status: $ref: '#/components/schemas/TrainingJobStatus' TrainingJobStatus: type: string description: > Status of training: * `PENDING` - The training job has been created and is pending execution * `RUNNING` - The training job is currently executing and progressing * `COMPLETED` - The training job has completed execution successfully, reaching the target performance. A model has been generated. * `TIMED_OUT` - The training job could not reach the target performance in the configured * `CANCELLED` - The training job has been cancelled by the user * `NOT_COMPLETED` - The training job has stalled without making progress in a specified timeframe * `FAILED` - The training job has failed due to an error enum: - PENDING - RUNNING - COMPLETED - TIMED_OUT - CANCELLED - FAILED - NOT_COMPLETED securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT ````