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

# Create job

> Create a new on-demand workflow job using either a template or custom DAG.

An *on-demand workflow job* is a job that takes one or more local files only as input, and whose temporary workflow exists only for the duration of the job's run

<Note>
  To run a workflow that was already created at some point in the past and still exists (also known as a *long-lived workflow*), see the [run workflow endpoint](/api-reference/api/workflow/run-workflow) instead.
  To run a workflow that takes files and data from remote locations as input (instead of local files), do the following instead:

  1. [Create a source connector](/api-reference/api/source/create-source) to the remote source locations.
  2. [Create a destination connector](/api-reference/api/destination/create-destination) to the remote destination location.
  3. [Create a long-lived workflow](/api-reference/api/workflow/create-workflow) that uses this specific source connector and destination connector.
  4. [Run this long-lived workflow manually](/api-reference/api/workflow/run-workflow), if you have not already created the workflow to run on a schedule.
</Note>

## Body

<ParamField body="request_data" type="string" required>
  Job configuration data.

  * To use a workflow template for a job, include a `template_id` field that specifies the unique ID of the workflow template. For more information, see [list templates](/api-reference/api/template/list-templates).
  * To use a custom workflow definition for a job, include a `job_nodes` field that specifies the settings for the job's workflow nodes. For instructions, see [Workflow Nodes](/api-reference/workflow/nodes/overview).
</ParamField>

<ParamField body="input_files" type="array">
  Input files to process. Upload as multipart/form-data, in the following format:

  ```
  --form "input_files=@</full/path/to/local/filename.extension>;filename=<filename.extension>;type=<local-file-media-type>" \
  --form "input_files=@</full/path/to/local/filename.extension>;filename=<filename.extension>;type=<local-file-media-type>" # For each additional file to be uploaded.
  ```

  For more information, see [Unstructured API Quickstart - On-Demand Jobs](/api-reference/quickstart).
</ParamField>

## Response

<ResponseField name="id" type="string" required>
  Unique identifier for the job.
</ResponseField>

<ResponseField name="workflow_id" type="string" required>
  Unique identifier of the workflow that created this job.
</ResponseField>

<ResponseField name="workflow_name" type="string" required>
  Name of the workflow that created this job.
</ResponseField>

<ResponseField name="status" type="string" required>
  Job status. One of: `SCHEDULED`, `IN_PROGRESS`, `COMPLETED`, `STOPPED`, `FAILED`.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp when the job was created.
</ResponseField>

<ResponseField name="runtime" type="string">
  ISO 8601 duration of the job run.
</ResponseField>

<ResponseField name="input_file_ids" type="array">
  IDs of input files for this job.
</ResponseField>

<ResponseField name="output_node_files" type="array">
  Output file metadata objects. Each object includes `node_id`, `file_id`, `node_type`, and `node_subtype`.
</ResponseField>

<ResponseField name="job_type" type="string">
  Job type. Default: `ephemeral`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url "${UNSTRUCTURED_API_URL}/api/v1/jobs/" \
    --header "unstructured-api-key: ${UNSTRUCTURED_API_KEY}" \
    --form "request_data={\"template_id\":\"f0a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c\"}" \
    --form "input_files=@/path/to/document.pdf"
  ```

  ```python Python SDK theme={null}
  import os
  from unstructured_client import UnstructuredClient
  from unstructured_client.models.operations import CreateJobRequest

  client = UnstructuredClient(
      api_key_auth=os.getenv("UNSTRUCTURED_API_KEY"),
      server_url=os.getenv("UNSTRUCTURED_API_URL"),
  )

  response = client.jobs.create_job(
      request=CreateJobRequest(
          request_data="{\"template_id\":\"f0a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c\"}"
      )
  )
  print(response)
  ```

  ```python Python SDK (async) theme={null}
  import asyncio
  import os
  from unstructured_client import UnstructuredClient
  from unstructured_client.models.operations import CreateJobRequest

  async def create_job():
      client = UnstructuredClient(
          api_key_auth=os.getenv("UNSTRUCTURED_API_KEY"),
          server_url=os.getenv("UNSTRUCTURED_API_URL"),
      )
      response = await client.jobs.create_job_async(
          request=CreateJobRequest(
              request_data="{\"template_id\":\"f0a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c\"}"
          )
      )
      print(response)

  asyncio.run(create_job())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "b2c3d4e5-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
    "workflow_id": "f0a1b2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
    "workflow_name": "My ETL Workflow",
    "status": "SCHEDULED",
    "created_at": "2026-01-01T00:00:00Z",
    "runtime": null,
    "input_file_ids": ["document.pdf"],
    "output_node_files": null,
    "job_type": "ephemeral"
  }
  ```
</ResponseExample>