Skip to main content
POST
/
v1
/
deepresearch
/
batches
curl --request POST \ --url https://api.valyu.ai/v1/deepresearch/batches \ --header 'Content-Type: application/json' \ --header 'x-api-key: <api-key>' \ --data ' { "name": "Q4 Market Analysis", "mode": "standard" } '
{
  "batch_id": "<string>",
  "status": "open",
  "mode": "standard",
  "counts": {
    "total": 123,
    "queued": 123,
    "running": 123,
    "completed": 123,
    "failed": 123,
    "cancelled": 123
  },
  "cost": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "organisation_id": "<string>",
  "name": "<string>",
  "output_formats": [
    "<string>"
  ],
  "search_params": {
    "search_type": "all",
    "included_sources": [
      "<string>"
    ],
    "excluded_sources": [
      "<string>"
    ],
    "start_date": "2023-12-25",
    "end_date": "2023-12-25",
    "category": "<string>"
  },
  "webhook_url": "<string>",
  "webhook_secret": "<string>",
  "metadata": {},
  "completed_at": "2023-11-07T05:31:56Z"
}

Authorizations

​
x-api-key
string
header
required

Your Valyu API key. Get one at platform.valyu.ai

Body

application/json
​
name
string

Optional name for the batch

Example:

"Q4 Market Analysis"

​
mode
enum<string>
default:standard

DeepResearch mode for all tasks in this batch

Available options:
standard,
heavy,
fast
​
output_formats
(string | object)[]

Default output formats for all tasks (markdown, pdf, toon, or structured JSON schema). Cannot mix JSON schema with markdown/pdf. toon requires a JSON schema.

​
search
object

Search configuration applied to all tasks in the batch (cannot be overridden per task)

​
webhook_url
string<uri>

HTTPS URL to receive notifications when the batch completes

​
metadata
object

Custom metadata for tracking and organization

Response

Batch created successfully

​
batch_id
string
required

Unique batch identifier

​
status
enum<string>
required

Current batch status

Available options:
open,
processing,
completed,
completed_with_errors,
cancelled
​
mode
enum<string>
required

DeepResearch mode for all tasks in this batch

Available options:
standard,
heavy,
fast
​
counts
object
required
​
cost
number
required

Total cost in dollars

​
created_at
string<date-time>
required

Batch creation timestamp

​
organisation_id
string

Organization ID that owns this batch

​
name
string

Optional batch name

​
output_formats
(string | object)[]

Default output formats for tasks

​
search_params
object

Default search configuration

​
webhook_url
string

Webhook URL for completion notifications

​
webhook_secret
string

Secret for webhook signature verification. Only present in batch creation responses.

​
metadata
object

Custom metadata

​
completed_at
string<date-time>

Completion timestamp (if completed)