---
canonical_url: "https://docs.composio.dev/toolkits/valyu"
markdown_url: "https://docs.composio.dev/toolkits/valyu.md"
product: "platform"
version: null
last_updated: null
---

# Valyu

Valyu provides one API for searching specialist, proprietary, and web sources and running multi-step research with cited, structured outputs.

- **Category:** artificial intelligence
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 32
- **Triggers:** 0
- **Slug:** `VALYU`
- **Version:** 00000000_00

## Tools

### Add DeepResearch Batch Tasks

**Slug:** `VALYU_ADD_DEEP_RESEARCH_BATCH_TASKS`

Add 1-100 paid research tasks to an open or processing DeepResearch batch. Each task costs the batch mode's base price: at least 25 credits per task (fast), or 100 standard, 500 heavy, and 2,500 max, before add-ons. Valyu reserves the full set's mode prices in one all-or-nothing step; a 402 adds no tasks, and a 503 means billing could not be checked and nothing was added.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch batch ID. The batch must be open or processing. |
| `tasks` | array | Yes | Research tasks to add (1-100). Every task uses the batch mode's paid price. Valyu reserves credits for the entire list atomically: if the available balance or usage limits cannot cover every task, none are added. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Answer

**Slug:** `VALYU_ANSWER`

Generate a cited answer from live search and return the complete answer, sources, warnings, token usage, and authoritative billed cost.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Question or research query to answer. |
| `end_date` | string | No | Latest publication date to include, in YYYY-MM-DD format. |
| `fast_mode` | boolean | No | Use the lower-latency answer mode with three search tool-call rounds. |
| `start_date` | string | No | Earliest publication date to include, in YYYY-MM-DD format. |
| `search_type` | string ("all" | "web" | "proprietary" | "news") | No | Source family to search: all combines web and proprietary sources; web, proprietary, and news restrict the search to that family. |
| `country_code` | string ("ALL" | "AR" | "AU" | "AT" | "BE" | "BR" | "CA" | "CL" | "DK" | "FI" | "FR" | "DE" | "HK" | "IN" | "ID" | "IT" | "JP" | "KR" | "MY" | "MX" | "NL" | "NZ" | "NO" | "CN" | "PL" | "PT" | "PH" | "RU" | "SA" | "ZA" | "ES" | "SE" | "CH" | "TW" | "TR" | "GB" | "US") | No | ISO 3166-1 alpha-2 country code for geo-targeted search, or ALL. |
| `data_max_price` | number | No | Maximum budget in dollars for search only. This does not cap content extraction or AI processing charges. |
| `excluded_sources` | array | No | Domains, URLs, or dataset identifiers to exclude. Presets are not supported. May be combined with included_sources. |
| `included_sources` | array | No | Domains, URLs, dataset identifiers, or supported presets to include. May be combined with excluded_sources for narrower filtering. |
| `structured_output` | object | No | JSON Schema for a structured JSON answer instead of free-form text. The schema may have at most 10 levels, 50 properties, and 5000 characters. |
| `system_instructions` | string | No | Replacement system instructions for answer generation, up to 2000 characters. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Cancel DeepResearch Batch

**Slug:** `VALYU_CANCEL_DEEP_RESEARCH_BATCH`

WARNING: irreversibly cancel all queued and running tasks in an open or processing DeepResearch batch. Completed tasks are not undone. Cancelling running tasks can incur their full mode price; queued-task cancellation is free.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch batch ID to cancel. The batch must be open or processing. Cancellation affects queued and running tasks but does not undo completed tasks; cancelling running tasks can incur their full mode price. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Cancel DeepResearch Task

**Slug:** `VALYU_CANCEL_DEEP_RESEARCH_TASK`

WARNING: irreversibly cancel a DeepResearch task in queued, running, awaiting_input, or paused status. Cancelling a running or awaiting_input task charges its full mode price; cancelling a queued or paused task is free.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch task ID to cancel. WARNING: cancelling a running or awaiting_input task charges its full mode price; cancelling a queued or paused task is free. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create DeepResearch Batch

**Slug:** `VALYU_CREATE_DEEP_RESEARCH_BATCH`

Create an empty DeepResearch batch with shared mode, output, search, webhook, and metadata configuration. WARNING: Valyu provides no batch-delete endpoint, so even an empty batch persists. Adding tasks later incurs the selected DeepResearch mode cost for each task.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | string ("fast" | "standard" | "heavy" | "max") | No | Research mode shared by every task in the batch. |
| `name` | string | No | Optional human-readable batch name. |
| `model` | string ("fast" | "standard" | "heavy" | "max") | No | Deprecated research mode selector. Use mode instead. |
| `search` | object | No | Shared source, geography, date, bias, and snapshot controls. |
| `metadata` | object | No | Caller key-value metadata attached to the batch. |
| `webhook_url` | string | No | HTTPS webhook called when every task in the batch finishes. |
| `output_formats` | array | No | Output formats shared by all tasks: markdown, pdf, or a JSON Schema object. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create DeepResearch Task

**Slug:** `VALYU_CREATE_DEEP_RESEARCH_TASK`

Start a paid asynchronous DeepResearch task. Choose exactly one side: freeform mode, supplying query (preferred) or the deprecated input field; or workflow mode, supplying workflow_id and the required workflow_params. Do not mix freeform and workflow fields. When share_with is provided, share_notify defaults to true and sends notification email to those recipients; set it false to create sharing access without emailing them. Base prices before tool add-ons are 8 credits (instant), 25 (fast), 100 (standard), 500 (heavy), and 2,500 (max). Creation holds the mode price; insufficient balance returns 402 without creating a task.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `hitl` | object | No | Human-in-the-loop checkpoints; unavailable for batch requests. |
| `mode` | string ("instant" | "fast" | "standard" | "heavy" | "max") | No | Research depth and base task price before tool add-ons: instant 8 credits, fast 25, standard 100, heavy 500, or max 2,500 credits. |
| `urls` | array | No | URLs to include in the research context (maximum 50). The first 10 are free; each additional URL costs 8 credits. For tasks created from 2026-11-13, scanned pages requiring OCR in URL files cost 2.4 credits per page. |
| `files` | array | No | Data-URL file attachments (maximum 10). |
| `input` | string | No | Freeform mode only: deprecated research question; use query instead. Do not supply workflow_id. |
| `model` | string ("fast" | "standard" | "heavy" | "max") | No | Deprecated mode selector. Use mode instead. |
| `query` | string | No | Freeform mode only: preferred research question (maximum 25,000 characters). Supply query or the deprecated input field, and do not supply workflow_id. |
| `tools` | object | No | X search, code execution, screenshots, browser sessions, and chart controls. |
| `search` | object | No | Source, geography, date, bias, and historical snapshot controls. |
| `metadata` | object | No | Caller key-value metadata attached to the task. |
| `strategy` | string | No | Deprecated research strategy. Use research_strategy instead. |
| `cover_art` | object | No | Cover art for this one report. It replaces the brand kit's cover art on the PDF report cover, the PDF deliverable and the title slide of a PPTX deck, and works without a kit. Send exactly one of data or url. The picture must be a PNG or JPEG, at most 2 MB after base64 decoding, and at least 800 px on the short side. Cropping it to the A4 page must keep at least 25% of it. For a large picture, send url. A malformed field returns 400. A picture that cannot be used, including a private or unreachable url, never fails the task: the kit's cover art or the standard cover applies, and warnings carries cover_art_not_used. |
| `share_with` | array | No | People or company domains who can open the report. Each entry is an email address (name@company.com) or a whole company domain (@company.com). The report stays private: only these people and members of your organization can open it. Viewers open the share link and sign in to Valyu with that email address, which must be verified. A domain covers anyone with a verified email at exactly that domain, not its subdomains. Public email providers such as gmail.com and outlook.com can't be shared as a domain; add those people individually. An invalid entry returns 400 and no task is created. Max 100. |
| `alert_email` | string | No | Completion email address or email/custom report URL configuration. |
| `mcp_servers` | array | No | MCP tool servers available during research (maximum 5). |
| `webhook_url` | string | No | HTTPS completion webhook signed with HMAC-SHA256. |
| `workflow_id` | string | No | Workflow mode only: workflow slug to run instead of query or input. workflow_params is required with workflow_id. |
| `deliverables` | array | No | Natural-language or typed CSV, XLSX, PPTX, DOCX, or PDF deliverables (maximum 10). |
| `share_notify` | boolean | No | Email each person in share_with a link to the report. Domains are never emailed. |
| `report_format` | string | No | Report structure, style, length, and presentation; combined with the effective strategy, maximum 15,000 characters. |
| `code_execution` | boolean | No | Deprecated code-execution switch. Use tools.code_execution instead. |
| `output_formats` | array | No | Report formats. Use markdown and optionally pdf, or one JSON Schema optionally paired with toon; toon requires that schema. |
| `workflow_params` | object | No | Required with workflow_id: workflow variable values keyed by the workflow's declared variable keys. Do not supply in freeform mode. |
| `previous_reports` | array | No | Prior DeepResearch task IDs to use as context (maximum 3). |
| `workflow_version` | integer | No | Immutable workflow version to run. Requires workflow_id. |
| `research_strategy` | string | No | Research methodology and source priorities; combined with report_format, maximum 15,000 characters. |
| `brand_collection_id` | string | No | Brand kit ID, or none for no branding; paid-plan entitlement may apply. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Workflow

**Slug:** `VALYU_CREATE_WORKFLOW`

Create a private organization workflow and its first immutable version. Use a new slug for each attempt. If Valyu returns 5xx, this action performs one lookup by slug because the workflow may have persisted; it never retries or deletes automatically.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `icon` | string | No | Workflow icon identifier. |
| `slug` | string | Yes | Unique organization workflow slug; use a new slug for each create attempt. |
| `tags` | array | No | Discovery tags, up to 20. |
| `title` | string | Yes | Workflow display title. |
| `version` | object | Yes | First immutable workflow version and its research template. |
| `subtitle` | string | No | Short workflow subtitle. |
| `vertical` | string | No | Target vertical. |
| `description` | string | No | Longer explanation of the workflow. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete DeepResearch Task

**Slug:** `VALYU_DELETE_DEEP_RESEARCH_TASK`

Permanently delete a completed, failed, or cancelled DeepResearch task and all associated outputs, sources, PDFs, and images. Running or queued tasks must be cancelled first.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch task ID to permanently delete. The task must be completed, failed, or cancelled; cancel a running or queued task first. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Workflow

**Slug:** `VALYU_DELETE_WORKFLOW`

Soft-delete an organization-owned workflow. Valyu-curated workflows cannot be deleted.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Organization-owned workflow slug to soft-delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Extract Contents

**Slug:** `VALYU_EXTRACT_CONTENTS`

Extract content from up to 10 URLs synchronously or queue up to 50 URLs asynchronously. Returns every per-URL success, failure, or not-found outcome and the authoritative charge; async responses return a job_id for Get Contents Job.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `urls` | array | Yes | HTTP or HTTPS URLs to extract. Duplicates are silently removed. |
| `async` | boolean | No | Queue background extraction. Required for more than 10 URLs; save the returned job_id and poll it with Get Contents Job. |
| `max_age` | integer | No | Maximum accepted cache age in seconds. Zero forces a live crawl; cannot be used with historical_cache. |
| `summary` | string | No | AI processing mode: false for raw content, true for a summary, a string of summary instructions (up to 500 characters), or a JSON Schema object for structured extraction. When enabled, AI processing adds 0.4 credits to the 0.2-credit base, for 0.6 credits total per successfully extracted URL. Text summaries and structured extraction cost the same; if the AI step fails, only the 0.2-credit base is charged. |
| `end_date` | string | No | End cutoff for point-in-time extraction as YYYY, YYYY-MM-DD, or an ISO-8601 datetime. A year means its final day. |
| `screenshot` | boolean | No | Capture a screenshot and return screenshot_url for each successful page. |
| `start_date` | string | No | Start of the point-in-time extraction window as YYYY, YYYY-MM-DD, or an ISO-8601 datetime. Use with historical_cache. |
| `webhook_url` | string | No | HTTPS completion webhook used only in async mode. Valyu signs its payload with the webhook_secret returned when the job is created. |
| `extract_effort` | string ("auto" | "normal" | "high") | No | Rendering effort: auto chooses per URL, normal uses HTTP-only extraction, and high uses full browser rendering. |
| `response_length` | string | No | Maximum extracted characters per URL: short (25,000), medium (50,000), large (100,000), max (unlimited), or a positive integer. |
| `historical_cache` | boolean | No | Require a cached snapshot within the date window. Contents requests enforce an only policy and do not fall back to a live crawl. |
| `max_price_dollars` | number | No | Maximum request budget in dollars. The request is rejected before processing if its worst-case cost exceeds this value and may return 402 if its actual cost exceeds it. |
| `include_image_links` | boolean | No | Keep image URLs in extracted markdown. Set false to retain image alt text without image URLs and reduce token usage. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Contents Job

**Slug:** `VALYU_GET_CONTENTS_JOB`

Get an asynchronous content extraction job's status, per-URL results, failures, and final charge. HTTP 200 and top-level success=true only mean the status request succeeded; inspect status and each result to determine extraction success.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `job_id` | string | Yes | Job ID returned by Extract Contents in async mode. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get DeepResearch Batch Status

**Slug:** `VALYU_GET_DEEP_RESEARCH_BATCH_STATUS`

Get a DeepResearch batch's lifecycle status, task counts, shared configuration, timestamps, and aggregate cost.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch batch ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get DeepResearch Sharing

**Slug:** `VALYU_GET_DEEP_RESEARCH_SHARING`

List the people and company domains a DeepResearch report is shared with, including its share link, public setting, notification timestamps, and view timestamps. Sharing with named recipients is separate from public access, and only the API key that created the task can read it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch task ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get DeepResearch Status

**Slug:** `VALYU_GET_DEEP_RESEARCH_STATUS`

Get a DeepResearch task's status, progress, checkpoint, report, sources, generated files, warnings, and cost.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch task ID. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Workflow

**Slug:** `VALYU_GET_WORKFLOW`

Get a workflow's current version, including its template, tools, output formats, deliverables, and variables. Use Get Workflow Version to read a specific historical version.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Workflow slug. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Workflow Version

**Slug:** `VALYU_GET_WORKFLOW_VERSION`

Get a workflow resolved at one specific immutable version, including its template, tools, output formats, deliverables, and variables.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Workflow slug. |
| `version` | integer | Yes | Immutable workflow version number. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Datasource Categories

**Slug:** `VALYU_LIST_DATASOURCE_CATEGORIES`

List current datasource category IDs, names, descriptions, and dataset counts.

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Datasources

**Slug:** `VALYU_LIST_DATASOURCES`

List searchable datasources and their IDs, capabilities, pricing, plan requirements, schemas, and example queries, optionally by category.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category` | string | No | Datasource category to return. Use List Datasource Categories to discover current category IDs. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List DeepResearch Batches

**Slug:** `VALYU_LIST_DEEP_RESEARCH_BATCHES`

List DeepResearch batches with lifecycle status, task counts, and aggregate cost.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of batches to return (1-100). Always sent; defaults to 20. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List DeepResearch Batch Tasks

**Slug:** `VALYU_LIST_DEEP_RESEARCH_BATCH_TASKS`

Return one cursor-controlled page of a DeepResearch batch's tasks, optionally filtered by status and expanded with outputs, sources, files, errors, and costs.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch batch ID. |
| `limit` | integer | No | Maximum number of tasks to return in this page. |
| `status` | string ("queued" | "running" | "completed" | "failed" | "cancelled") | No | Return only tasks with this status. |
| `next_cursor` | string | No | Opaque continuation value returned as next_cursor by the previous page; omit for the first page. |
| `include_output` | boolean | No | Whether to include task outputs, sources, images, PDFs, deliverables, errors, and cost. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List DeepResearch Tasks

**Slug:** `VALYU_LIST_DEEP_RESEARCH_TASKS`

List up to 100 DeepResearch task summaries for the connected API key.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of task summaries to return (1-100). |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Workflows

**Slug:** `VALYU_LIST_WORKFLOWS`

List visible curated and organization workflows with discovery metadata and optional current-version expansion. Returns at most the requested 1-100 rows; a returned next_cursor is informational because the API accepts no continuation input.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | string | No | Comma-separated tags to filter by. |
| `limit` | integer | No | Maximum number of workflows to return (1-100). |
| `query` | string | No | Free-text search over workflow titles, subtitles, and descriptions. |
| `scope` | string ("valyu" | "org" | "all") | No | Which visible workflows to return: Valyu-curated, organization-owned, or all workflows. |
| `expand` | string | No | Comma-separated fields to expand. Pass version to include each workflow's full current version. |
| `vertical` | string | No | Workflow vertical to filter by, such as finance or life-sciences. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Workflow Versions

**Slug:** `VALYU_LIST_WORKFLOW_VERSIONS`

List a workflow's immutable version history newest first, including current-version and changelog metadata.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Workflow slug whose immutable version history to list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Preview Workflow

**Slug:** `VALYU_PREVIEW_WORKFLOW`

Resolve workflow variables and return the exact DeepResearch configuration and estimated credits without launching or charging for a research task.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Workflow slug to resolve without starting a DeepResearch task. |
| `workflow_params` | object | No | Values for the workflow's template variables, keyed by variable key. |
| `workflow_version` | integer | No | Immutable workflow version to preview; omit to resolve the current version. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Publish Workflow Version

**Slug:** `VALYU_PUBLISH_WORKFLOW_VERSION`

Publish a new immutable version of an organization-owned workflow. Supply the complete prompt, strategy, and report format, not a partial patch, plus a non-empty changelog describing what changed. Optionally make the published version current. Published versions cannot be edited in place.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `slug` | string | Yes | Organization-owned workflow slug. |
| `version` | object | Yes | Complete immutable version to publish. Prompt, strategy, report_format, and a non-empty changelog describing the changes are required. |
| `set_current` | boolean | No | Whether the newly published version becomes the workflow's current version. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Respond to DeepResearch Checkpoint

**Slug:** `VALYU_RESPOND_TO_DEEP_RESEARCH_CHECKPOINT`

Answer an active planning, plan-review, source-review, or outline-review checkpoint so a DeepResearch task in awaiting_input or paused state can continue. Resuming a paused task requires enough balance and can continue paid execution that incurs the task's mode price and add-on charges.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch task ID. The task must currently be awaiting_input or paused. |
| `response` | string | Yes | Checkpoint-specific nested response matching the task interaction type. |
| `interaction_id` | string | Yes | Interaction ID from the task status interaction field. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search

**Slug:** `VALYU_SEARCH`

Search web, news, academic, financial, and specialist sources, returning ranked content, source coverage, warnings, and the amount charged.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural-language search query. |
| `category` | string | No | Deprecated ranking guidance retained for compatibility; use instructions instead. |
| `end_date` | string | No | Publication end date as a year, YYYY-MM-DD date, or ISO-8601 datetime. |
| `url_only` | boolean | No | Return URLs without full content extraction. Available only for web or news search. |
| `fast_mode` | boolean | No | Skip query rewriting and reranking for lower latency; incompatible with proprietary-only search. |
| `max_price` | number | No | Maximum total search price. The provider rejects budgets below the request's worst-case cost. |
| `start_date` | string | No | Publication start date as a year, YYYY-MM-DD date, or ISO-8601 datetime. |
| `search_type` | string ("all" | "web" | "proprietary" | "news") | No | Source family to search: all sources, web only, proprietary sources only, or news only. |
| `country_code` | string ("ALL" | "AR" | "AU" | "AT" | "BE" | "BR" | "CA" | "CL" | "DK" | "FI" | "FR" | "DE" | "HK" | "IN" | "ID" | "IT" | "JP" | "KR" | "MY" | "MX" | "NL" | "NZ" | "NO" | "CN" | "PL" | "PT" | "PH" | "RU" | "SA" | "ZA" | "ES" | "SE" | "CH" | "TW" | "TR" | "GB" | "US") | No | ISO 3166-1 alpha-2 country code for geo-targeted web results, or ALL. |
| `hls_coverage` | string ("hls" | "increased_coverage") | No | Coverage mode for Wiley Health and Life Sciences: licensed HLS only or increased open-access coverage. |
| `instructions` | string | No | Natural-language reranking instructions, up to 500 characters. Ignored in fast mode. |
| `scope_policy` | string ("advisory" | "strict") | No | Whether included datasets guide source selection or define an exact strict dataset scope. |
| `source_biases` | object | No | Per-domain or URL-path ranking biases, with integer values from -5 (strong demotion) to 5 (strong boost). |
| `max_num_results` | integer | No | Maximum results to return (1-20). Higher account limits may be available, and the provider may cap this value with a warning. |
| `response_length` | string | No | Maximum content per result: short, medium, large, max, or a positive custom character count. |
| `excluded_sources` | array | No | Domains, URLs, dataset IDs, or presets to exclude from the search. |
| `historical_cache` | boolean | No | Prefer cached content captured in the requested date window instead of the latest crawl. |
| `included_sources` | array | No | Domains, URLs, dataset IDs, presets, the web keyword, or collection names to include. |
| `include_abstracts` | boolean | No | Include the full PubMed abstract corpus and full-text chunks when available. |
| `include_image_links` | boolean | No | Keep image URLs in returned markdown instead of replacing images with alt-text markers. |
| `relevance_threshold` | number | No | Minimum post-reranking relevance score from 0 to 1. |
| `historical_cache_strict` | string ("off" | "prefer" | "only") | No | Historical snapshot fallback policy: off, prefer an in-window snapshot, or only return qualifying snapshots. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Search Datasources

**Slug:** `VALYU_SEARCH_DATASOURCES`

Find datasources accessible to the connected key from a natural-language need, returning ranked datasource IDs and full metadata.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | integer | No | Maximum number of ranked datasources to return (1-100). |
| `query` | string | Yes | Natural-language description of the data you want. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Set DeepResearch Public Access

**Slug:** `VALYU_SET_DEEP_RESEARCH_PUBLIC_ACCESS`

Make a DeepResearch task public or private. Public results are accessible without authentication, so review sensitive content before enabling access.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch task ID. |
| `public` | boolean | Yes | True to enable unauthenticated public access; false to make the results private. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update DeepResearch Sharing

**Slug:** `VALYU_UPDATE_DEEP_RESEARCH_SHARING`

Atomically add or remove people and company domains that can open a private DeepResearch report. The report remains private and sharing does not change its public setting. Omitted notify defaults to true and emails every individual in add; set notify=false to avoid notification emails. Domains are never emailed. A report can be shared with at most 100 people and domains, and only the API key that created the task can change sharing.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch task ID. |
| `add` | array | No | Email addresses (name@company.com) or company domains (@company.com) to share with. Public email providers cannot be added as domains. |
| `notify` | boolean | No | Email each person in add a report link. Defaults to true; domains are never emailed. |
| `remove` | array | No | Email addresses or company domains to stop sharing with, using the same format as add. |
| `shared_by` | string | No | Sender name used in notification emails; defaults to the organization's name. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update DeepResearch Task

**Slug:** `VALYU_UPDATE_DEEP_RESEARCH_TASK`

Add a follow-up instruction to a running DeepResearch task before its writing phase begins.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | string | Yes | DeepResearch task ID. |
| `instruction` | string | Yes | Follow-up instruction for the research agent. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Update Workflow

**Slug:** `VALYU_UPDATE_WORKFLOW`

Update metadata on an organization-owned workflow. Provide at least one of title, subtitle, description, vertical, tags, or icon. Use Publish Workflow Version to publish an immutable version. Valyu-curated workflows are read-only.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `icon` | string | No | Updated workflow icon identifier. |
| `slug` | string | Yes | Organization-owned workflow slug. |
| `tags` | array | No | Replacement discovery tags, up to 20. |
| `title` | string | No | Updated workflow title. |
| `subtitle` | string | No | Updated short subtitle. |
| `vertical` | string | No | Updated target vertical. |
| `description` | string | No | Updated longer workflow description. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |
