# Training Our training endpoints allow you to programmatically train models based off of datasets you've uploaded to Akkio. They can be viewed as a better-designed v2 of our legacy `/v1/models` route. Training is a fundamentally long operation, so is surfaced through a polling-based mechanism where you make the following calls: * One call to `/new` to submit the task * Polling calls to `/{task_id}/status` to check up on your task's status * One last call to `/{task_id}/result` once `/status` indicates it's done ## Submit Controller > Model creation via API. ```json {"openapi":"3.1.0","info":{"title":"Akkio Public API (Beta)","version":"0.1.0"},"paths":{"/api/v1/models/train/new":{"post":{"description":"Model creation via API.","operationId":"_submit_controller_api_v1_models_train_new_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainRequestPayload"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APITaskStartedResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":" Submit Controller","tags":["Training"]}}},"components":{"schemas":{"TrainRequestPayload":{"additionalProperties":true,"properties":{"dataset_id":{"description":"The ID of the dataset to train the model on.","title":"Dataset Id","type":"string"},"duration":{"description":"Integer corresponding to how much time we should spend on training. Higher values will take longer but generally be more accurate. Allowed values: 10 (Fastest), 60 (High Quality), 300 (Higher Quality), 1800 (Production)","title":"Duration","type":"integer"},"extra_attention":{"default":false,"description":"Helps with predicting rare cases.","title":"Extra Attention","type":"boolean"},"force":{"default":false,"description":"Forces the creation of a new model even if another currently exists.","title":"Force","type":"boolean"},"ignore_fields":{"default":[],"description":"An array of field names to ignore (case sensitive).","items":{"type":"string"},"title":"Ignore Fields","type":"array"},"predict_fields":{"description":"An array of field names to predict (case sensitive).","items":{"type":"string"},"title":"Predict Fields","type":"array"}},"required":["dataset_id","predict_fields","duration"],"title":"TrainRequestPayload","type":"object"},"APITaskStartedResponse":{"additionalProperties":true,"properties":{"task_id":{"description":"The ID of the task that was started. This is generally queryable at a nearby `/status` endpoint to get the current status of the task.","title":"Task Id","type":"string"}},"required":["task_id"],"title":"APITaskStartedResponse","type":"object"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` ## Get Status Controller > Retrieves the status of the provided model creation call. ```json {"openapi":"3.1.0","info":{"title":"Akkio Public API (Beta)","version":"0.1.0"},"paths":{"/api/v1/models/train/{task_id}/status":{"get":{"description":"Retrieves the status of the provided model creation call.","operationId":"_get_status_controller_api_v1_models_train__task_id__status_get","parameters":[{"in":"path","name":"task_id","required":true,"schema":{"title":"Task Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIStatusResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":" Get Status Controller","tags":["Training"]}}},"components":{"schemas":{"APIStatusResponse":{"additionalProperties":true,"properties":{"metadata":{"description":"Metadata, contextually dependent on the status of the task being queried.","discriminator":{"mapping":{"FAILED":"#/components/schemas/APIStatusMetadataFailed","IN_PROGRESS":"#/components/schemas/APIStatusMetadataInProgress","PENDING":"#/components/schemas/APIStatusMetadataPending","SUCCEEDED":"#/components/schemas/APIStatusMetadataSucceeded"},"propertyName":"type"},"oneOf":[{"$ref":"#/components/schemas/APIStatusMetadataPending"},{"$ref":"#/components/schemas/APIStatusMetadataInProgress"},{"$ref":"#/components/schemas/APIStatusMetadataSucceeded"},{"$ref":"#/components/schemas/APIStatusMetadataFailed"}],"title":"Metadata"},"status":{"$ref":"#/components/schemas/TaskStatusEnum","description":"The current status of the task being queried."}},"required":["status","metadata"],"title":"APIStatusResponse","type":"object"},"APIStatusMetadataPending":{"additionalProperties":true,"properties":{"type":{"const":"PENDING","default":"PENDING","enum":["PENDING"],"title":"Type","type":"string"}},"title":"APIStatusMetadataPending","type":"object"},"APIStatusMetadataInProgress":{"additionalProperties":true,"properties":{"estimate_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"If provided, an estimate of how many seconds we expect this task to take. This value should be treated as a rough estimate on a best-effort basis, not a guarantee.","title":"Estimate Seconds"},"type":{"const":"IN_PROGRESS","default":"IN_PROGRESS","enum":["IN_PROGRESS"],"title":"Type","type":"string"}},"title":"APIStatusMetadataInProgress","type":"object"},"APIStatusMetadataSucceeded":{"additionalProperties":true,"properties":{"location":{"description":"The path at which you can submit a GET request to retrieve the result of the successful job. May require proper authentication or authorization to access.","title":"Location","type":"string"},"type":{"const":"SUCCEEDED","default":"SUCCEEDED","enum":["SUCCEEDED"],"title":"Type","type":"string"}},"required":["location"],"title":"APIStatusMetadataSucceeded","type":"object"},"APIStatusMetadataFailed":{"additionalProperties":true,"properties":{"error":{"default":"Unable to complete request. Please verify your inputs, try again later, or get in touch at support@akkio.com.","description":"If provided, a text representation of what went wrong with the task, including if any action on your part may rectify the issue.","title":"Error","type":"string"},"type":{"const":"FAILED","default":"FAILED","enum":["FAILED"],"title":"Type","type":"string"}},"title":"APIStatusMetadataFailed","type":"object"},"TaskStatusEnum":{"description":"Celery task status enum. Update apps/web-backend-api/src/types/TaskStatusEnum.ts if you update this enum.","enum":["PENDING","IN_PROGRESS","SUCCEEDED","FAILED","UNKNOWN_TIMEOUT"],"title":"TaskStatusEnum","type":"string"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` ## Get Result Controller > Retrieves the result of a model creation call. ```json {"openapi":"3.1.0","info":{"title":"Akkio Public API (Beta)","version":"0.1.0"},"paths":{"/api/v1/models/train/{task_id}/result":{"get":{"description":"Retrieves the result of a model creation call.","operationId":"_get_result_controller_api_v1_models_train__task_id__result_get","parameters":[{"in":"path","name":"task_id","required":true,"schema":{"title":"Task Id","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"title":"Response Get Result Controller Api V1 Models Train Task Id Result Get","type":"object"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":" Get Result Controller","tags":["Training"]}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}}} ``` *** ## Example Call Sequence[​](https://api-docs.akkio.com/endpoints/training#example-call-sequence) Here's a rough outline of how you'd make a request to the Inference bulk predictions endpoints. #### HTTP Headers[​](https://api-docs.akkio.com/endpoints/training#http-headers) | Header Name | Required | Value | | ----------- | -------- | ---------------------------------------------------------------------------------------------- | | X-API-Key | Yes | Your team's API key. See [Authentication](https://api-docs.akkio.com/concepts/authentication). | #### 1. Create Request[​](https://api-docs.akkio.com/endpoints/training#1-create-request) First, we'll submit the task into our asynchronous processing queue. `POST /api/v1/models/train/new` ``` { "dataset_id": "YTV32jCdVf5DbcMxzvX5", "predict_fields": ["Positive Lead"] } ``` You'll receive an object like this containing a task id: ``` { "task_id": "" } ``` We'll use this in the next request. #### 2. Query for Task Status[​](https://api-docs.akkio.com/endpoints/training#2-query-for-task-status) Next, we'll query the status endpoint at a cadence to see whether the task is complete yet. This request might look something like this: `GET /api/v1/models/train//status` Note that you must use the same Task ID that you received from the task creation endpoint above. This will provide you with a `status` field set to either `SUBMITTED`, `IN_PROGRESS`, `FAILED`, or `SUCCEEDED`. You can read more about each state on the [Asynchronous Endpoints](https://api-docs.akkio.com/concepts/asynchronous-endpoints) page. Here's an example response you might get: ``` { "status": "IN_PROGRESS", "metadata": { "type": "IN_PROGRESS" } } ``` You should retry ("poll") this endpoint at a regular cadence until you get a response that looks something like this: ``` { "status": "SUCCEEDED", "metadata": { "type": "SUCCEEDED", "location": "/api/v1/models/train//result" } } ``` note The `location` field is always relative to the **API root** (`https://api.akkio.com/api/v1`), *not* the overall website root (`https://api.akkio.com`). You'll need to remember to construct the end URL from the site name, API root, and the provided location. Armed with this information, we'll move to the last request. #### 3. Query for Result[​](https://api-docs.akkio.com/endpoints/training#3-query-for-result) Armed with the location we got from the status call, we'll make a request for the end result. `GET /api/v1/models/train//result` You'll get a response that looks something like this: ``` { "status": "success", "model_id": "AyooDGG4IB7iJDkgLKJR", "stats": [ [ { "field": 12, "field_name": "Positive Lead", "field_type": "category", "class": 0, "class_name": "0", "count": 19, "true positives": 19, "false positives": 0, "false negatives": 0, "precision": 1.0, "recall": 1.0, "f1": 1.0, "frequency": 0.95 }, { "field": 12, "field_name": "Positive Lead", "field_type": "category", "class": 1, "class_name": "1", "count": 1, "true positives": 1, "false positives": 0, "false negatives": 0, "precision": 1.0, "recall": 1.0, "f1": 1.0, "frequency": 0.05 } ] ], "field_importance": { "Job Title": 0.09528297930955887, "Years of Experience": 0.09974530339241028, "Company Size": 0.08637341856956482, "Industry": 0.08510678261518478, "Location": 0.050445690751075745, "Webinars Attended": 0.1286168396472931, "Whitepapers Downloaded": 0.10489732772111893, "Pages Visited": 0.08934492617845535, "Days Since Last Visit": 0.07931949943304062, "Email Open Rate": 0.08199360221624374, "Email Click Rate": 0.05456322059035301, "Responded to Survey": 0.04431045055389404, "Positive Lead": 8.27786672541464e-10 }, "data_story": [ { "name": "Positive Lead", "type": "category", "outcomes": [ { "outcome": "0", "causes": [ { "field": "Webinars Attended", "top_value": "3", "bottom_value": "3" }, { "field": "Whitepapers Downloaded", "top_value": "3", "bottom_value": "7" }, { "field": "Years of Experience", "top_value": "6", "bottom_value": "7" }, { "field": "Job Title", "top_value": "Executive", "bottom_value": "Assistant" }, { "field": "Pages Visited", "top_value": "27", "bottom_value": "1" } ], "top_case": 1.0, "avg_case": 0.94, "bottom_case": 1.0 }, { "outcome": "1", "causes": [ { "field": "Webinars Attended", "top_value": "3", "bottom_value": "3" }, { "field": "Whitepapers Downloaded", "top_value": "7", "bottom_value": "3" }, { "field": "Years of Experience", "top_value": "7", "bottom_value": "6" }, { "field": "Job Title", "top_value": "Assistant", "bottom_value": "Executive" }, { "field": "Pages Visited", "top_value": "1", "bottom_value": "27" } ], "top_case": 0.0, "avg_case": 0.06, "bottom_case": 0.0 } ] } ] } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.akkio.com/akkio-docs/endpoints-and-schemas/endpoints/training.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.