curl --request GET \
--url https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_id} \
--header 'domain: <domain>'import requests
url = "https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_id}"
headers = {"domain": "<domain>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {domain: '<domain>'}};
fetch('https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_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://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_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 => [
"domain: <domain>"
],
]);
$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://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("domain", "<domain>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_id}")
.header("domain", "<domain>")
.asString();require 'uri'
require 'net/http'
url = URI("https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["domain"] = '<domain>'
response = http.request(request)
puts response.read_body{
"id": "9349773c-27fe-4d4f-a093-a5793dff8702",
"brand_id": "691df5949676c8e0b1d7b6b3",
"type": "OPTIMIZE",
"origin": "API",
"mode": "prod",
"workflow_type": null,
"status": "REVIEW_PENDING",
"current_step": "TAXONOMY_MAP",
"current_hitl_gate": "TAXONOMY_REVIEW",
"name": "Spring 2026 catalog enrichment",
"tags": [],
"started_at": "2026-05-15T10:35:12Z",
"completed_at": null,
"last_error": null,
"retry_count": 0,
"workflow_metadata": null,
"progress": {
"current_phase": "taxonomy",
"current_step": "TAXONOMY_MAP",
"current_gate": "TAXONOMY_REVIEW",
"phases": {
"validation": {
"status": "COMPLETED"
},
"taxonomy": {
"status": "REVIEW_PENDING"
},
"enrichment": {
"status": "NOT_STARTED"
},
"publish": {
"status": "NOT_STARTED"
}
}
},
"review_summary": {
"total_categories": 12,
"decided_categories": 3,
"pending_categories": 9,
"rerunning_categories": 0,
"rejected_categories": 0,
"ready_for_publish_categories": 0,
"published_categories": 0
},
"reviewer_summary": [
{
"reviewer_user_id": "user_xyz",
"name": "Alex Reviewer",
"email": "alex@acme.com",
"first_name": "Alex",
"last_name": "Reviewer",
"category_ids": [
"cat_apparel",
"cat_outerwear"
],
"categories_at_open_gate": 2,
"current_gate": "TAXONOMY_REVIEW"
}
],
"created_by": {
"id": "user_xyz",
"type": "user",
"name": "Integration Bot",
"email": "integration@acme.com"
},
"updated_by": {
"id": "user_xyz",
"type": "user",
"name": "Integration Bot",
"email": "integration@acme.com"
},
"created_at": "2026-05-15T10:35:00Z",
"updated_at": "2026-05-15T10:42:08Z"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}Retrieve optimization workflow status
Returns the current state of an optimization workflow, including status, current_step, current_hitl_gate (when the workflow is paused at a review gate), per-phase progress, and aggregated review and reviewer summaries.
Poll this endpoint to track a workflow through its lifecycle. A 401 response indicates that the access token has expired; re-authenticate and retry the request.
The status value progresses through PENDING, then RUNNING or IN_PROGRESS, then REVIEW_PENDING when paused at a human-in-the-loop gate, and ultimately COMPLETED. FAILED and CANCELLED are terminal alternatives.
When status is REVIEW_PENDING, the value of current_hitl_gate identifies the active gate. Gate approval is performed in the CommerceOS web application — direct the assigned reviewer to CommerceOS to evaluate and approve the gate. Once the reviewer acts, the workflow resumes and subsequent polls reflect the new state.
curl --request GET \
--url https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_id} \
--header 'domain: <domain>'import requests
url = "https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_id}"
headers = {"domain": "<domain>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {domain: '<domain>'}};
fetch('https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_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://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_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 => [
"domain: <domain>"
],
]);
$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://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("domain", "<domain>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_id}")
.header("domain", "<domain>")
.asString();require 'uri'
require 'net/http'
url = URI("https://commerceos.aiagents.fabric.inc/api/v2/optimize/workflows/{workflow_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["domain"] = '<domain>'
response = http.request(request)
puts response.read_body{
"id": "9349773c-27fe-4d4f-a093-a5793dff8702",
"brand_id": "691df5949676c8e0b1d7b6b3",
"type": "OPTIMIZE",
"origin": "API",
"mode": "prod",
"workflow_type": null,
"status": "REVIEW_PENDING",
"current_step": "TAXONOMY_MAP",
"current_hitl_gate": "TAXONOMY_REVIEW",
"name": "Spring 2026 catalog enrichment",
"tags": [],
"started_at": "2026-05-15T10:35:12Z",
"completed_at": null,
"last_error": null,
"retry_count": 0,
"workflow_metadata": null,
"progress": {
"current_phase": "taxonomy",
"current_step": "TAXONOMY_MAP",
"current_gate": "TAXONOMY_REVIEW",
"phases": {
"validation": {
"status": "COMPLETED"
},
"taxonomy": {
"status": "REVIEW_PENDING"
},
"enrichment": {
"status": "NOT_STARTED"
},
"publish": {
"status": "NOT_STARTED"
}
}
},
"review_summary": {
"total_categories": 12,
"decided_categories": 3,
"pending_categories": 9,
"rerunning_categories": 0,
"rejected_categories": 0,
"ready_for_publish_categories": 0,
"published_categories": 0
},
"reviewer_summary": [
{
"reviewer_user_id": "user_xyz",
"name": "Alex Reviewer",
"email": "alex@acme.com",
"first_name": "Alex",
"last_name": "Reviewer",
"category_ids": [
"cat_apparel",
"cat_outerwear"
],
"categories_at_open_gate": 2,
"current_gate": "TAXONOMY_REVIEW"
}
],
"created_by": {
"id": "user_xyz",
"type": "user",
"name": "Integration Bot",
"email": "integration@acme.com"
},
"updated_by": {
"id": "user_xyz",
"type": "user",
"name": "Integration Bot",
"email": "integration@acme.com"
},
"created_at": "2026-05-15T10:35:00Z",
"updated_at": "2026-05-15T10:42:08Z"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}{
"errors": "<array>",
"message": "Bad request",
"type": "CLIENT_ERROR"
}Headers
The brand domain name (for example, vessel.com or containerstore.com) used to scope the request to a specific brand's data and configuration. The authenticated principal must be authorized for the specified brand.
"vessel.com"
Path Parameters
Workflow identifier returned by POST /v2/optimize/workflows.
"9349773c-27fe-4d4f-a093-a5793dff8702"
Response
Workflow state
Workflow state envelope returned by POST /v2/optimize/workflows and GET /v2/optimize/workflows/{workflow_id}. The status value progresses through PENDING, then RUNNING or IN_PROGRESS, then REVIEW_PENDING, and ultimately COMPLETED. FAILED and CANCELLED are terminal alternatives.
Workflow identifier. Use this value to poll for status and to construct deep links into the Commerce OS UI.
"9349773c-27fe-4d4f-a093-a5793dff8702"
"691df5949676c8e0b1d7b6b3"
Current lifecycle state.
PENDING, RUNNING, IN_PROGRESS, REVIEW_PENDING, COMPLETED, FAILED, CANCELLED "REVIEW_PENDING"
"2026-05-15T10:35:00Z"
"2026-05-15T10:42:08Z"
"OPTIMIZE"
COMMERCEOS, API "API"
The publish target the run's enriched catalog is published to. Null when the run uses the brand's existing configured destination.
dev, test, prod "prod"
null
Current step in the workflow. One of VALIDATE / VALIDATION, TAXONOMY_MAP / TAXONOMY, ENRICH / ENRICHMENT, or PUBLISH / PUBLISHED.
"TAXONOMY_MAP"
Active human-in-the-loop review gate. Populated when status is REVIEW_PENDING. One of VALIDATION_REVIEW, TAXONOMY_REVIEW, SAMPLE_REVIEW, ENRICHMENT_SAMPLE_REVIEW, FULL_ENRICHMENT_REVIEW, ENRICHMENT_FULL_REVIEW, or PUBLISH_APPROVAL.
"TAXONOMY_REVIEW"
"Spring 2026 catalog enrichment"
[]
"2026-05-15T10:35:12Z"
null
Most recent error message. Populated when status is FAILED.
null
0
Phase-keyed progress for the workflow, computed at read time. The phases object contains one key per phase (validation, taxonomy, enrichment, publish), each carrying a phase-specific structure.
Show child attributes
Show child attributes
Aggregate counts across categories at the current enrichment-side review gate. This summary supports diagnosing which categories are blocking progression. For non-enrichment gates (taxonomy, validation, publish) the counts are typically zero, because those gates are workflow-level rather than per-category.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Resolved reference for the created_by and updated_by audit fields. A type of unknown is returned when the referenced identifier can no longer be resolved (for example, when a user has been hard-deleted).
Show child attributes
Show child attributes
Resolved reference for the created_by and updated_by audit fields. A type of unknown is returned when the referenced identifier can no longer be resolved (for example, when a user has been hard-deleted).
Show child attributes
Show child attributes
Was this page helpful?