Workflows

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

Workflows save the instructions and output format for a job you repeat. A workflow can define a prompt, typed variables, research strategy, deliverables and recommended tools and mode. Each run is a normal DeepResearch task. For example, save a company-profile workflow once, then supply a different company for each run. Use the Workflows quickstart to run an existing workflow. This page covers previewing, overrides and creating your own versioned workflows. Valyu-curated workflows are read-only. Workflows you create belong to your organization. For examples of jobs to build, see Financial services and Sciences.

How a workflow runs

Running a workflow is a DeepResearch task. You pass workflow_id and workflow_params to POST /v1/deepresearch/tasks; the workflow 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 workflow without running (free), 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 (pnpm add 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 supported setting such as mode or deliverables for a single run, supply it in the request body. tools are merged with the workflow’s tools instead, so a tool the workflow 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. Valyu-curated workflows cover 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. The Workflows quickstart includes SDK and REST examples for listing and inspecting workflows. 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 workflow 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 workflow against your params without running it (nothing is charged) to confirm the final prompt, deliverables, and mode.

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

const preview = await valyu.workflows.preview("ib-company-profile", {
  workflowParams: { company: "NVIDIA (NVDA)" },
});
console.log(preview.resolved.input);

curl -X POST "https://api.valyu.ai/v1/workflows/ib-company-profile/preview" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "workflow_params": { "company": "NVIDIA (NVDA)" } }'

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.

Pin a workflow_version for production runs so later edits to the workflow do not change the version used for your run. Omit it to always use the current version.

Per-run overrides

A workflow 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 workflow’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 workflow’s tools, so a tool the workflow enables stays enabled unless you explicitly set that tool to false.

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 workflow'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"},
)

const task = await valyu.deepresearch.create({
  workflowId: "ib-strategic-alternatives",
  workflowParams: { company: "Peloton (PTON)" },
  // Chain earlier runs in as context (max 3)
  previousReports: [profileTaskId, compsTaskId],
  // Override the workflow's deliverables for this run only
  deliverables: ["docx", "pptx"],
  // Pause after the plan is drafted so a human can approve it
  hitl: { planReview: true },
  // Constrain the research window
  search: { startDate: "2019-01-01" },
});

curl -X POST "https://api.valyu.ai/v1/deepresearch/tasks" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "workflow_id": "ib-strategic-alternatives",
    "workflow_params": { "company": "Peloton (PTON)" },
    "previous_reports": ["<profile_task_id>", "<comps_task_id>"],
    "deliverables": ["docx", "pptx"],
    "hitl": { "plan_review": true },
    "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 workflow defaults instead. The REST API has always accepted them.

Workflow 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 workflow must map to a variable declared in variables, or the API returns unreferenced_template_vars. Declared variables that aren’t referenced in the workflow 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, browser use, 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, standard, heavy or max). Override either in the run request body. See research modes and pricing for budgets and charges.

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 retain a stable workflow configuration. 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 workflow 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.

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")

const created = await 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)
await 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.",
  },
  setCurrent: true,
});

await valyu.workflows.versions("quarterly-company-profile");
await 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 }.

Next steps

Workflows quickstart

Discover a workflow and start your first run.

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.

Start here

APIs

Finance workflows

Sciences workflows

Build and connect

Comparisons

How a workflow runs

Discover and inspect

Preview (optional)

Run a workflow

Per-run overrides

Workflow reference

Create and version your own

Next steps

Workflows quickstart

DeepResearch guide

List workflows API

Run via tasks API

​How a workflow runs

​Discover and inspect

​Preview (optional)

​Run a workflow

​Per-run overrides

​Workflow reference

​Create and version your own

​Next steps

Workflows quickstart

DeepResearch guide

List workflows API

Run via tasks API

How a workflow runs

Discover and inspect

Preview (optional)

Run a workflow

Per-run overrides

Workflow reference

Create and version your own

Next steps