Retrieve a specific flow execution

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

import requests

url = "https://flows.super.ai/api/flow-executions/{flow_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/flow-executions/{flow_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/flow-executions/{flow_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/flow-executions/{flow_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/flow-executions/{flow_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/flow-executions/{flow_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

{
  "created_at": "2023-11-07T05:31:56Z",
  "flow_id": "550e8400-e29b-41d4-a716-446655440000",
  "flow_version": 3,
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "input": {
    "file_key": "documents/abc123.pdf",
    "metadata": {
      "priority": "high"
    }
  },
  "modified_by": "<string>",
  "organization_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "running",
  "updated_at": "2023-11-07T05:31:56Z",
  "run_number": 42
}

flow-executions

Retrieve a specific flow execution

Retrieve detailed information for a specific flow execution.

Fetch a single flow execution by its unique identifier. Returns execution metadata including status, input data, timestamps, and optionally the sequential run number within its flow.

Context:

Retrieves single execution regardless of status (except deleted)
Soft-deleted executions return 404 Not Found
Includes full input data as provided at creation
Run number calculated on-demand if requested
Useful for monitoring execution progress

Run Number Calculation:

When include_run_number=true, calculates sequential position
Based on creation timestamp among all executions for this flow
Includes deleted executions (may have gaps in visible numbers)
Performance: Adds ~10-20ms per request
Useful for displaying “Run #42” in UI

Use Cases:

Check status of long-running execution
Retrieve input data for debugging
Display execution details in UI
Audit execution history with run numbers
Poll for execution completion

Performance Notes:

Without run_number: ~10ms average response time
With run_number: ~25ms average response time
Highly cacheable (status changes infrequently)

Related Endpoints:

GET /flow-executions - List all executions for a flow
POST /flow-executions//execute - Re-execute this execution
GET /task-executions?flow_execution_id= - Get task details
DELETE /flow-executions/ - Delete this execution

GET

api

flow-executions

{flow_execution_id}

Retrieve a specific flow execution

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

import requests

url = "https://flows.super.ai/api/flow-executions/{flow_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/flow-executions/{flow_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/flow-executions/{flow_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/flow-executions/{flow_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/flow-executions/{flow_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/flow-executions/{flow_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

{
  "created_at": "2023-11-07T05:31:56Z",
  "flow_id": "550e8400-e29b-41d4-a716-446655440000",
  "flow_version": 3,
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "input": {
    "file_key": "documents/abc123.pdf",
    "metadata": {
      "priority": "high"
    }
  },
  "modified_by": "<string>",
  "organization_id": "660e8400-e29b-41d4-a716-446655440001",
  "status": "running",
  "updated_at": "2023-11-07T05:31:56Z",
  "run_number": 42
}

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

flow_execution_id

string<uuid>

required

UUID of the flow execution to retrieve. Must exist and not be soft-deleted.

Query Parameters

include_run_number

boolean

default:false

Calculate and include sequential run number. Adds ~10-20ms overhead. Recommended for UI display only.

Response

Flow execution successfully retrieved

Flow execution response with optional sequential run number.

Extends FlowExecutionResponse to include an optional run_number field that indicates the sequential position of this execution among all executions for the same flow (including deleted ones).

created_at

string<date-time>

required

flow_id

string<uuid>

required

UUID of the flow definition being executed. References the parent flow that defines the workflow structure.

Example:

"550e8400-e29b-41d4-a716-446655440000"

flow_version

integer

required

Version number of the flow definition used for this execution. Execution continues on the same version even if flow is updated. Ensures consistency throughout execution lifecycle.

Required range: x >= 1

Example:

3

string<uuid>

required

input

Input · object

required

Input data provided when execution was created. Schema is defined by the flow definition. Commonly includes: file_key, document_url, or custom parameters. Structure varies by flow type.

Example:

{
  "file_key": "documents/abc123.pdf",
  "metadata": { "priority": "high" }
}

modified_by

string

required

organization_id

string<uuid>

required

UUID of the organization that owns this execution. Used for access control and data isolation. All executions are scoped to an organization.

Example:

"660e8400-e29b-41d4-a716-446655440001"

status

string

required

Current execution status. Possible values: 'queued', 'running', 'in_progress', 'completed', 'failed', 'deleted', 'stale'. Status transitions: queued → running → in_progress → completed/failed. Use 'completed' to indicate success, 'failed' for errors.

Example:

"running"

updated_at

string<date-time>

required

run_number

integer | null

Sequential run number for this execution within its flow. Starts at 1 for the first execution and increments by creation time. Includes deleted executions in count, so visible numbers may have gaps. Only populated when include_run_number=true query parameter is set. Null when not requested to avoid performance overhead.

Required range: x >= 1

Example:

42

Create and start a flow execution Soft delete a flow execution