Skip to main content
GET
/
v1
/
deepresearch
/
batches
/
{id}
Get batch status
curl --request GET \
  --url https://api.valyu.ai/v1/deepresearch/batches/{id} \
  --header 'X-API-Key: <api-key>'
{
  "batch_id": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "mode": "standard",
  "created_at": "2024-06-15T10:30:00.000Z",
  "counts": {
    "total": 10,
    "queued": 2,
    "running": 3,
    "completed": 4,
    "failed": 1,
    "cancelled": 0
  },
  "cost": 2
}

Authorizations

​
X-API-Key
string
header
required

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

Path Parameters

​
id
string
required

Batch ID.

Response

Batch status.

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.