​
Overview

This endpoint allows users to retrieve a list of jobs associated with a specific workflow. It supports filtering by job ID, status, creator, or creation date. Only jobs tied to the specified workflow ID will be returned. Authentication via an authorization token is required.

  • Method: GET
  • URL: /v0/workflows/{workflow_id}/jobs
  • Operation: Retrieve jobs for a given 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 uniquely identifies the workflow whose associated jobs are to be listed. This ensures that only jobs relevant to the specified workflow are retrieved, maintaining clear scoping within the system.

NameTypeRequiredDescription
workflow_idstringYesUnique identifier of the workflow to fetch jobs from

​
Query Parameters

Query parameters allow you to narrow the job list based on specific needs. You can filter by job ID, job status (e.g., running or completed), creator’s user ID, or creation date. These filters help users efficiently find relevant jobs within large workflow histories.

NameTypeRequiredDescription
idstringNoFilter the results by a specific job ID
statusstringNoFilter jobs by current status (e.g., running, completed)
created_bystringNoFilter jobs by the user who created them
created_onstringNoFilter jobs by the date they were created (ISO 8601 format)

​
Response

A 200 OK response contains an array of job objects matching the provided criteria. Each object includes metadata like job ID, status, creator, and creation timestamp. The array may be empty if no jobs match the filter conditions or if none exist under the specified workflow.

NameTypeDescription
created_bystringUser ID of the person who created the job
idstringUnique identifier of the job
costnumberCost incurred or estimated for the job execution
workflow_idstringID of the workflow the job belongs to
created_atstringTimestamp when the job was created (ISO 8601 format)
updated_atstringTimestamp when the job was last updated (ISO 8601 format)
finished_atstringTimestamp when the job completed (ISO 8601 format)
estimated_durationnumberEstimated duration of the job in seconds
progressstringProgress indicator or percentage (e.g., “50%“)
statusstringCurrent status of the job (e.g., pending, running, completed, failed)
time_takenstringActual time taken to complete the job (e.g., “2m 35s” or ISO 8601 duration)
Here is a sample 200 response:
200
{
  "jobs": [
    {
      "created_by": "<string>",
      "id": "<string>",
      "cost": 123,
      "workflow_id": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "finished_at": "<string>",
      "estimated_duration": 123,
      "progress": "<string>",
      "status": "<string>",
      "time_taken": "<string>"
    }
  ]
}
A 400 Bad Request occurs when query parameters are malformed or invalid. A 403 Forbidden response indicates that the user does not have permission to access jobs under the specified workflow. Error responses include structured fields like code, message, and optional troubleshooting details.
400 403
{
  "error": {
    "code": "<string>",
    "details": "<any>",
    "message": "<string>"
  }
}

​
How to use the endpoint

  1. Prepare the Request Ensure you have the workflow_id and a valid bearer token. Optionally include query parameters for filtering jobs.
  2. Send the Request Make a GET request to https://api.pixxel.space/v0/workflows/{workflow_id}/jobs. Include your Authorization header.
  3. Handle the Response On success, you’ll receive an array of jobs matching the criteria. Handle errors based on status codes and messages in the response.