Skip to main content
POST
/
v1
/
deepresearch
/
batches
Create a new batch
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 2024 Earnings Analysis",
  "mode": "standard",
  "output_formats": [
    "markdown",
    "pdf"
  ],
  "search": {
    "search_type": "proprietary",
    "included_sources": [
      "finance"
    ]
  }
}
'
{
  "batch_id": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "open",
  "mode": "standard",
  "name": "Q4 2024 Earnings Analysis",
  "output_formats": [
    "markdown",
    "pdf"
  ],
  "search_params": {
    "search_type": "proprietary",
    "included_sources": [
      "finance"
    ]
  },
  "counts": {
    "total": 0,
    "queued": 0,
    "running": 0,
    "completed": 0,
    "failed": 0,
    "cancelled": 0
  },
  "cost": 0,
  "created_at": "2024-06-15T10:30:00.000Z",
  "webhook_secret": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef12345678"
}

Authorizations

​
X-API-Key
string
header
required

API key for authentication. Get yours at platform.valyu.ai.

Body

application/json

Create a new batch for running multiple DeepResearch tasks with shared configuration.

​
name
string

Optional name for the batch.

Example:

"Q4 Earnings Analysis Batch"

​
mode
enum<string>
default:standard

Research mode applied to all tasks in the batch.

Available options:
fast,
standard,
heavy,
max
​
model
enum<string>
deprecated

Deprecated. Use mode instead.

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

Output formats applied to all tasks.

Available options:
markdown,
pdf
​
search
object

Search configuration for DeepResearch tasks.

​
webhook_url
string<uri>

HTTPS URL to receive a webhook when all tasks complete.

​
metadata
object

Arbitrary key-value metadata.

Response

Batch created.

Batch status and metadata.

​
batch_id
string
required

Unique batch identifier.

Example:

"batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
status
enum<string>
required

Batch lifecycle status.

  • open - Batch created, accepting tasks
  • processing - Tasks are running
  • completed - All tasks finished successfully
  • completed_with_errors - All tasks finished, some failed
  • cancelled - Batch was cancelled
Available options:
open,
processing,
completed,
completed_with_errors,
cancelled
Example:

"processing"

​
mode
enum<string>
required

Research mode for all tasks in this batch.

Available options:
fast,
standard,
heavy,
max
Example:

"standard"

​
created_at
string<date-time>
required

ISO 8601 timestamp of batch creation.

Example:

"2024-06-15T10:30:00.000Z"

​
counts
object
required

Task count breakdown for a batch.

​
cost
number
required

Aggregated cost in USD across all tasks.

Example:

5

​
name
string

Human-readable name for the batch.

Example:

"Q4 Earnings Analysis Batch"

​
output_formats
(string | object)[]

Output formats configured for all tasks.

Example:
["markdown"]
​
search_params
object

Shared search configuration.

​
completed_at
string<date-time>

ISO 8601 timestamp. Present when batch is completed.

​
webhook_secret
string

HMAC-SHA256 secret. Only present on creation when webhook_url was provided.