API Reference
API Reference

Get Insight Workflow By Id

Get a InsightWorkflow by ID.

GET/api/v1/insights/workflows/{workflow_id}

Authentication

Syllable-API-Keyrequired

Send Syllable-API-Key in the header.

Need a credential? Create or manage an API token in the Syllable Console.

Parameters

Path parameters

workflow_id integer path required

Responses

200Successful Response

application/json

response InsightWorkflowResponse required
20 fields
format_versionenum<integer>optional

Workflow configuration format version

Allowed values [1,2]Default 1
revisioninteger | nulloptional

Expected saved revision when updating a workflow

Exclusive minimum 0
stepsInsightWorkflowStep[] | nulloptional

Ordered steps with stable identities for version 2 workflows

Maximum items 100
Item schema
itemsInsightWorkflowSteprequired
4 fields
step_idstringrequired
Minimum length 1Maximum length 128Pattern ^[A-Za-z0-9_-]+$
insight_tool_idintegerrequired
Exclusive minimum 0
conditionsInsightToolConditionGroup | nulloptional
2 options
matchenum<string>optional
Allowed values ["all","any"]Default all
rulesInsightConditionRule[]optional
Maximum items 50
Item schema
itemsInsightConditionRulerequired
5 fields
rule_idstringrequired
Minimum length 1Maximum length 128Pattern ^[A-Za-z0-9_-]+$
sourceSessionConditionSource | TranscriptConditionSource | ToolConditionSource | InsightConditionSourcerequired
4 options
Option 1SessionConditionSourcerequired
1 field
kindstringrequired
Constant session
Option 2TranscriptConditionSourcerequired
2 fields
kindstringrequired
Constant transcript
step_idstring | nulloptional
Minimum length 1Maximum length 128Pattern ^[A-Za-z0-9_-]+$
Option 3ToolConditionSourcerequired
2 fields
kindstringrequired
Constant tool
tool_namestringrequired
Minimum length 1Maximum length 255Pattern \S
Option 4InsightConditionSourcerequired
3 fields
kindstringrequired
Constant insight
step_idstringrequired
Minimum length 1Maximum length 128Pattern ^[A-Za-z0-9_-]+$
keystringrequired
Minimum length 1Maximum length 512
fieldstring | nulloptional
Maximum length 64
operatorenum<string> | nulloptional
Allowed values ["eq","neq","in","not_in","gte","lte","between","contains","not_contains","is_empty","is_not_empty"]
valueunspecifiedoptional
transcript_source_step_idstring | nulloptional
Minimum length 1Maximum length 128Pattern ^[A-Za-z0-9_-]+$
namestringrequired

Human-readable name of insight workflow

sourcestringrequired

Source of the workflow

descriptionstringrequired

Text description of workflow

insight_tool_idsinteger[]required

Ordered list of IDs of tool configurations to be executed in the workflow

Item schema
itemsintegerrequired
conditionsInsightWorkflowConditionrequired

Conditions (filters) on which a workflow should be triggered.

9 fields
min_durationinteger | nulloptional

Minimum duration of the calls in seconds

max_durationinteger | nulloptional

Maximum duration of the calls in seconds

sample_rateinteger | number | nulloptional

Sample rate as a percentage of calls

3 options
Option 1integeroptional
Option 2numberoptional
Option 3nulloptional
agent_listinteger[] | string[] | nulloptional

List of agents

Item schema
Option 1integer[]optional
Item schema
itemsintegerrequired
Option 2string[]optional
Item schema
itemsstringrequired
Option 3nulloptional
prompt_liststring[] | nulloptional

List of prompts

Item schema
itemsstringrequired
agent_labelsstring[] | nulloptional

Match any of these labels on the session agent in its current state. Combined with other conditions using AND; an empty list applies no filter.

Item schema
itemsstringrequired
prompt_labelsstring[] | nulloptional

Match any of these labels on the prompt version used by the session. Combined with other conditions using AND; an empty list applies no filter.

Item schema
itemsstringrequired
folder_listinteger[] | nulloptional

List of folder IDs

Item schema
itemsintegerrequired
sheet_infoobject | nulloptional

Legacy sheet metadata, retained for viewing retired workflows

1 options
{key}stringoptional
start_datetimestring (date-time) | nulloptional

Target session timestamp the workflow (backfill) should start. An empty value indicates start on activation - live sessions only

end_datetimestring (date-time) | nulloptional

Target session timestamp the workflow (backfill) should end. An empty value indicates no end, i.e., include live sessions until deactivation

idintegerrequired

Internal ID of the insight workflow

insight_toolsInsightToolResponse[]required

Ordered tool configurations, including model lifecycle findings

Item schema
itemsInsightToolResponserequired

Response model for insight tool saves, carrying any non-blocking findings.

11 fields
namestringrequired

Human readable name of insight tool

descriptionstringrequired

Text description of insight tool configuration

versionintegerrequired

Version of insight tool

tool_argumentsunspecifiedrequired

Arguments for calling the insight tool. LLM tools carry their configuration in llm_config. Its optional integer seed is deprecated by Syllable and should be left unset for new configurations. Seed does not guarantee identical responses; support depends on provider, model and endpoint. OpenAI/Azure Responses and Anthropic sampling do not support seed. Configured values (including zero) produce nonblocking llm-seed-deprecated findings at $.tool_arguments.llm_config.seed in configuration responses. Unset/null values do not. Saved values do not establish past request handling.

insight_tool_definition_idintegerrequired

Unique ID for insight tool definition used by this tool configuration

idintegerrequired

Unique ID for insight tool

insight_tool_definitionInsightToolDefinition | nulloptional

Insight Tool Definition

6 options
idintegerrequired

Unique ID for insight tool definition

namestringrequired

Human-readable name of insight tool definition

typestringrequired

Type of insight tool definition

descriptionstringrequired

Text description of insight tool definition

tool_parametersunspecifiedrequired

Parameters for tools that use this definition and their associated types

tool_result_setunspecifiedrequired

Result key/types for insight tool definition

created_atstring (date-time)optional

Timestamp of at which insight tool configuration was created

updated_atstring (date-time)optional

Timestamp at which insight tool configuration was last updated

last_updated_bystringrequired

Email of user who last updated insight tool configuration

validation_issuesValidationIssue[] | nulloptional

Current findings for the saved insight tool. Configured seed (including zero) returns llm-seed-deprecated at $.tool_arguments.llm_config.seed; unset/null seed does not. Known Anthropic seed restrictions are reported separately as llm-seed-unsupported. Seed warnings do not block saves or establish past request handling. Model lifecycle findings are also included; retired models block saves but can appear on reads. Explicitly projected lists can omit findings; their absence does not establish that seed is unset or supported.

Item schema
itemsValidationIssuerequired

A single validation finding with severity, location, and description.

5 fields
idstringrequired

Stable machine-readable identifier (kebab-case)

severityenum<string>optional
Allowed values ["info","warning","error"]Default error
messagestringrequired

Human-readable description

pathstring | nulloptional

JSONPath-style location (e.g. $.context.task.steps[2])

valuestring | nulloptional

The offending value, when it adds clarity

statusstringrequired

Status of the insight workflow

estimateInsightWorkflowEstimaterequired

Estimate of the number of calls that will be processed by the workflow and their cost

6 fields
backfill_countintegerrequired

Number of extant calls that will be processed by the workflow

backfill_durationnumberrequired

Estimated duration of the calls that will be processed by the workflow

estimated_daily_countintegerrequired

Estimated number of calls that will be processed by the workflow daily

estimated_daily_durationnumberrequired

Estimated duration of the calls that will be processed by the workflow daily

estimated_daily_costnumberrequired

Estimated cost of the calls that will be processed by the workflow daily

estimated_backfill_costnumberrequired

Estimated cost of the backfill of the calls that will be processed by the workflow

queue_countinteger | nulloptional

Number of calls in the workflow queue (pending or processing)

failed_countinteger | nulloptional

Number of workflow executions currently in FAILED status

created_atstring (date-time)optional

Timestamp at which the insight workflow was created

updated_atstring (date-time)optional

Timestamp of most recent update to the insight workflow

last_updated_bystringrequired

Email of user who last updated Insight Workflow

last_folder_upload_atstring (date-time) | nulloptional

Timestamp of the most recent file upload to any folder associated with this workflow (null for non-upload workflows or until a file has been uploaded)

Response example
{
  "format_version": 1,
  "revision": "string",
  "steps": "string",
  "name": "string",
  "source": "string",
  "description": "string",
  "insight_tool_ids": [
    0
  ],
  "conditions": {
    "min_duration": "string",
    "max_duration": "string",
    "sample_rate": "string",
    "agent_list": "string",
    "prompt_list": "string",
    "agent_labels": "string",
    "prompt_labels": "string",
    "folder_list": "string",
    "sheet_info": "string"
  },
  "start_datetime": "string",
  "end_datetime": "string",
  "id": 0,
  "insight_tools": [
    {
      "name": "string",
      "description": "string",
      "version": 0,
      "tool_arguments": "string",
      "insight_tool_definition_id": 0,
      "id": 0,
      "insight_tool_definition": "string",
      "created_at": "string",
      "updated_at": "string",
      "last_updated_by": "string",
      "validation_issues": "string"
    }
  ],
  "status": "string",
  "estimate": {
    "backfill_count": 0,
    "backfill_duration": 0,
    "estimated_daily_count": 0,
    "estimated_daily_duration": 0,
    "estimated_daily_cost": 0,
    "estimated_backfill_cost": 0
  },
  "queue_count": "string",
  "failed_count": "string",
  "created_at": "string",
  "updated_at": "string",
  "last_updated_by": "string",
  "last_folder_upload_at": "string"
}
422Validation Error

application/json

response HTTPValidationError required
1 field
detailValidationError[]optional
Item schema
itemsValidationErrorrequired
3 fields
locstring | integer[]required
Item schema
itemsstring | integerrequired
2 options
Option 1stringrequired
Option 2integerrequired
msgstringrequired
typestringrequired
Response example
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}