Submit a batch flow execution

POST

/v1/batch/flow

POST

/v1/batch/flow

$ curl -X POST https://api.runtype.com/v1/batch/flow \
>      -H "Authorization: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d '{
>   "flowId": "flow_01jv0000000000000000000001",
>   "options": {
>     "recordConcurrency": 10
>   },
>   "records": [
>     {
>       "metadata": {
>         "company": "Acme Corp",
>         "employees": 120,
>         "website": "https://acme.example"
>       },
>       "name": "Acme Corp",
>       "type": "lead"
>     },
>     {
>       "metadata": {
>         "company": "Globex",
>         "employees": 4800,
>         "website": "https://globex.example"
>       },
>       "name": "Globex",
>       "type": "lead"
>     }
>   ]
> }'

1 {
2   "batchExecutionId": "string",
3   "status": "string"
4 }

Submits a batch of records for flow execution. Checks daily execution limits and feature gating.

Authentication

AuthorizationBearer

API key or Clerk session token

Request

Batch flow request body. Target one of flowId, flowDefinition, or agentId; supply recordIds, records, or both. The optional options object accepts the documented execution tunables; unknown or out-of-range option keys are rejected at submission. Legacy snake_case aliases are accepted.

agentIdstring or nullOptional

Agent to execute per record instead of a flow. Saved records are loaded and their conversation read from metadata.messages; inline records reach the agent only when their type is _agent_eval or _agent_schedule and metadata.messages carries the conversation. Any other inline record type fails per record.

flowDefinitionobjectOptional

Inline flow definition executed per record without saving the flow.

flowIdstring or nullOptional

Saved flow to execute per record. One of flowId, flowDefinition, or agentId is required.

inputsmap from strings to any or nullOptional

Flow input variables applied to every record execution.

messageslist of objects or nullOptional

Conversation seed passed unchanged to every record execution. Records cannot see each other's history.

optionsobject or nullOptional

recordIdslist of strings or nullOptional

Saved record ids to process. May be combined with records; the batch runs the union. At least one of recordIds or records must be non-empty. Maximum 50000 records per batch across both.

recordslist of objects or nullOptional

Inline records to process without saving them first. May be combined with recordIds. Maximum 50000 records per batch across both.

Response

Batch submitted

batchExecutionIdstring

statusstring

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

429

Too Many Requests Error

500

Internal Server Error