Batches

Create a new batch

Create a batch for running multiple DeepResearch tasks with shared configuration. After creation, add tasks with the Add Tasks endpoint. The batch transitions from open to processing when tasks are added.

post/v1/deepresearch/batches

Request

  • Base URL: https://api.valyu.ai
  • URL: https://api.valyu.ai/v1/deepresearch/batches
  • Auth: API key in header X-API-Key

Request body

namestring

Optional name for the batch.

mode'fast' | 'standard' | 'heavy' | 'max'

Research mode applied to all tasks in the batch.

model'fast' | 'standard' | 'heavy' | 'max'

Deprecated. Use mode instead.

webhook_urlstring uri

HTTPS URL to receive a webhook when all tasks complete.

metadataobject

Arbitrary key-value metadata.

Example request

{
  "name": "Q4 Earnings Analysis Batch"
}

Response

Batch created.

batch_idstring required

Unique batch identifier.

status'open' | 'processing' | 'completed' | 'completed_with_errors' | 'cancelled' 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
mode'fast' | 'standard' | 'heavy' | 'max' required

Research mode for all tasks in this batch.

created_atstring date-time required

ISO 8601 timestamp of batch creation.

namestring

Human-readable name for the batch.

search_paramsobject

Shared search configuration.

costnumber required

Aggregated cost in USD across all tasks.

completed_atstring date-time

ISO 8601 timestamp. Present when batch is completed.

webhook_secretstring

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

Example response

{
  "batch_id": "batch_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing",
  "mode": "standard",
  "created_at": "2024-06-15T10:30:00.000Z",
  "name": "Q4 Earnings Analysis Batch",
  "output_formats": [
    "markdown"
  ],
  "counts": {
    "total": 10,
    "queued": 3,
    "running": 2,
    "completed": 4,
    "failed": 1
  },
  "cost": 5
}

Changes

No recorded changes to this operation across all 1 revision of this API.