> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetypeai.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Start with /introduction/getting-started. Use the Direct Query API (POST /query) with the Newton Fusion model (text, image, and video reasoning) or the Newton Omega encoder (time-series embeddings). ATAI_API_ENDPOINT must include the version path: /v0.5 for most APIs, /v0.6 for the Fine-Tuning Service. Pages whose descriptions are marked (Archived) document the legacy Lens runtime — do not use them for new projects.

# Create Job

> Create a new batch or training job

<Callout icon="clock" color="#3064E3" iconType="solid">
  Requires [version 1.1.0](/release-notes/1.1.x#v1-1-0) or later of the Archetype platform.
</Callout>

## Overview

This endpoint creates a new job with the specified pipeline configuration and optional input files. The job is placed into the queue and will be processed when resources are available.

Inputs are organized by **port name**. The available ports depend on the pipeline — call [Get Pipeline Schema](/api-reference/batch/registry/pipelines/get-pipeline-schema) first if you don't know them. The two batch pipelines deployed on the platform today are:

* `machine-state-classification` — time-series sensor classification via an Omega encoder + KNN. Input ports: `worker.inference` (CSV files to classify), `worker.n_shots` (labeled CSV example files with `metadata.class`). Output port: `worker.results`.
* `activity-detection` — Newton C language model over a JSONL prompt file. Input port: `worker.data` (one JSONL file, each line an `InferenceRecord`). Output port: `worker.result`.

## Request

<ParamField body="name" type="string" required>
  A human-readable name for the job
</ParamField>

<ParamField body="pipeline_type" type="string" required>
  The type of pipeline to run. One of: `batch`, `training`
</ParamField>

<ParamField body="pipeline_key" type="string" required>
  The key identifying the pipeline to use from the registry (e.g. `machine-state-classification`, `activity-detection`)
</ParamField>

<ParamField body="pipeline_version" type="string">
  Specific pipeline version to use. If omitted, the latest published version is used.
</ParamField>

<ParamField body="inputs" type="object">
  Input files organized by port name. Each key is a port name (see the pipeline schema) and the value is an array of input file objects:

  * `file_id` (string, required) — The file ID returned from the Files API
  * `metadata` (object) — Optional per-input metadata. For n-shot ports this carries the class label (`{"class": "..."}`).
</ParamField>

<ParamField body="parameters" type="object">
  Pipeline parameters organized by component name (e.g. `worker`). Each value is an object with:

  * `parallelism` (integer) — Number of parallel workers for this component
  * `config` (object) — Free-form configuration passed to the container. The accepted shape is defined by the pipeline's `user_config_schema` — fetch it via [Get Pipeline Schema](/api-reference/batch/registry/pipelines/get-pipeline-schema).
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique job identifier (TypeID, `job_` prefix)
</ResponseField>

<ResponseField name="org_id" type="string">
  Organization identifier
</ResponseField>

<ResponseField name="name" type="string">
  Job name
</ResponseField>

<ResponseField name="pipeline_type" type="string">
  Pipeline type (`batch` or `training`)
</ResponseField>

<ResponseField name="pipeline_key" type="string">
  Pipeline key
</ResponseField>

<ResponseField name="pipeline_version" type="string">
  Pipeline version used
</ResponseField>

<ResponseField name="status" type="string">
  Initial job status (typically `PENDING`)
</ResponseField>

<ResponseField name="outcome" type="null">
  Omitted for any job whose status is not `COMPLETED`. <Badge color="blue">[v1.1.5+](/release-notes/1.1.x#v1-1-5)</Badge>
</ResponseField>

<ResponseField name="parameters" type="object">
  Resolved job parameters (user-supplied values merged onto the pipeline's `default_config`)
</ResponseField>

<ResponseField name="retry_count" type="integer">
  Number of times the job has been retried (always `0` on create)
</ResponseField>

<ResponseField name="preemption_count" type="integer">
  Number of times the job has been preempted (always `0` on create)
</ResponseField>

<ResponseField name="queue_position" type="integer">
  Position in the queue at admission time. Omitted from the response when not queued (e.g. terminal-state jobs).
</ResponseField>

<ResponseField name="queue_depth" type="integer">
  Total queue depth at admission time. Omitted from the response when not queued.
</ResponseField>

<ResponseField name="input_progress" type="object">
  Per-status counts of tracked inputs (`pending`, `processing`, `completed`, `failed`). **Omitted from this response** — populated only on read paths like `GET /batch/jobs` and `GET /batch/jobs/{id}`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Creation timestamp in RFC 3339 format
</ResponseField>

<ResponseField name="updated_at" type="string">
  Last update timestamp
</ResponseField>

<ResponseField name="started_at" type="string">
  Start timestamp, or `null` if not yet started
</ResponseField>

<ResponseField name="completed_at" type="string">
  Completion timestamp, or `null`
</ResponseField>

<ResponseField name="failed_at" type="string">
  Failure timestamp, or `null`
</ResponseField>

<ResponseField name="cancelled_at" type="string">
  Cancellation timestamp, or `null`
</ResponseField>

<ResponseField name="error" type="object">
  Error details, or `null`
</ResponseField>

## Examples

The two batch pipelines deployed on the platform take very different request bodies. Switch tabs to compare.

<Tabs>
  <Tab title="machine-state-classification">
    Classify time-series sensor data using n-shot example files. Inputs split across two ports — `worker.inference` for the CSVs to classify and `worker.n_shots` for the labeled example files (class declared via `metadata.class`).

    <CodeGroup>
      ```bash cURL theme={"system"}
      curl -X POST https://api.u1.archetypeai.app/v0.5/batch/jobs \
        -H "Authorization: Bearer $ATAI_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "tep-classification",
          "pipeline_type": "batch",
          "pipeline_key": "machine-state-classification",
          "inputs": {
            "worker.inference": [
              {"file_id": "tep_inference.csv"}
            ],
            "worker.n_shots": [
              {"file_id": "tep_normal.csv", "metadata": {"class": "normal"}},
              {"file_id": "tep_fault.csv",  "metadata": {"class": "fault"}}
            ]
          },
          "parameters": {
            "worker": {
              "parallelism": 1,
              "config": {
                "model_type": "omega_1_4_base",
                "batch_size": 32,
                "reader_config": {
                  "data_columns": ["xmeas_1", "xmeas_2", "xmv_11"],
                  "timestamp_column": "timestamp",
                  "window_size": 64,
                  "step_size": 1
                },
                "classifier_config": {
                  "n_neighbors": 5,
                  "metric": "euclidean",
                  "weights": "uniform",
                  "normalize_embeddings": false
                },
                "flush_every_n_iteration": 150
              }
            }
          }
        }'
      ```

      ```python Python theme={"system"}
      import requests
      import os

      api_key = os.environ.get("ATAI_API_KEY")

      response = requests.post(
          "https://api.u1.archetypeai.app/v0.5/batch/jobs",
          headers={
              "Authorization": f"Bearer {api_key}",
              "Content-Type": "application/json",
          },
          json={
              "name": "tep-classification",
              "pipeline_type": "batch",
              "pipeline_key": "machine-state-classification",
              "inputs": {
                  "worker.inference": [
                      {"file_id": "tep_inference.csv"},
                  ],
                  "worker.n_shots": [
                      {"file_id": "tep_normal.csv", "metadata": {"class": "normal"}},
                      {"file_id": "tep_fault.csv",  "metadata": {"class": "fault"}},
                  ],
              },
              "parameters": {
                  "worker": {
                      "parallelism": 1,
                      "config": {
                          "model_type": "omega_1_4_base",
                          "batch_size": 32,
                          "reader_config": {
                              "data_columns": ["xmeas_1", "xmeas_2", "xmv_11"],
                              "timestamp_column": "timestamp",
                              "window_size": 64,
                              "step_size": 1,
                          },
                          "classifier_config": {
                              "n_neighbors": 5,
                              "metric": "euclidean",
                              "weights": "uniform",
                              "normalize_embeddings": False,
                          },
                          "flush_every_n_iteration": 150,
                      },
                  }
              },
          },
      )

      job = response.json()
      print(f"Job created: {job['id']} — Status: {job['status']}")
      ```

      ```javascript JavaScript theme={"system"}
      const response = await fetch('https://api.u1.archetypeai.app/v0.5/batch/jobs', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          name: 'tep-classification',
          pipeline_type: 'batch',
          pipeline_key: 'machine-state-classification',
          inputs: {
            'worker.inference': [
              { file_id: 'tep_inference.csv' }
            ],
            'worker.n_shots': [
              { file_id: 'tep_normal.csv', metadata: { class: 'normal' } },
              { file_id: 'tep_fault.csv',  metadata: { class: 'fault' } }
            ]
          },
          parameters: {
            worker: {
              parallelism: 1,
              config: {
                model_type: 'omega_1_4_base',
                batch_size: 32,
                reader_config: {
                  data_columns: ['xmeas_1', 'xmeas_2', 'xmv_11'],
                  timestamp_column: 'timestamp',
                  window_size: 64,
                  step_size: 1
                },
                classifier_config: {
                  n_neighbors: 5,
                  metric: 'euclidean',
                  weights: 'uniform',
                  normalize_embeddings: false
                },
                flush_every_n_iteration: 150
              }
            }
          }
        })
      });

      const job = await response.json();
      console.log(`Job created: ${job.id} — Status: ${job.status}`);
      ```
    </CodeGroup>

    **Response — `201 Created`**

    ```json theme={"system"}
    {
      "id": "job_2abc3def4ghi5jkl6mno7pqr",
      "org_id": "org_1abc2def3ghi4jkl",
      "name": "tep-classification",
      "pipeline_type": "batch",
      "pipeline_key": "machine-state-classification",
      "pipeline_version": "1.1.1",
      "status": "PENDING",
      "parameters": {
        "worker": {
          "parallelism": 1,
          "config": {
            "model_type": "omega_1_4_base",
            "batch_size": 32,
            "reader_config": {
              "data_columns": ["xmeas_1", "xmeas_2", "xmv_11"],
              "timestamp_column": "timestamp",
              "window_size": 64,
              "step_size": 1
            },
            "classifier_config": {
              "n_neighbors": 5,
              "metric": "euclidean",
              "weights": "uniform",
              "normalize_embeddings": false
            },
            "flush_every_n_iteration": 150
          }
        }
      },
      "retry_count": 0,
      "preemption_count": 0,
      "created_at": "2026-04-14T10:00:00Z",
      "updated_at": "2026-04-14T10:00:00Z",
      "started_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancelled_at": null,
      "error": null
    }
    ```

    See the [`newton-machine-state-batch`](https://github.com/archetypeai/archetypeai-agent-skills/blob/main/skills/newton-machine-state-batch/SKILL.md) skill for model selection (`omega_1_4_base` vs the legacy 1.3 variants), `window_size` / `step_size` guidance at high sample rates, and the within-distribution vs cross-condition accuracy pitfall.
  </Tab>

  <Tab title="activity-detection">
    Run the Newton C language model over a JSONL prompt file. Single input port `worker.data` containing one JSONL file; each line is an `InferenceRecord` (`system?`, `instruction?`, `prompt?`, optional `inputs[]` carrying text/image/video evidence as inline base64). Output is one JSON line per record: `{"line_index": N, "prediction": "..."}`.

    <CodeGroup>
      ```bash cURL theme={"system"}
      curl -X POST https://api.u1.archetypeai.app/v0.5/batch/jobs \
        -H "Authorization: Bearer $ATAI_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "narrative-generation",
          "pipeline_type": "batch",
          "pipeline_key": "activity-detection",
          "inputs": {
            "worker.data": [{"file_id": "my_prompts.jsonl"}]
          },
          "parameters": {
            "worker": {
              "parallelism": 1,
              "config": {
                "generation": {
                  "max_new_tokens": 1024,
                  "do_sample": true,
                  "temperature": 0.7,
                  "top_p": 0.8,
                  "top_k": 20,
                  "repetition_penalty": 1
                }
              }
            }
          }
        }'
      ```

      ```python Python theme={"system"}
      import requests
      import os

      api_key = os.environ.get("ATAI_API_KEY")

      response = requests.post(
          "https://api.u1.archetypeai.app/v0.5/batch/jobs",
          headers={
              "Authorization": f"Bearer {api_key}",
              "Content-Type": "application/json",
          },
          json={
              "name": "narrative-generation",
              "pipeline_type": "batch",
              "pipeline_key": "activity-detection",
              "inputs": {
                  "worker.data": [{"file_id": "my_prompts.jsonl"}],
              },
              "parameters": {
                  "worker": {
                      "parallelism": 1,
                      "config": {
                          "generation": {
                              "max_new_tokens": 1024,
                              "do_sample": True,
                              "temperature": 0.7,
                              "top_p": 0.8,
                              "top_k": 20,
                              "repetition_penalty": 1,
                          }
                      },
                  }
              },
          },
      )

      job = response.json()
      print(f"Job created: {job['id']} — Status: {job['status']}")
      ```

      ```javascript JavaScript theme={"system"}
      const response = await fetch('https://api.u1.archetypeai.app/v0.5/batch/jobs', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.ATAI_API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          name: 'narrative-generation',
          pipeline_type: 'batch',
          pipeline_key: 'activity-detection',
          inputs: {
            'worker.data': [{ file_id: 'my_prompts.jsonl' }]
          },
          parameters: {
            worker: {
              parallelism: 1,
              config: {
                generation: {
                  max_new_tokens: 1024,
                  do_sample: true,
                  temperature: 0.7,
                  top_p: 0.8,
                  top_k: 20,
                  repetition_penalty: 1
                }
              }
            }
          }
        })
      });

      const job = await response.json();
      console.log(`Job created: ${job.id} — Status: ${job.status}`);
      ```
    </CodeGroup>

    **Response — `201 Created`**

    ```json theme={"system"}
    {
      "id": "job_3xyz4abc5def6ghi7jkl8mno",
      "org_id": "org_1abc2def3ghi4jkl",
      "name": "narrative-generation",
      "pipeline_type": "batch",
      "pipeline_key": "activity-detection",
      "pipeline_version": "1.1.1",
      "status": "PENDING",
      "parameters": {
        "worker": {
          "parallelism": 1,
          "config": {
            "generation": {
              "max_new_tokens": 1024,
              "do_sample": true,
              "temperature": 0.7,
              "top_p": 0.8,
              "top_k": 20,
              "repetition_penalty": 1
            }
          }
        }
      },
      "retry_count": 0,
      "preemption_count": 0,
      "created_at": "2026-04-14T10:00:00Z",
      "updated_at": "2026-04-14T10:00:00Z",
      "started_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancelled_at": null,
      "error": null
    }
    ```

    See the [`newton-activity-detection-batch`](https://github.com/archetypeai/archetypeai-agent-skills/blob/main/skills/newton-activity-detection-batch/SKILL.md) skill for the full `InferenceRecord` schema (text / image / video inputs), the \~4K-token quality cliff for CSV-heavy inputs, MapReduce / hierarchical reduce patterns, and the two silent join bugs to watch for when chaining reduce stages.
  </Tab>
</Tabs>

## Error responses

```json 400 - Invalid Request theme={"system"}
{
  "code": "INVALID_REQUEST",
  "message": "pipeline_key 'nonexistent-pipeline' not found in registry",
  "error_uid": "err_abc123",
  "suggestion": "Check available pipelines with GET /batch/registry/pipelines"
}
```

```json 401 - Unauthorized theme={"system"}
{
  "detail": "Invalid access with key: api_key_not_found"
}
```