List task executions with filtering

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

import requests

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

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', 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 => "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"

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

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

{
  "task_executions": [
    {
      "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"
      },
      "tags": [
        {
          "tag": "reviewed",
          "tag_metadata": {
            "notes": "Looks good",
            "reviewer": "user@example.com"
          },
          "tag_type": "review_status"
        },
        {
          "tag": "priority_high",
          "tag_type": "custom"
        }
      ],
      "updated_at": "2025-01-23T10:35:00Z"
    }
  ]
}

task-executions

List task executions with filtering

List task executions with optional filtering by flow execution, task name, or execution index.

Overview Retrieve task executions across all flows in your organization. Results can be filtered by parent flow execution, specific task name, or execution index. Returns task executions with their associated tags for categorization and filtering.

Filtering Logic Multiple filters are combined with AND logic:

flow_execution_id AND task_name → All executions of a specific task in a flow
flow_execution_id AND task_execution_idx → All tasks at a specific execution index
All three filters → Exact task execution lookup (equivalent to GET /)

Common Query Patterns

All tasks in a flow execution: ?flow_execution_id=
Specific task across retries: ?flow_execution_id=&task_name=send_email
First execution of all tasks: ?flow_execution_id=&task_execution_idx=0
All task executions (no filters): Returns all executions in organization

Response Format Returns TaskExecutionWithTagsAPI objects containing:

Full task execution details (input, output, error, status)
Associated tags (e.g., reviewed, approved, flagged)
Metadata (created_at, updated_at, modified_by)
Organization context for multi-tenant isolation

Performance Considerations

Queries are scoped to organization_id via RLS policies (automatic filtering)
Add flow_execution_id filter for better query performance on large datasets
Unfiltered queries may return large result sets; pagination planned for future

Tags Task tags provide categorization and workflow state:

Tag types: ‘review_status’, ‘approval’, ‘quality’, ‘custom’
Tags are returned with each task execution for filtering and display
Soft-deleted tags are excluded from results

Related Endpoints

GET /task-executions/ - Get single task execution by ID
GET /task-tags - List all tags for a flow execution
POST /task-executions - Create new task execution

GET

api

task-executions

List task executions with filtering

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

import requests

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

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', 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 => "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"

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

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

{
  "task_executions": [
    {
      "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"
      },
      "tags": [
        {
          "tag": "reviewed",
          "tag_metadata": {
            "notes": "Looks good",
            "reviewer": "user@example.com"
          },
          "tag_type": "review_status"
        },
        {
          "tag": "priority_high",
          "tag_type": "custom"
        }
      ],
      "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...

Query Parameters

flow_execution_id

string<uuid> | null

Filter task executions by parent flow execution ID. Returns only tasks belonging to the specified flow execution. Combines with other filters using AND logic. Omit to search across all flow executions in your organization.

task_name

string | null

Filter task executions by exact task name (case-sensitive). Returns all execution attempts of the named task. Useful for tracking retries or finding specific task types. Must match task name exactly as defined in flow definition YAML.

Required string length: 1 - 200

task_execution_idx

integer | null

Filter task executions by execution index (zero-based). Returns tasks at a specific execution attempt number. Index 0 = first execution, 1 = first retry, 2 = second retry, etc. Useful for comparing initial vs retry executions or finding specific attempts.

Required range: x >= 0

Response

List of task executions successfully retrieved

Response model for listing task executions with filtering.

Returns an array of task executions with their associated tags, filtered by the query parameters provided in the request.

task_executions

TaskExecutionWithTagsAPI · object[]

required

Array of task execution objects matching the filter criteria. Each object includes full task execution details plus associated tags. Empty array if no executions match filters. Results are ordered by created_at descending (newest first).

Show child attributes

Analyze flow definition and extract schemas Update task execution and optionally re-execute flow