Skip to main content
GET
/
v1
/
deepresearch
/
batches
List all batches
curl --request GET \
  --url https://api.valyu.ai/v1/deepresearch/batches \
  --header 'X-API-Key: <api-key>'
[
  {
    "batch_id": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "completed",
    "mode": "standard",
    "created_at": "2024-06-15T10:30:00.000Z",
    "counts": {
      "total": 5,
      "queued": 0,
      "running": 0,
      "completed": 5,
      "failed": 0,
      "cancelled": 0
    },
    "cost": 2.5
  }
]

Authorizations

​
X-API-Key
string
header
required

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

Query Parameters

​
limit
integer

Maximum number of batches to return.

Required range: x >= 1

Response

List of batches.

​
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.