​
Overview

This endpoint is used to create a new job from a specified workflow. You must provide the workflow_id as a path parameter and the associated project_id as a query parameter. The response returns full job metadata including execution details, status, and task results. Authentication is required.

  • Method: POST
  • URL: /v0/workflows/{workflow_id}/jobs
  • Operation: Create a new job from a workflow
  • Authentication Required: Yes

​
Authorization

You need the api key which you can get from the API tab in Organization Settings. The api key is required in almost all the commands

Authorization: <YOUR_API_KEY>

​
Path Parameters

The workflow_id path parameter identifies the specific workflow from which the job should be created. It ensures that the job is associated with the correct workflow logic, configurations, and processing structure. This parameter is essential to determine the template or pipeline that the job will execute.

NameTypeRequiredDescription
workflow_idstringYesUnique ID of the workflow to create the job from

​
Query Parameters

The project_id query parameter links the job creation to a specific project. It validates that the user has access to the project under which the workflow exists. This scoping is important to enforce security boundaries and maintain proper organizational ownership of workflows and jobs within the platform.

NameTypeRequiredDescription
project_idstringYesIdentifier of the project the workflow is part of

​
Response

A 200 OK response returns complete metadata for the newly created job, including progress, cost, status, and timestamps. It also includes any validation errors or task-level results, enabling users to track and manage job execution immediately after it has been queued or started.

NameTypeDescription
created_bystringUser ID of the person who created the job
statusstringCurrent status of the job (e.g., running, completed, failed)
time_takenstringTotal time taken by the job (human-readable)
idstringUnique identifier of the job
tasksobject[]List of tasks executed within the job
val_errorsobject[]List of validation errors encountered during execution
specinteger[]Raw specification data of the job
costintegerToken or compute cost of the job
workflow_idstringID of the workflow this job belongs to
updated_atstringTimestamp when the job was last updated
finished_atstringTimestamp when the job completed (nullable if still running)
exec_created_atstringTimestamp when the job execution was initialized
exec_updated_atstringTimestamp of the last execution update
created_atstringTimestamp when the job was created
estimated_durationintegerEstimated time to complete the job in seconds
progressstringCurrent completion progress (e.g., “45%”)
Here is a sample 200 OK response:
200
{
  "created_by": "<string>",
  "status": "<string>",
  "time_taken": "<string>",
  "id": "<string>",
  "tasks": [
    {
      "id": "<string>",
      "info_logs": [
        123
      ],
      "created_at": "<string>",
      "updated_at": "<string>",
      "finished_at": "<string>",
      "estimated_time_duration": 123,
      "time_taken": "<string>",
      "status": "<string>",
      "state_msg": "<string>",
      "inputs": [
        123
      ],
      "result": [
        123
      ],
      "depends_on": [
        "<string>"
      ],
      "name": "<string>",
      "progress": 123,
      "disclaimer": [
        "<string>"
      ],
      "recv_time": "<string>",
      "send_time": "<string>",
      "block_inf_start_time": "<string>",
      "block_inf_end_time": "<string>",
      "block_info": {
        "id": "<string>",
        "name": "<string>",
        "version": "<string>"
      },
      "err_msg": "<string>",
      "failure_type": "<string>"
    }
  ],
  "val_errors": [
    {
      "from": "<string>",
      "to": "<string>",
      "err": "<string>",
      "reason": "<string>",
      "component_name": "<string>"
    }
  ],
  "spec": [
    123
  ],
  "cost": 123,
  "workflow_id": "<string>",
  "updated_at": "<string>",
  "finished_at": "<string>",
  "exec_created_at": "<string>",
  "exec_updated_at": "<string>",
  "created_at": "<string>",
  "estimated_duration": 123,
  "progress": "<string>"
}
A 400 Bad Request occurs if required parameters like project_id or workflow_id are missing or invalid. A 403 Forbidden response indicates lack of permission to create a job under the given workflow. Structured error responses include a code, message, and optional details for debugging.
400 403
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}

​
How to use the endpoint

  • Prepare Your Request Ensure you have the workflow_id as a path parameter and project_id as a query parameter. Add your Authorization token to the header.
  • Send the Request Make a POST request to https://api.pixxel.space/v0/workflows/{workflow_id}/jobs?project_id={project_id}
  • Process the Response A successful response will return the new job object. Use its metadata to monitor progress or access task results. Handle any 400/403 errors using the returned error object.