AI agents: install the Runflow skill before integrating, or jump to For agents.
Reference
- POSTCreate and dispatch a batch
- GETSearch models
- GETList Model Availability Statuses
- GETGet Model Availability Status
- GETList Model Categories
- GETGet Model Category
- GETList Model Example Categories
- GETGet Model Example Category
- GETList Model Family Variants
- GETGet Model Family Variant
- GETList Model License Types
- GETGet Model License Type
- GETList Model Statuses
- GETGet Model Status
- GETGet model
- GETSearch model examples
- GETGet model example
- GETSearch model faq entries
- GETGet model faq entry
- GETSearch model inputs
- GETGet model input
- GETSearch model outputs
- GETGet model output
- GETSearch model customer pricings
- GETGet model customer pricing
- GETSearch model related links
- GETGet model related link
- GETGet model by owner and slug
- GETGet the llms.txt markdown for a public model
- GETList runs for a model
- POSTCreate and dispatch a singleton model run
- GETList public, active models (no auth)
curl --request POST \
--url https://api.runflow.io/v1/models/{owner}/{slug}/batches \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": [
{}
],
"metadata": {},
"callback_url": "<string>"
}
'{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_type": "<string>",
"target_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status_code": "<string>",
"items_total": 123,
"items_succeeded": 123,
"items_failed": 123,
"items_cancelled": 123,
"items": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"sequence_index": 123,
"run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status_code": "<string>",
"client_ref": "<string>"
}
],
"created_at": "2023-11-07T05:31:56Z",
"output": {},
"cost": "<string>",
"metadata": {},
"callback_url": "<string>",
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}Create and dispatch a batch
Create a Batch + N child Run rows + thin batch_items junction rows.
Only binding-capable (template-backed) models support batches today — per-provider-only models return 422 on this route.
Idempotency: customers may send an Idempotency-Key request
header. Handling lives in the global IdempotencyMiddleware
(core/middleware/idempotency.py) — not this route. Same key +
same body replays the cached 201 (same batch_id, no second
batch); same key + different body returns 409 CONFLICT; absent
header falls through to first-write-wins.
curl --request POST \
--url https://api.runflow.io/v1/models/{owner}/{slug}/batches \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"input": [
{}
],
"metadata": {},
"callback_url": "<string>"
}
'{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"target_type": "<string>",
"target_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status_code": "<string>",
"items_total": 123,
"items_succeeded": 123,
"items_failed": 123,
"items_cancelled": 123,
"items": [
{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"sequence_index": 123,
"run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status_code": "<string>",
"client_ref": "<string>"
}
],
"created_at": "2023-11-07T05:31:56Z",
"output": {},
"cost": "<string>",
"metadata": {},
"callback_url": "<string>",
"started_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}Documentation Index
Fetch the complete documentation index at: https://docs.runflow.io/llms.txt
Use this file to discover all available pages before exploring further.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Body
POST body for creating a batch.
input is an array of per-item objects. Each item is validated
independently against the target model's ModelInput declarations.
Each item may carry an optional client_ref (≤255 chars, stripped
before model validation); the model's own input shape fills the rest.
Response
Successful Response
POST /batches response — batch fields + items handle list.
Shape matches the customer contract (docs/api/contracts/
batch-endpoint-api-surface.md "Response shape" section). Distinct from
Batch.FullValidator which exposes additional internal fields for
admin callers.
Show child attributes
Show child attributes
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$