Create a task execution record

curl --request POST \
  --url https://flows.super.ai/api/task-executions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "flow_execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "task_execution_idx": 1,
  "task_name": "<string>",
  "error": "<unknown>",
  "input": "<unknown>",
  "output": "<unknown>"
}
'

import requests

url = "https://flows.super.ai/api/task-executions"

payload = {
    "flow_execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "<string>",
    "task_execution_idx": 1,
    "task_name": "<string>",
    "error": "<unknown>",
    "input": "<unknown>",
    "output": "<unknown>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-API-Key': '<api-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    flow_execution_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    status: '<string>',
    task_execution_idx: 1,
    task_name: '<string>',
    error: '<unknown>',
    input: '<unknown>',
    output: '<unknown>'
  })
};

fetch('https://flows.super.ai/api/task-executions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://flows.super.ai/api/task-executions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'flow_execution_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'status' => '<string>',
    'task_execution_idx' => 1,
    'task_name' => '<string>',
    'error' => '<unknown>',
    'input' => '<unknown>',
    'output' => '<unknown>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://flows.super.ai/api/task-executions"

	payload := strings.NewReader("{\n  \"flow_execution_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"status\": \"<string>\",\n  \"task_execution_idx\": 1,\n  \"task_name\": \"<string>\",\n  \"error\": \"<unknown>\",\n  \"input\": \"<unknown>\",\n  \"output\": \"<unknown>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://flows.super.ai/api/task-executions")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"flow_execution_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"status\": \"<string>\",\n  \"task_execution_idx\": 1,\n  \"task_name\": \"<string>\",\n  \"error\": \"<unknown>\",\n  \"input\": \"<unknown>\",\n  \"output\": \"<unknown>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://flows.super.ai/api/task-executions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"flow_execution_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"status\": \"<string>\",\n  \"task_execution_idx\": 1,\n  \"task_name\": \"<string>\",\n  \"error\": \"<unknown>\",\n  \"input\": \"<unknown>\",\n  \"output\": \"<unknown>\"\n}"

response = http.request(request)
puts response.read_body

{
  "flow_execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "task_execution_idx": 1,
  "task_name": "<string>",
  "created_at": "2025-01-23T10:30:00Z",
  "error": {
    "message": "Connection timeout after 30 seconds",
    "traceback": "Traceback (most recent call last):\n  ...",
    "type": "ConnectionError"
  },
  "input": "<unknown>",
  "modified_by": "system",
  "output": {
    "email_id": "msg_123",
    "sent_at": "2025-01-23T10:30:00Z"
  },
  "updated_at": "2025-01-23T10:35:00Z"
}

task-executions

Create a task execution record

Create a new task execution record for a specific task within a flow execution.

Overview Task executions represent individual task invocations within a flow execution. Each task in a flow can be executed multiple times (retries, loops), tracked by task_execution_idx. This endpoint is primarily used by system workers to report task execution state.

Resource Hierarchy Organization → Flow → Flow Execution → Task Execution

Lifecycle Task executions progress through states: queued → running → completed/failed

queued: Task scheduled but not yet started
running: Task currently executing
completed: Task finished successfully with output
failed: Task encountered an error

Use Cases

Workers reporting task execution start/completion
Recording task outputs for downstream tasks
Tracking task execution history and retries
Debugging failed workflow executions

Idempotency This endpoint is idempotent based on (flow_execution_id, task_name, task_execution_idx). If a task execution with these identifiers exists, it will be updated rather than creating a duplicate.

Performance Notes WebSocket notifications are processed in the background to ensure fast worker responses. The endpoint returns immediately after database write; notifications are async.

Related Endpoints

GET /task-executions - List task executions with filtering
PUT /task-executions - Update existing task execution and optionally re-execute flow
GET /flow-executions/ - View parent flow execution

POST

api

task-executions

Create a task execution record

curl --request POST \
  --url https://flows.super.ai/api/task-executions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "flow_execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "task_execution_idx": 1,
  "task_name": "<string>",
  "error": "<unknown>",
  "input": "<unknown>",
  "output": "<unknown>"
}
'

import requests

url = "https://flows.super.ai/api/task-executions"

payload = {
    "flow_execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "status": "<string>",
    "task_execution_idx": 1,
    "task_name": "<string>",
    "error": "<unknown>",
    "input": "<unknown>",
    "output": "<unknown>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-API-Key': '<api-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    flow_execution_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    status: '<string>',
    task_execution_idx: 1,
    task_name: '<string>',
    error: '<unknown>',
    input: '<unknown>',
    output: '<unknown>'
  })
};

fetch('https://flows.super.ai/api/task-executions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://flows.super.ai/api/task-executions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'flow_execution_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'status' => '<string>',
    'task_execution_idx' => 1,
    'task_name' => '<string>',
    'error' => '<unknown>',
    'input' => '<unknown>',
    'output' => '<unknown>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://flows.super.ai/api/task-executions"

	payload := strings.NewReader("{\n  \"flow_execution_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"status\": \"<string>\",\n  \"task_execution_idx\": 1,\n  \"task_name\": \"<string>\",\n  \"error\": \"<unknown>\",\n  \"input\": \"<unknown>\",\n  \"output\": \"<unknown>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://flows.super.ai/api/task-executions")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"flow_execution_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"status\": \"<string>\",\n  \"task_execution_idx\": 1,\n  \"task_name\": \"<string>\",\n  \"error\": \"<unknown>\",\n  \"input\": \"<unknown>\",\n  \"output\": \"<unknown>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://flows.super.ai/api/task-executions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"flow_execution_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"status\": \"<string>\",\n  \"task_execution_idx\": 1,\n  \"task_name\": \"<string>\",\n  \"error\": \"<unknown>\",\n  \"input\": \"<unknown>\",\n  \"output\": \"<unknown>\"\n}"

response = http.request(request)
puts response.read_body

{
  "flow_execution_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organization_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "<string>",
  "task_execution_idx": 1,
  "task_name": "<string>",
  "created_at": "2025-01-23T10:30:00Z",
  "error": {
    "message": "Connection timeout after 30 seconds",
    "traceback": "Traceback (most recent call last):\n  ...",
    "type": "ConnectionError"
  },
  "input": "<unknown>",
  "modified_by": "system",
  "output": {
    "email_id": "msg_123",
    "sent_at": "2025-01-23T10:30:00Z"
  },
  "updated_at": "2025-01-23T10:35:00Z"
}

Authorizations

X-API-Key

string

header

required

API key authentication. Include your API key in the X-API-Key header as: X-API-Key YOUR_API_KEY

Example:

X-API-Key: saf_1234567890

Authorization

string

header

required

JWT Bearer token authentication. Include your access token in the Authorization header as: Bearer YOUR_ACCESS_TOKEN

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

application/json

Request model for creating or updating a task execution.

This model is used by system workers to report task execution state. Fields are intentionally simplified to reduce worker complexity. The server infers additional fields like organization_id and timestamps.

flow_execution_id

string<uuid>

required

ID of the parent flow execution containing this task. Used to determine organization_id and maintain execution hierarchy.

Example:

"123e4567-e89b-12d3-a456-426614174000"

status

string

required

Current execution status of the task. Valid values: 'queued', 'running', 'completed', 'failed', 'cancelled'. Server validates against ExecutionStatus enum. Status transitions are: queued → running → (completed|failed|cancelled).

Examples:

"running"

"completed"

"failed"

task_execution_idx

integer

required

Zero-based execution index for this task. Increments for each execution of the same task (retries, loops). Combines with flow_execution_id and task_name to form unique identifier.

Required range: x >= 0

Examples:

0

1

2

task_name

string

required

Name of the task as defined in the flow definition YAML. Must match a task name in the flow's task list. Case-sensitive identifier used for task lookups.

Required string length: 1 - 200

Examples:

"send_email"

"process_data"

"validate_input"

error

any

Error information when task execution fails. Only set when status is 'failed'. Contains error message, type, and stack trace. Structure: {'message': str, 'type': str, 'traceback': str} Used for debugging and error reporting.

Example:

{
  "message": "Connection timeout after 30s",
  "traceback": "...",
  "type": "ConnectionError"
}

input

any

Input parameters provided to the task executor. Schema varies by task type. Can be dict, list, or primitive types. NULL if task has no input parameters.

Examples:

{
  "recipient": "user@example.com",
  "subject": "Hello"
}

[1, 2, 3, 4, 5]

"simple string input"

output

any

Output data produced by the task executor upon completion. Only set when status is 'completed'. NULL for queued/running/failed states. Available to downstream tasks via {{task_name.output}} syntax.

Examples:

{
  "email_id": "msg_123",
  "sent_at": "2025-01-23T10:30:00Z"
}

{ "errors": 0, "processed_rows": 150 }

Response

Task execution created successfully

API model representing a task execution within a flow.

Task executions track individual task invocations during flow execution. Each task can execute multiple times (retries, loops), identified by task_execution_idx. Contains full execution context including inputs, outputs, errors, and lifecycle metadata.

Resource Hierarchy: Organization → Flow → Flow Execution → Task Execution

flow_execution_id

string<uuid>

required

ID of the parent flow execution containing this task. Establishes the execution hierarchy and determines organization scope. All tasks in a flow execution share the same flow_execution_id.

Example:

"223e4567-e89b-12d3-a456-426614174000"

string<uuid>

required

Unique identifier for this task execution. Auto-generated UUID assigned at creation time. Used for direct resource access via GET /task-executions/{id}.

Example:

"123e4567-e89b-12d3-a456-426614174000"

organization_id

string<uuid>

required

ID of the organization owning this task execution. Inherited from parent flow execution for tenant isolation. Used for Row-Level Security (RLS) filtering and authorization. All task executions are scoped to a single organization.

Example:

"323e4567-e89b-12d3-a456-426614174000"

status

string

required

Current execution state of the task. Valid values: 'queued', 'running', 'completed', 'failed', 'deleted', 'stale'.

Status transitions:

queued → running: Task execution started
running → completed: Task succeeded with output
running → failed: Task encountered error
any → deleted: Task soft-deleted (hidden from list operations)
completed/failed → stale: Task data is outdated

Queued: Task scheduled but not started Running: Task actively executing Completed: Task finished successfully (output field set) Failed: Task encountered error (error field set) Deleted: Soft-deleted, excluded from queries (preserves audit trail) Stale: Previously completed but data is now outdated

Examples:

"queued"

"running"

"completed"

"failed"

"deleted"

"stale"

task_execution_idx

integer

required

Zero-based execution index tracking task attempts. 0 = first execution, 1 = first retry, 2 = second retry, etc. Increments for each retry or loop iteration of the same task. Combines with flow_execution_id and task_name to form unique composite key.

Required range: x >= 0

Examples:

0

1

2

task_name

string

required

Name of the task as defined in the flow definition YAML. Case-sensitive identifier matching flow configuration. Used to reference task in flow logic and dependency graphs.

Required string length: 1 - 200

Examples:

"send_email"

"process_data"

"validate_input"

created_at

string<date-time> | null

ISO 8601 timestamp when task execution was created (UTC). Represents when the task was queued or first recorded in the system. NULL for legacy records created before timestamp tracking.

Example:

"2025-01-23T10:30:00Z"

error

any | null

Error information when task execution fails. Only populated when status is 'failed'; NULL for other states. Contains error message, exception type, and stack trace for debugging.

Typical structure: { "message": "Human-readable error description", "type": "Exception class name", "traceback": "Full Python stack trace" }

Used for debugging, monitoring, and error reporting workflows.

Example:

{
  "message": "Connection timeout after 30 seconds",
  "traceback": "Traceback (most recent call last):\n  ...",
  "type": "ConnectionError"
}

input

any

Input parameters provided to the task executor. Schema varies by task type; can be object, array, or primitive. NULL if task accepts no input parameters. Resolved from flow definition and upstream task outputs.

Examples:

{
  "recipient": "user@example.com",
  "subject": "Hello"
}

[1, 2, 3, 4, 5]

"simple string input"

modified_by

string

default:system

Identifier of the actor who last modified this task execution. Tracks manual interventions vs automated updates for auditing. Defaults to 'system' for worker-initiated changes.

Values:

'system': System-automated changes (workers, background jobs)
User ID: UUID string of the user who made the change (e.g., '123e4567-e89b-12d3-a456-426614174000')
Integration type: For service accounts/integrations (e.g., 'integration', 'service-account')

Examples:

"system"

"123e4567-e89b-12d3-a456-426614174000"

"integration"

output

any | null

Output data produced by the task executor upon successful completion. Only populated when status is 'completed'; NULL for other states. Available to downstream tasks via {{task_name.output}} syntax. Structure defined by task executor implementation. Used for task chaining and flow data propagation.

Example:

{
  "email_id": "msg_123",
  "sent_at": "2025-01-23T10:30:00Z"
}

updated_at

string<date-time> | null

ISO 8601 timestamp of last update to this task execution (UTC). Changes whenever status, output, or error fields are modified. Used for change tracking and optimistic locking. NULL for records never updated since creation.

Example:

"2025-01-23T10:35:00Z"

Update task execution and optionally re-execute flow Retrieve a specific task execution