> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bigdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Workflows API
> Build reproducible, templated research workflows for automated analysis
The **Workflows API** enables templated, reproducible research designed for automation. Unlike the conversational Research Agent, Workflows uses parameterized templates that produce consistent outputs across executions.
## Workflows vs Research Agent
| Feature | Research Agent | Workflows API |
| --------------------- | ------------------------------- | --------------------------------- |
| **Interaction style** | Ad-hoc natural language queries | Templated, reproducible research |
| **Execution** | Single execution | Reusable templates |
| **State management** | Conversational (chatId) | Parameterized (template + inputs) |
| **Best for** | Exploration and discovery | Automation and production |
| **Research plan** | Dynamic, agent-determined | Optional predefined steps |
## Core Concepts
### Templates
Templates are reusable research specifications that define:
* **Prompt**: The research question with Jinja2 placeholders (e.g., `{{ company_id }}`)
* **Expected inputs**: Typed parameters the template requires
* **Content filters**: Optional restrictions on which sources to search
* **Research plan**: Optional predefined steps for structured execution
* **Expected output**: Optional report template describing the final answer's structure, tone, and format
### Research Plan Behavior
The Workflows API behavior is controlled by the presence of a `research_plan`:
* **Without a plan**: The agent dynamically determines research steps based on your prompt.
* **With a plan**: The agent follows your predefined steps for structured, predictable output.
### Input Types
Templates support two input types:
* `rp_entity_id`: A Bigdata entity ID (e.g., company identifier like `D8442A`)
* `string`: Free-form text input
## Quick Links
Get started with your first workflow execution
Submit a run that outlives your connection, then read, watch, or cancel it
Learn how to build effective templates
Learn how research plans affect execution
Discover and clone shared templates
## Running a workflow: synchronous or asynchronous
A workflow can stream its result on the connection that started it, or run
independently of that connection.
* **`POST /v1/workflow/execute`** streams the whole run back on the same HTTP
response. Closing the connection cancels the run.
* **`POST /v1/workflow/execute/async`** returns an `execution_id` immediately and
the run continues on its own. Its result is always stored, you can attach to its
event stream at any point, and disconnecting never stops it.
Use the asynchronous endpoint for production integrations. See
[Running a workflow](/how-to-guides/agents/workflows/running-a-workflow).
## API Endpoints
The Workflows API provides the following endpoints:
| Endpoint | Method | Description |
| -------------------------------------------------- | ------ | --------------------------------------------------------------- |
| `/v1/workflow/execute` | POST | Execute a workflow and stream the result on the same connection |
| `/v1/workflow/execute/async` | POST | Submit a workflow that runs independently of your connection |
| `/v1/workflow/execute/async/{execution_id}/stream` | GET | Attach to a submitted run and receive its events live |
| `/v1/workflow/execute/async/{execution_id}/cancel` | POST | Stop a running workflow |
| `/v1/workflow/executions` | GET | List your stored runs |
| `/v1/workflow/executions/{execution_id}` | GET | Retrieve a stored run with its full result |
| `/v1/workflow/executions/{execution_id}` | DELETE | Delete a stored run |
| `/v1/workflow/templates` | GET | List your templates |
| `/v1/workflow/templates` | POST | Create a new template |
| `/v1/workflow/templates/{id}` | GET | Get a specific template |
| `/v1/workflow/templates/{id}` | PUT | Update a template |
| `/v1/workflow/templates/{id}` | DELETE | Delete a template |
| `/v1/workflow/templates/community` | GET | Browse community templates |
| `/v1/workflow/templates/{id}/clone` | POST | Clone a template to your account |
## Available Models
Select the model that best fits your use case:
| Model | Description |
| ------ | ----------------------------------- |
| `base` | Default model, balanced performance |
| `pro` | Enhanced reasoning capabilities |
## Time Range Options
Control the time range of research data:
**Rolling time ranges:**
* `last_24_hours`
* `last_7_days`
* `last_30_days`
* `last_60_days`
* `last_90_days`
* `last_180_days`
* `last_365_days`
**Custom date range:**
```json theme={null}
{
"start": "2024-01-01T00:00:00Z",
"end": "2024-12-31T23:59:59Z"
}
```
## Streaming Response
The Workflows API returns responses via Server-Sent Events (SSE). Each event
wraps a typed payload in a `delta` field. The most common message types:
| Type | Description |
| ----------- | -------------------------------------------- |
| `THINKING` | Agent's reasoning process |
| `PLANNING` | Research plan with steps |
| `ACTION` | Tool being called |
| `ANSWER` | Final response content |
| `GROUNDING` | Source references |
| `AUDIT` | Search results and traces |
| `COMPLETE` | Execution finished with resource consumption |
| `ERROR` | Error occurred |
This list is abbreviated. For every public message type -- including `LLM_RETRY`,
`TOOL_ERROR`, and `STRUCTURED_OUTPUT` -- their field schemas, when each fires, and
a copy-paste Python handler, see
[Streaming responses](/how-to-guides/agents/concepts/streaming-responses).