> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valyu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a workflow

> Run a Valyu Workflow: pick a curated workflow such as a company profile, fill in its inputs and submit it as a DeepResearch task. Python, TypeScript or cURL.

> [!NOTE]
>
> Workflows are in **Beta**. Start with a Valyu-curated workflow, inspect its inputs, and submit a research task. Completion time depends on the selected mode.

This example runs a company-profile workflow for NVIDIA. Workflows save the instructions and deliverables while you supply inputs such as the company name. To write your own research question instead, use the [DeepResearch quickstart](https://docs.valyu.ai/guides/deepresearch-quickstart.md).

**1. Get your API key and install an SDK**

Create a key in the [platform](https://platform.valyu.ai), check your balance and install an SDK.

```bash Python theme={null}
pip install valyu        # valyu-py >= 2.12.0
export VALYU_API_KEY="your-api-key"
```

```bash TypeScript theme={null}
pnpm add valyu-js      # valyu-js >= 2.10.0
export VALYU_API_KEY="your-api-key"
```

**2. List the Valyu workflows**

Browse the available curated workflows and grab a `slug`.

```python Python theme={null}
from valyu import Valyu

valyu = Valyu()  # reads VALYU_API_KEY
listing = valyu.workflows.list(scope="valyu")
for wf in listing.workflows:
    print(wf.slug, wf.title, wf.vertical)
```

```typescript TypeScript theme={null}
import { Valyu } from "valyu-js";

const valyu = new Valyu(process.env.VALYU_API_KEY!);
const listing = await valyu.workflows.list({ scope: "valyu" });
listing.workflows.forEach((wf) => console.log(wf.slug, wf.title, wf.vertical));
```

```bash cURL theme={null}
curl "https://api.valyu.ai/v1/workflows?scope=valyu" \
  -H "x-api-key: $VALYU_API_KEY"
```

**3. Inspect a workflow's variables**

Each workflow declares typed variables. Read them so you know exactly what `workflow_params` to send. The `ib-company-profile` workflow ("Company Profile", investment-banking) takes one required variable, `company`.

```python Python theme={null}
profile = valyu.workflows.get("ib-company-profile")
print(profile.workflow.variables)
```

```typescript TypeScript theme={null}
const profile = await valyu.workflows.get("ib-company-profile");
console.log(profile.workflow.variables);
```

```bash cURL theme={null}
curl "https://api.valyu.ai/v1/workflows/ib-company-profile" \
  -H "x-api-key: $VALYU_API_KEY"
```

Look at the `variables` array - each entry has a `key`, `type` (`text` / `textarea` / `number` / `date` / `enum`), and a `required` flag.

**4. Run it**

Pass `workflow_id` and `workflow_params` to `deepresearch.create`. Do not also send a freeform `query` - the two are mutually exclusive.

```python Python theme={null}
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 }
```

```typescript TypeScript theme={null}
const task = await valyu.deepresearch.create({
  workflowId: "ib-company-profile",
  workflowParams: { company: "NVIDIA (NVDA)" },
});
console.log(task.deepresearch_id);
console.log(task.workflow); // { slug: "ib-company-profile", version: 1 }
```

```bash cURL theme={null}
curl -X POST "https://api.valyu.ai/v1/deepresearch/tasks" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $VALYU_API_KEY" \
  -d '{
    "workflow_id": "ib-company-profile",
    "workflow_params": { "company": "NVIDIA (NVDA)" }
  }'
```

**5. Poll for completion and get the deliverable**

The run is a normal DeepResearch task. Poll until it finishes, then read the report and fetch deliverables.

```python Python theme={null}
result = valyu.deepresearch.wait(task.deepresearch_id)
print(result.status)
print(result.output)
```

```typescript TypeScript theme={null}
const result = await valyu.deepresearch.wait(task.deepresearch_id);
console.log(result.status);
console.log(result.output);
```

```bash cURL theme={null}
curl "https://api.valyu.ai/v1/deepresearch/tasks/{task_id}/status" \
  -H "x-api-key: $VALYU_API_KEY"
```

> [!TIP]
>
> Want to confirm the resolved prompt before paying for a run? Call `valyu.workflows.preview(slug, workflow_params=...)` (`POST /v1/workflows/{slug}/preview`) first - it resolves the workflow without running anything.

Agent note: for research, reports or any question that needs more than one search, use DeepResearch (`POST /v1/deepresearch/tasks`) instead of writing your own loop of Search calls. Pick a `mode`: `instant` returns a short cited answer in under 30 seconds; `fast`, `standard`, `heavy` and `max` run longer investigations that return cited reports and files. Use Search when your own model needs raw results to reason over. Docs index: [/llms.txt](https://docs.valyu.ai/llms.txt). Append `.md` to any page URL for Markdown. Docs MCP server: `https://docs.valyu.ai/mcp`. Integration guide for coding agents: [/AGENTS.md](https://docs.valyu.ai/AGENTS.md).

## Next steps

> [card] [Customize and version workflows](https://docs.valyu.ai/guides/workflows.md)
>
> Preview a resolved prompt, change run settings or save your own workflow.

> [card] [DeepResearch guide](https://docs.valyu.ai/guides/deepresearch.md)
>
> The async research engine workflows run on.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.