Workflows

Templated, versioned DeepResearch for repeatable knowledge work

Workflows are in Beta. The API and schema may change. Endpoints live under /v1/workflows and runs go through the existing DeepResearch task lifecycle.

A Workflow is a templated, versioned DeepResearch starting point. Save a prompt, sources, deliverables, and mode once as a template with typed {variables}, then run it by filling in those variables. It’s the highest-leverage way to use DeepResearch for repeatable knowledge work - earnings previews, diligence reads, market sizings, competitor scans - where the structure stays fixed and only the inputs change.

A workflow bundles a prompt template (with {variable} placeholders), deliverables (xlsx/docx/pptx/pdf/csv), a research strategy and report format, and recommended tools and mode.

Two scopes: Valyu-curated workflows are read-only and available to every org (run, preview, inspect). Your org’s workflows are private templates you create and version, with a default quota of 100 per org.

How a workflow runs

Running a workflow is a DeepResearch task. You pass workflow_id and workflow_params to POST /v1/deepresearch/tasks; the template resolves server-side into a normal run with the same auth, billing, mode pricing, and task lifecycle.

The core endpoints: GET /v1/workflows to discover, GET /v1/workflows/{slug} to inspect variables and deliverables, POST /v1/workflows/{slug}/preview to resolve the template without running (no credits), and POST /v1/deepresearch/tasks to run. Custom org workflows add POST /v1/workflows (create), PATCH /v1/workflows/{slug} (publish a new version), and DELETE /v1/workflows/{slug}.

Both SDKs ship native workflow support: valyu.workflows in Python (pip install valyu, valyu-py >= 2.12.0) and TypeScript (npm install valyu-js, valyu-js >= 2.10.0). Every workflow response is an object with a success boolean and an optional error string.

workflow_id is mutually exclusive with freeform fields (query/input, research_strategy, report_format). Sending both returns 400 workflow_and_freeform_mutually_exclusive. To override a template field for a single run, supply it in the request body - a non-empty value wins over the template’s. tools are merged with the template instead, so a tool the template enables stays enabled unless you explicitly set that tool to false. See Per-run overrides.

Discover and inspect

List workflows, then read a chosen one to see its variables and deliverables. There are 44 Valyu-curated workflows across verticals - investment-banking, private-equity, hedge-funds, consulting, life-sciences, legal-regulatory, sales-intelligence, and supply-chain. Filter the list by scope (valyu | org | all), vertical, q, or tags.

Python

from valyu import Valyu

valyu = Valyu("YOUR_API_KEY")

# List Valyu-curated investment-banking workflows
listing = valyu.workflows.list(scope="valyu", vertical="investment-banking")
for wf in listing.workflows:
    print(wf.slug, wf.title)

# Inspect one - read its variables to build workflow_params
profile = valyu.workflows.get("ib-company-profile")
print(profile.workflow.variables)

The list response is { workflows, total, next_cursor, verticals }. Each row carries slug, version, vertical, tags, title, subtitle, description, popular, recommended_mode, estimated_time, is_valyu, owner_org_id, variables, deliverables, and timestamps. Pass expand=true to also include the template body (prompt, strategy, report_format, tools, output_formats). Ownership is is_valyu / owner_org_id - filter on it with scope.

Variable names differ per workflow - read variables rather than assuming. Workflows in the same vertical often take different keys, and some take a description rather than a name. Within investment-banking, ib-company-profile takes company, ib-comps-analysis takes target, and ib-precedent-transactions takes sector (a sub-sector like "Vertical SaaS for healthcare", not a single company). Passing the wrong key returns 400 validation_failed before any research runs, with an errors array naming both the unknown parameter and the missing one.

Preview (optional)

Resolve the template against your params without running it (no credits spent) to confirm the final prompt, deliverables, and mode.

Python

preview = valyu.workflows.preview(
    "ib-company-profile",
    workflow_params={"company": "NVIDIA (NVDA)"},
)
print(preview.resolved.input)

The response is { workflow: { slug, version }, resolved: { input, research_strategy, report_format, deliverables, mode, tools, output_formats }, estimated_credits }. Pass workflow_version (Python workflow_version, TS workflowVersion) to preview a specific version.

Run a workflow

Runs go through deepresearch.create (POST /v1/deepresearch/tasks) with workflow_id and workflow_params; optionally pin workflow_version. workflow_id is mutually exclusive with query/input/research_strategy/report_format. The create response echoes the resolved workflow: { slug, version }, and the run is a normal DeepResearch task - poll /status and fetch deliverables from the task assets.

Python

task = valyu.deepresearch.create(
    workflow_id="ib-company-profile",
    workflow_params={"company": "NVIDIA (NVDA)"},
)
print(task.deepresearch_id)
print(task.workflow)  # { "slug": "ib-company-profile", "version": 1 }

Pin a workflow_version for production runs so template edits never silently change your output. Omit it to always use the current version.

Per-run overrides

A workflow template supplies the freeform fields - prompt, research strategy, report format - and sensible defaults for mode, deliverables, and tools. Every other deepresearch.create option still applies to a workflow run, and a value in the request body wins over the template’s.

That covers deliverables, search, previous_reports, hitl, urls, files, mcp_servers, brand_collection_id, metadata, webhook_url, and alert_email. tools is the exception: it is merged with the template, so a tool the template enables stays enabled unless you explicitly set that tool to false.

Python

task = valyu.deepresearch.create(
    workflow_id="ib-strategic-alternatives",
    workflow_params={"company": "Peloton (PTON)"},
    # Chain earlier runs in as context (max 3)
    previous_reports=[profile_task_id, comps_task_id],
    # Override the template's deliverables for this run only
    deliverables=["docx", "pptx"],
    # Pause after the plan is drafted so a human can approve it
    hitl={"plan_review": True},
    # Constrain the research window
    search={"start_date": "2019-01-01"},
)

Per-run overrides on a workflow run need valyu-py >= 2.12.0 or valyu-js >= 2.10.0. Earlier SDK versions dropped these fields when workflow_id was set, so the run silently used the template defaults instead. The REST API has always accepted them.

Template reference

Variables

Typed inputs filled in at run time. Each variable has a key, label, type, an optional required flag, and optional placeholder, help, examples, and validation (min_length, max_length, pattern, enum).

Type	Use for
text	Short single-line values (ticker, company name)
textarea	Longer free-form context or instructions
number	Numeric inputs (year, headcount, target multiple)
date	ISO YYYY-MM-DD dates
enum	A fixed set of choices defined in validation.enum

Placeholders use {key} syntax. Every {placeholder} in the template must map to a variable declared in variables, or the API returns unreferenced_template_vars. Declared variables that aren’t referenced in the template are allowed.

Deliverables

Output artifacts, each with a type and description: xlsx (Excel), docx (Word), pptx (PowerPoint), pdf, and csv.

xlsx, docx, and pptx require code_execution enabled in the workflow’s tools. Charts are free; screenshots, code execution, and extra deliverables carry small surcharges. See Pricing.

Tools and mode

A workflow recommends tools (code_execution, screenshots, browser_use, charts - each a boolean) and a recommended_mode (fast ~$0.10, standard ~$0.50, heavy ~$2.50, max ~$15.00). Override either in the run request body.

Output formats

A version body accepts an optional output_formats array. Items are the strings "markdown", "pdf", or "toon", and/or one JSON-schema object for structured output. The rules:

• At most one JSON-schema object.
• A schema object cannot be combined with "markdown" or "pdf".
• "toon" requires a schema object.

An invalid combination returns 400 invalid_output_formats. output_formats is returned on workflow detail, on list with ?expand=true, and in preview under resolved.output_formats. At run time, a task created with workflow_id inherits the workflow’s output_formats when the request doesn’t pass its own; a request-level output_formats always wins.

A structured forecasting workflow that returns an evidence packet might set:

"output_formats": [
  {
    "type": "object",
    "properties": {
      "base_case": { "type": "string" },
      "bull_case": { "type": "string" },
      "bear_case": { "type": "string" },
      "confidence": { "type": "number" }
    }
  },
  "toon"
]

Versioning

Versions are immutable. PATCH /v1/workflows/{slug} (or valyu.workflows.update(...)) publishes a new version by supplying a version body, which must include a changelog (omitting it returns changelog_required). Pin workflow_version to keep older runs reproducible. List history with GET /v1/workflows/{slug}/versions - it returns { slug, versions: [...] } where each row carries version, recommended_mode, estimated_time, changelog, created_at, and is_current. Fetch a workflow resolved at a version with GET /v1/workflows/{slug}?version=N.

Limits and error codes

Limit	Value
Text field size	64 KB per field
Variables per workflow	≤ 50
Deliverables per workflow	≤ 20
Tags per workflow	≤ 20
Org workflow quota	100 (default)

Code	Meaning
workflow_not_found	No workflow matches the slug
cannot_edit_valyu_workflow / cannot_delete_valyu_workflow	Valyu-curated workflows are read-only
workflow_quota_exceeded	Org hit its workflow quota
workflow_and_freeform_mutually_exclusive	Both workflow_id and freeform fields were sent
unreferenced_template_vars	The template references a {placeholder} not declared in variables
changelog_required	A version was published without a changelog
invalid_output_formats	More than one schema, a schema mixed with markdown/pdf, or toon without a schema
field_too_long	A text field exceeded 64 KB
too_many_variables / too_many_deliverables	Count exceeded the limit

Workflow errors come back as { "error": "<code>", "message": "<human text>" }.

Create and version your own

Custom workflows are private to your org (quota 100 by default). Create one with a slug, title, and a version body holding the prompt, strategy, report format, and optional variables, deliverables, tools, and output_formats. Editing Valyu-curated workflows returns 403 cannot_edit_valyu_workflow.

Python

created = valyu.workflows.create(
    slug="quarterly-company-profile",
    title="Quarterly Company Profile",
    vertical="investment-banking",
    version={
        "prompt": "Build a company profile for {company} covering business, financials, and recent developments.",
        "strategy": "Prioritise the latest 10-K/10-Q, IR materials, and reputable news.",
        "report_format": "A one-page profile with overview, key financials, and recent developments.",
        "variables": [
            {"key": "company", "label": "Company", "type": "text", "required": True},
        ],
        "recommended_mode": "standard",
        "output_formats": ["markdown", "pdf"],
    },
)

# Publish a new immutable version (changelog required)
valyu.workflows.update(
    "quarterly-company-profile",
    version={
        "prompt": "Build a company profile for {company}. Add a competitive landscape section.",
        "strategy": "Prioritise the latest 10-K/10-Q, IR materials, and reputable news.",
        "report_format": "A two-page profile with overview, financials, landscape, and developments.",
        "variables": [
            {"key": "company", "label": "Company", "type": "text", "required": True},
        ],
        "changelog": "Added a competitive landscape section.",
    },
    set_current=True,
)

valyu.workflows.versions("quarterly-company-profile")
valyu.workflows.delete("quarterly-company-profile")

A create/update returns the workflow as a flat object (list-row fields plus the resolved version body). Delete returns { slug, deleted_at }.

Wire up a workflow run in your code

Paste into your AI coding assistant to run a Valyu Workflow from your codebase, with full parameter guidance.

CopiedCopy promptOpen in Cursor

Next steps

Workflows quickstart

Run your first workflow in 2 minutes.

DeepResearch guide

The async research engine workflows run on.

List workflows API

Full endpoint reference for /v1/workflows.

Run via tasks API

Pass workflow_id to POST /v1/deepresearch/tasks.