List active task tags for a flow execution

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

import requests

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

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

	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-tags")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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",
    "tag": "<string>",
    "tag_type": "<string>",
    "task_name": "<string>",
    "created_at": "2025-01-24T10:30:00Z",
    "modified_by": "123e4567-e89b-12d3-a456-426614174000",
    "status": "active",
    "tag_metadata": {
      "notes": "Looks good",
      "reviewer": "user@example.com"
    },
    "updated_at": "2025-01-24T10:35:00Z"
  }
]

task-tags

List active task tags for a flow execution

List all active tags for task executions within a flow execution.

Overview Retrieve tags associated with task executions in a specific flow execution. Results can be filtered to a single task or return all tasks’ tags. Only active tags are returned; soft-deleted tags (status=‘deleted’) are excluded.

What are Task Tags? Task tags provide flexible categorization and workflow state for task executions:

Review status: ‘reviewed’, ‘approved’, ‘rejected’
Quality flags: ‘quality_checked’, ‘flagged’, ‘verified’
Custom categories: ‘priority_high’, ‘customer_acme’, ‘requires_attention’ Each tag includes optional metadata for context (reviewer name, notes, etc.)

Filtering Logic Query parameters combine with AND logic:

flow_execution_id (required): Return tags for this flow execution
task_name (optional): Filter to tags for a specific task Without task_name: Returns all tags across all tasks in the flow execution

Common Query Patterns

All tags in flow execution: GET /task-tags?flow_execution_id=
Tags for specific task: GET /task-tags?flow_execution_id=&task_name=send_email
Check if task reviewed: GET /task-tags?flow_execution_id=&task_name=extract_data Filter results where tag=‘reviewed’

Response Format Returns array of FlowTaskTagAPI objects with:

Tag identification: tag, tag_type, task_name
Metadata: tag_metadata (JSON object for custom data)
Lifecycle: created_at, updated_at, modified_by
Status: Always ‘active’ (deleted tags excluded)
Organization context: organization_id for tenant isolation

Tag Types and Usage Common tag_type values:

‘review_status’: Workflow state (‘reviewed’, ‘approved’, ‘rejected’)
‘quality’: Quality assurance (‘quality_checked’, ‘flagged’)
‘priority’: Business priority (‘high’, ‘medium’, ‘low’)
‘custom’: Domain-specific categories

Performance Considerations

Queries scoped by organization_id via RLS (automatic filtering)
Indexes on (flow_execution_id, task_name, status) for fast lookups
Typical response: 5-50 tags per flow execution
Soft-deleted tags excluded at query time (no filtering overhead)

Use Cases

Display task status in UI (show ‘reviewed’ badge)
Filter tasks by approval state (find all ‘approved’ tasks)
Audit workflow progression (who reviewed what, when)
Custom business logic (trigger actions based on tag presence)

Error Scenarios

400 Bad Request: Invalid UUID format for flow_execution_id
403 Forbidden: User lacks permission to access flow execution’s organization
404 Not Found: flow_execution_id doesn’t exist Note: Missing task_name is NOT an error; returns empty array

Related Endpoints

PATCH /task-tags - Add/remove tags
GET /task-executions - List task executions (includes tags via TaskExecutionWithTagsAPI)
GET /flow-executions/ - View parent flow execution

GET

api

task-tags

List active task tags for a flow execution

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

import requests

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

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

	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-tags")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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",
    "tag": "<string>",
    "tag_type": "<string>",
    "task_name": "<string>",
    "created_at": "2025-01-24T10:30:00Z",
    "modified_by": "123e4567-e89b-12d3-a456-426614174000",
    "status": "active",
    "tag_metadata": {
      "notes": "Looks good",
      "reviewer": "user@example.com"
    },
    "updated_at": "2025-01-24T10: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>

required

Unique identifier of the flow execution to query tags from. Required parameter; returns all active tags for this execution. Combine with task_name to filter to a specific task.

Filtering: Queries automatically scoped to user's organization via RLS. Attempting to access another organization's execution returns 404.

Response: All active tags (status='active') for the execution. Soft-deleted tags (status='deleted') are excluded automatically.

task_name

string | null

Optional task name to filter tags by specific task. Case-sensitive; must match task name exactly as defined in flow YAML. Omit to return tags for all tasks in the flow execution.

Filtering behavior:

Specified: Returns only tags for this task_name
Omitted: Returns tags for all tasks in flow execution

Combines with flow_execution_id using AND logic.

Example: task_name='extract_data' returns tags only for that task. Useful for checking task-specific workflow states (is task reviewed?).

Required string length: 1 - 200

Response

List of task tags successfully retrieved

flow_execution_id

string<uuid>

required

ID of the flow execution containing the tagged task. Establishes execution context and organization scope. Tags are scoped to flow executions; same task in different executions has independent tag sets. Used for filtering tags by execution.

Example:

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

string<uuid>

required

Unique identifier for this tag record. Auto-generated UUID assigned at tag creation. Used for direct tag access and references.

Example:

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

organization_id

string<uuid>

required

ID of organization owning this tag. Inherited from parent flow execution for multi-tenant isolation. Used for Row-Level Security (RLS) filtering and authorization. All tags scoped to single organization; cross-org access forbidden. Queries automatically filtered by user's organization_id.

Example:

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

tag

string

required

Tag value identifying the categorization or state. Free-form string for flexible workflow customization. Case-sensitive; same tag with different case creates separate records. Combined with tag_type for organized categorization.

Common patterns:

Workflow: 'reviewed', 'approved', 'rejected', 'pending'
Quality: 'quality_checked', 'flagged', 'verified'
Priority: 'high', 'medium', 'low'
Custom: Domain-specific values

Required string length: 1 - 200

Examples:

"reviewed"

"approved"

"priority_high"

"requires_attention"

tag_type

string

required

Category or classification for the tag value. Groups related tags for filtering and organization in UI/queries. Case-sensitive; use consistent values across organization.

Common types:

'review_status': Workflow states
'quality': Quality assurance flags
'priority': Business priority levels
'approval': Approval workflow states
'custom': Domain-specific categories

Required string length: 1 - 100

Examples:

"review_status"

"quality"

"priority"

"approval"

"custom"

task_name

string

required

Name of the tagged task as defined in flow definition YAML. Case-sensitive identifier matching flow configuration. Tags are attached to task_name within a flow_execution_id. Multiple tags can be attached to the same task.

Required string length: 1 - 200

Examples:

"send_email"

"extract_data"

"validate_document"

created_at

string<date-time> | null

ISO 8601 timestamp when tag was created (UTC). Represents when tag was first added to task execution. NULL for legacy tags created before timestamp tracking. Used for audit trails and chronological sorting.

Example:

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

modified_by

string | null

Identifier of actor who last modified this tag. Tracks who made the last change for auditing purposes.

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')

For deleted tags, indicates who performed soft deletion. NULL for tags never modified since creation. Used for audit trails and accountability.

Example:

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

status

string | null

Tag lifecycle status indicating active or deleted state. Valid values: 'active', 'deleted'.

'active': Tag is visible in queries and included in task tag lists. Default state for newly created tags.

'deleted': Tag soft-deleted; excluded from list queries. Preserves audit trail (who deleted, when) without hard deletion.

Soft-delete rationale: Audit compliance requires deletion history.

Note: Only 'active' tags returned by GET /task-tags endpoint.

Example:

"active"

tag_metadata

any | null

Optional structured metadata providing tag context. Can be object, array, or primitive. NULL if no additional context needed.

Common uses:

Reviewer info: Who tagged and when
Approval details: Approver and notes
Quality metrics: Confidence scores, reasons
Custom data: Domain-specific context

Note: Part of composite unique key with flow_execution_id, task_name, tag, and tag_type. Different metadata creates separate tags.

Example:

{
  "notes": "Looks good",
  "reviewer": "user@example.com"
}

updated_at

string<date-time> | null

ISO 8601 timestamp of last update to this tag (UTC). Changes when tag is modified or soft-deleted. For deleted tags, records deletion timestamp. NULL for tags never updated since creation. Used for change tracking and audit history.

Example:

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

Get task output by ID Add or remove task tags in batch