Skip to main content

​
Batch Processing

AgentFlow supports synchronous completion operations and asynchronous batch jobs:
PathUse forAPI surface
Sync completionsInline work that fits in one requestPOST /api/v1/completions/run, /label, /extract, /summarize, /enrich
Async batchesLarger jobs, polling, output export, and cancellationPOST /api/v1/batches
File uploadsCSV, JSON, or JSONL uploads that create async jobsPOST /api/v1/files
Sync completions return results directly. Async batches create a job, process it in the background, and expose status and paginated output.

​
Operations

All operations accept items, model controls such as model, temperature, and max_tokens, and operation-specific fields.

​
Labeling

Labeling is the classification operation. Categories are treated as a strict enum: a single-label result must be exactly one category, and a multi-label result must only contain values from the same category set. 
POST /api/v1/completions/label

{
  "items": [
    { "content": "Customer says product is amazing but delivery was slow" },
    { "content": "Terrible experience, nothing works as advertised" }
  ],
  "categories": ["positive", "negative", "mixed"],
  "multi_label": false
}

{
  "results": [
    { "index": 0, "success": true, "result": { "label": "mixed", "confidence": 0.85 }, "error": null },
    { "index": 1, "success": true, "result": { "label": "negative", "confidence": 0.95 }, "error": null }
  ],
  "model": "openai/gpt-5.4"
}

​
Summarization

POST /api/v1/completions/summarize

{
  "items": [{ "content": "Full transcript of a 45-minute customer call..." }],
  "summary_instructions": "Summarize key decisions, action items, and risk signals. Keep under 200 words.",
  "temperature": 0.3
}

​
Extraction

POST /api/v1/completions/extract

{
  "items": [
    { "content": "Hi, I'm Sarah Chen, VP of Engineering at Acme Corp. We're migrating 500 seats by Q3." }
  ],
  "extraction_instructions": "Extract person_name, title, company, seat_count, and timeline.",
  "temperature": 0
}

​
Enrichment

POST /api/v1/completions/enrich

{
  "items": [
    {
      "content": "Enterprise SaaS company, 500 employees, Series C",
      "metadata": { "company": "Acme Corp", "industry": "Technology" }
    }
  ],
  "fields": [
    {
      "name": "company_segment",
      "type": "categorical",
      "description": "Market segment",
      "valid_values": ["enterprise", "mid-market", "smb"]
    }
  ],
  "include_context": true
}

​
General-Purpose Run

Use /completions/run when a dedicated operation does not fit. 
POST /api/v1/completions/run

{
  "operation": "feedback_analysis",
  "items": [{ "content": "Customer feedback text..." }],
  "system_prompt": "You analyze customer feedback for product teams.",
  "user_prompt_template": "Analyze this feedback:\n\n{content}\n\nReturn feature_requests and pain_points.",
  "response_format": { "type": "json_object" },
  "model": "openai/gpt-5.4-mini",
  "temperature": 0.2
}

​
Async Batches

Submit async jobs to /api/v1/batches for larger item arrays or background processing. The request accepts the same operation-specific fields as sync completions. 
POST /api/v1/batches

{
  "operation": "extract",
  "items": [
    { "content": "Sarah Chen, VP Engineering at Acme Corp, wants 500 seats by Q3." }
  ],
  "extraction_instructions": "Extract company, contact, title, seat_count, and timeline."
}
The response contains the job ID, initial status, and item count: 
{
  "id": "batch_abc123",
  "status": "queued",
  "total_items": 1
}

​
Retrieve a Job

GET /api/v1/batches/{batch_id}

{
  "id": "batch_abc123",
  "status": "processing",
  "progress": {
    "processed": 342,
    "total": 500,
    "percent": 68.4
  },
  "metadata": {
    "operation": "extract"
  }
}

​
Read Output

GET /api/v1/batches/{batch_id}/output?format=json&offset=0&limit=1000
format can be json, jsonl, or csv. JSON output is paginated with the fields returned by the backend: 
{
  "id": "batch_abc123",
  "status": "completed",
  "offset": 0,
  "limit": 1000,
  "results": [
    {
      "index": 0,
      "success": true,
      "result": { "company": "Acme Corp", "seat_count": 500 },
      "error": null
    }
  ]
}
Use format=jsonl for newline-delimited JSON or format=csv for CSV text.

​
Cancel

POST /api/v1/batches/{batch_id}/cancel
Cancellation is available for queued or running jobs.

​
File Upload

Upload CSV with headers, JSON arrays/objects, or JSONL files directly to create an async batch job. 
POST /api/v1/files
Content-Type: multipart/form-data

file=@customers.csv
operation=customer_enrichment
system_prompt=You extract structured customer details.
user_prompt_template=Extract company, contact, title, seat_count, and timeline from: {content}
response_format={"type":"json_object"}
The upload endpoint accepts multipart file plus these form fields:
FieldDescription
operationOptional semantic operation label
system_promptCustom system prompt
user_prompt_templatePrompt template that can reference item fields such as {content}
templatePredefined template name
response_formatJSON-encoded response format
modelModel ID
temperatureSampling temperature
max_tokensMaximum output tokens

​
Endpoint Summary

MethodPathDescription
POST/api/v1/completions/runGeneral-purpose synchronous completion
POST/api/v1/completions/labelSynchronous classification/labeling
POST/api/v1/completions/summarizeSynchronous summarization
POST/api/v1/completions/extractSynchronous structured extraction
POST/api/v1/completions/enrichSynchronous schema-driven enrichment
POST/api/v1/batchesSubmit an async batch job
GET/api/v1/batches/{batch_id}Get job status and progress
GET/api/v1/batches/{batch_id}/outputRead paginated output as JSON, JSONL, or CSV
POST/api/v1/batches/{batch_id}/cancelCancel a queued or running job
POST/api/v1/filesUpload a file and create a batch job