Retrieve a specific task execution

curl --request GET \
  --url https://flows.super.ai/api/task-executions/{task_execution_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Key: <api-key>'

import requests

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

headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Key': '<api-key>', Authorization: 'Bearer <token>'}
};

fetch('https://flows.super.ai/api/task-executions/{task_execution_id}', 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/{task_execution_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://flows.super.ai/api/task-executions/{task_execution_id}")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'

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

Retrieve a specific task execution

Retrieve a specific task execution by its unique identifier.

Overview Fetches a single task execution record with all details including input parameters, output data, error information, and execution metadata. Used for detailed inspection of task execution results and debugging.

Resource Identification Task executions are uniquely identified by UUID (id field). This is distinct from the composite key (flow_execution_id, task_name, task_execution_idx) used for creation and filtering.

Use Cases

Debugging failed task executions (inspect error field and stack trace)
Retrieving task output for display or downstream processing
Auditing task execution history and modifications
Viewing detailed execution metadata (timestamps, modified_by)

Related Endpoints

GET /task-executions - List task executions with filtering
PUT /task-executions - Update task execution
GET /flow-executions/ - View parent flow execution with all tasks

GET

api

task-executions

{task_execution_id}

Retrieve a specific task execution

curl --request GET \
  --url https://flows.super.ai/api/task-executions/{task_execution_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Key: <api-key>'

import requests

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

headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Key': '<api-key>', Authorization: 'Bearer <token>'}
};

fetch('https://flows.super.ai/api/task-executions/{task_execution_id}', 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/{task_execution_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://flows.super.ai/api/task-executions/{task_execution_id}")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'

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...

Path Parameters

task_execution_id

string<uuid>

required

Unique identifier of the task execution to retrieve. This is the UUID assigned when the task execution was created. Task executions are scoped to organization via RLS; attempting to access another organization's task execution returns 404.

Response

Task execution successfully retrieved

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"

Create a task execution record List all available task executors