--- title: "Execute Workflow" method: POST path: "/v1/workflow/execute" tags: ["Workflows"] --- # Execute Workflow `POST /v1/workflow/execute` Execute a workflow with an inline template definition or a stored template ID. Returns a streaming response via Server-Sent Events. ## Request body - WorkflowExecuteRequest — Request to execute a workflow. - `execution_id` string, nullable — Provide a previous execution ID to resume a workflow conversation. - `input` object, nullable — Input values for template placeholders. - `model_name` 'base' | 'pro' — Available models for execution. - `template` union, required — Template ID (string) or inline template definition (object). - string - CreateWorkflowTemplate — Inline workflow template definition. - `content_filter` ContentFilter — Composable content filter using logical operators. - `all_of` union[] — Match content satisfying all of these filters. - union - DocumentIdFilter — Filter by specific document identifiers. - … - SourceFilter — Filter by content source identifiers. - … - `any_of` union[] — Match content satisfying at least one of these filters. - union - DocumentIdFilter — Filter by specific document identifiers. - … - SourceFilter — Filter by content source identifiers. - … - `none_of` union[] — Exclude content matching any of these filters. - union - DocumentIdFilter — Filter by specific document identifiers. - … - SourceFilter — Filter by content source identifiers. - … - `description` string, nullable — Brief description of what this template does. - `expected_input` object, nullable — Input placeholders the template expects, keyed by placeholder name. - `name` string, required — Template display name. - `prompt` string, required — The research prompt with optional placeholders. - `ranking_parameters` RankingParameters — Parameters that influence how search results are ranked. - `freshness_boost` integer, nullable — Prioritize more recent content (1-10). - `source_boost` integer, nullable — Boost results from high-quality, authoritative sources (1-10). - `research_plan` PlanInput — A structured research plan with ordered steps. - `steps` Step[] — Ordered list of research steps. - `description` string, required — What this step will investigate or produce. - `status` 'NOT_STARTED' | 'IN_PROGRESS' | 'COMPLETED' | 'SKIPPED' | 'FAILED' — Status of a research plan step. - `title` string, required — Short title summarizing the research objective. - `expected_output` string, nullable — Optional guidance for the final answer's tone, structure, and format. - `time_range` union — Time range filter for the workflow. Omit for unconstrained. - 'last_24_hours' | 'last_7_days' | 'last_30_days' | 'last_60_days' | 'last_90_days' | 'last_180_days' | 'last_365_days' — Predefined rolling time windows for filtering data. - DateRange — Absolute time range for filtering content. - `end` string, date-time, nullable — End of the time range (ISO 8601 UTC, e.g. '2024-12-31T23:59:59Z'). - `start` string, date-time, nullable — Start of the time range (ISO 8601 UTC, e.g. '2024-01-01T00:00:00Z'). ## Response `200` Streaming SSE response with workflow results. - WorkflowStreamingDelta — A single streaming event from a workflow execution. - `delta` union, required — The streamed message event. - ThinkingMessage — The agent's intermediate reasoning while researching. - `content` string, required — The agent's reasoning text. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'THINKING' - ActionMessage — Notification that the agent is invoking a tool. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `tool_arguments` object, nullable — Arguments passed to the tool. - `tool_name` string, required — Name of the tool being called. - `type` 'ACTION' - AnswerMessage — A chunk of the agent's final answer text. - `content` string, required — Answer text content. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'ANSWER' - CompleteMessage — Signals that the agent has finished processing the request. - `checkpoint_id` string, nullable — Checkpoint for continuing this conversation. - `consumption` TokenTierConsumption[], required — Resource usage breakdown for this request. - `cached_tokens` integer — Number of tokens served from cache. - `input_tokens` integer, required — Number of input tokens consumed. - `output_tokens` integer, required — Number of output tokens generated. - `type` 'base' | 'pro', required — Model tier this consumption applies to. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'COMPLETE' - ErrorMessage — An unrecoverable error during processing. - `error` string, required — Error description. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'ERROR' - AuditMessage — Detailed trace data from tool executions. - `audit_traces` union[], required — Audit traces from tool executions. - union - SearchAuditV1 — Audit trace for a search operation. - `audit_type` 'SearchAuditV1' - `query` TraceQuery, required — A search query executed by the agent. - … - `results` union[], required — Search results grouped by source type. - … - `tool_id` string, required — Identifier of the tool that produced this trace. - MarkdownAuditV1 — Audit trace for generated markdown content. - `audit_type` 'MarkdownAuditV1' - `content` string, required — The generated markdown content. - `title` string, required — Title of the generated content. - `tool_id` string, required — Identifier of the tool that produced this trace. - StructuredReportAuditV1 — Audit trace for a structured data report. - `audit_type` 'StructuredReportAuditV1' - `structured_report` StructuredReport, required — A structured report with multiple sections. - … - `tool_id` string, required — Identifier of the tool that produced this trace. - SubAgentStartedAuditV1 — Audit trace emitted when a sub-agent begins its research task. - `agent_role` string, required — Role name of the sub-agent. - `audit_type` 'SubAgentStartedAuditV1' - `plan` PlanOutput — A structured research plan with ordered steps. - … - `plan_title` string, required — Title of the sub-agent's research plan. - `step_index` integer, required — Index of the plan step this sub-agent is executing. - `tool_id` string, required — Identifier of the tool that produced this trace. - SubAgentCompletedAuditV1 — Audit trace emitted when a sub-agent finishes its research task. - `audit_type` 'SubAgentCompletedAuditV1' - `consumption` TokenTierConsumption[] — Resource usage for this sub-agent's execution. - … - `success` boolean, required — Whether the sub-agent completed successfully. - `tool_id` string, required — Identifier of the tool that produced this trace. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'AUDIT' - GroundingMessage — Citations linking answer text spans to their sources. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `references` GroundingReference[], required — Source references for spans of the answer text. - `audit_id` string, required — Identifier linking this reference to its audit trace. - `end` integer, required — End character offset (exclusive) in the answer text. - `source` union — The referenced source document or web result. - ExternalResult — A result from an external web source. - `action` ExternalSourceAction, required — Metadata for an external web source. - … - `description` string, nullable — Brief summary. - `hd` string, required — Headline or title. - `id` string, required — Unique identifier for this result. - `text` string, required — Content text excerpt. - `ts` string, nullable — Publication timestamp. - `type` 'EXTERNAL' — Source type identifier. - BigdataDocument — A document from the Bigdata content platform. - `chunks` BigdataChunk[], nullable — Text chunks with matched content. - … - `content_type` string, nullable — Content type classification. - `document_scope` string, nullable — Scope or section of the document. - `document_type` string, nullable — Document type classification. - `hd` string, required — Document headline or title. - `id` string, required — Unique document identifier. - `language` string, required — Document language code. - `rp_provider_id` string, nullable — Provider identifier. - `source_rank` integer, required — Ranking weight of the source. - `src_key` string, required — Source key identifier. - `src_name` string, required — Source display name. - `ts` string, required — Publication timestamp. - `type` 'BIGDATA' — Source type identifier. - `url` string, nullable — URL of the original document. - `start` integer, required — Start character offset in the answer text. - `tool_name` string, required — Name of the tool that produced this reference. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'GROUNDING' - ToolErrorMessage — A recoverable error from a specific tool. - `error` string, required — Error description. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `tool_name` string, nullable — Name of the tool that encountered the error. - `type` 'TOOL_ERROR' - PlanningMessage — Updates to the agent's research plan. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `plan` PlanOutput, required — A structured research plan with ordered steps. - `steps` Step[] — Ordered list of research steps. - `description` string, required — What this step will investigate or produce. - `status` 'NOT_STARTED' | 'IN_PROGRESS' | 'COMPLETED' | 'SKIPPED' | 'FAILED' — Status of a research plan step. - `title` string, required — Short title summarizing the research objective. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'PLANNING' - LlmRetryMessage — Notification that the agent is retrying a failed operation. - `message` string, required — Human-readable retry status. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'LLM_RETRY' - StructuredOutputMessage — Structured data extracted from the research results. - `content` union, required — Extracted structured data matching the requested schema. - object - unknown[] - unknown - `json_schema` object, required — The JSON Schema used to produce this output. - `message_id` string, nullable — Groups related message chunks that belong to the same logical unit. - `role` string — Message source: 'assistant' for the main agent, or a sub-agent role name. - `type` 'STRUCTURED_OUTPUT' - `execution_id` string, required — Workflow conversation identifier. Use this to resume the conversation. - `request_id` string, required — Unique identifier for this request. ## Other responses - `422` — Validation Error --- [API](https://skmtc.dev/bigdata/apis/bigdata-structured-data-api.md) · [All operations](https://skmtc.dev/bigdata/apis/bigdata-structured-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bigdata/bigdata-structured-data-api/revisions/18082de268c4/schema)