Skip to main content
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.10.0) and TypeScript (npm install valyu-js, valyu-js >= 2.8.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 - the body wins over the template for mode, deliverables, and tools.

​
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. 
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.

​
Preview (optional)

Resolve the template against your params without running it (no credits spent) to confirm the final prompt, deliverables, and mode. 
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. 
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.

​
Template reference

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).
TypeUse for
textShort single-line values (ticker, company name)
textareaLonger free-form context or instructions
numberNumeric inputs (year, headcount, target multiple)
dateISO YYYY-MM-DD dates
enumA fixed set of choices defined in validation.enum
Placeholders use {key} syntax. Every placeholder must map to a declared variable and every declared variable must be referenced, or the API returns unreferenced_template_vars.
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.
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.
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"
]
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.
LimitValue
Text field size64 KB per field
Variables per workflow≤ 50
Deliverables per workflow≤ 20
Tags per workflow≤ 20
Org workflow quota100 (default)
CodeMeaning
workflow_not_foundNo workflow matches the slug
cannot_edit_valyu_workflow / cannot_delete_valyu_workflowValyu-curated workflows are read-only
workflow_quota_exceededOrg hit its workflow quota
workflow_and_freeform_mutually_exclusiveBoth workflow_id and freeform fields were sent
unreferenced_template_varsA declared variable is unused (or vice versa)
changelog_requiredA version was published without a changelog
invalid_output_formatsMore than one schema, a schema mixed with markdown/pdf, or toon without a schema
field_too_longA text field exceeded 64 KB
too_many_variables / too_many_deliverablesCount 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. 
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.

Open 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.