Workflow Runs Migration

What You Get

Single-file runs — Each request processes one file, giving you a single WorkflowRun back instead of an array
Typed step runs — stepRuns now includes all step types (extraction, classification, splitting, etc.) with typed results, replacing the old outputs array
Cleaner request/response format — Simpler property names, unwrapped responses, predictable nullable fields
Polling helpers — createAndPoll / create_and_poll handles polling with exponential backoff

The old /workflow_runs request and response shapes from 2025-04-21 are not carried forward—you’ll need to update your integration to use the new format.

Quick Start: Common Patterns

Running a Workflow

TypeScript

Python

Java

Before (2025-04-21)

1 const response = await client.workflowRun.create({
2   workflowId: "workflow_abc123",
3   files: [{ fileUrl: "https://example.com/invoice.pdf", fileName: "invoice.pdf" }],
4   version: "3",
5   metadata: { customerId: "cust_123" }
6 });
7 if (response.success) {
8   const run = response.workflowRuns[0]; // Array of runs, one per file
9   console.log(run.outputs); // ProcessorRun[]
10 }

After (2026-02-09)

1 const run = await client.workflowRuns.create({
2   workflow: { id: "workflow_abc123", version: "3" },
3   file: { url: "https://example.com/invoice.pdf", name: "invoice.pdf" },
4   metadata: { customerId: "cust_123" }
5 });
6 console.log(run.stepRuns); // Typed StepRun[] with all step types

Using Polling Helpers

The SDK provides createAndPoll / create_and_poll methods that handle polling automatically, returning when the run reaches a terminal state (PROCESSED, FAILED, CANCELLED, NEEDS_REVIEW, or REJECTED):

TypeScript

Python

Java

1 const result = await client.workflowRuns.createAndPoll({
2   workflow: { id: "workflow_abc123" },
3   file: { url: "https://example.com/invoice.pdf" }
4 });
5 console.log(result.status);
6 console.log(result.stepRuns);

Workflow runs can take a long time. Complex workflows may run for hours. For long-running workflows, consider using webhooks instead of polling.

Processing Multiple Files

The old API accepted an array of files in a single request. The new API processes one file at a time. To process multiple files, make separate requests or use the batch endpoint:

TypeScript

Python

Before (2025-04-21) — multiple files in one request

1 const response = await client.workflowRun.create({
2   workflowId: "workflow_abc123",
3   files: [
4     { fileUrl: "https://example.com/file1.pdf" },
5     { fileUrl: "https://example.com/file2.pdf" },
6     { fileUrl: "https://example.com/file3.pdf" }
7   ]
8 });
9 const runs = response.workflowRuns; // 3 runs

After (2026-02-09) — one file per request

1 // Option 1: Separate requests
2 const run1 = await client.workflowRuns.create({
3   workflow: { id: "workflow_abc123" },
4   file: { url: "https://example.com/file1.pdf" }
5 });
6 
7 // Option 2: Batch endpoint for bulk processing
8 const batch = await client.workflowRuns.createBatch({
9   workflow: { id: "workflow_abc123" },
10   inputs: [
11     { file: { url: "https://example.com/file1.pdf" } },
12     { file: { url: "https://example.com/file2.pdf" } },
13     { file: { url: "https://example.com/file3.pdf" } }
14   ]
15 });
16 console.log(batch.batchId); // Use to track via webhooks or list endpoint

Listing Workflow Runs

TypeScript

Python

Before

1 const response = await client.workflowRun.list({
2   workflowId: "workflow_abc123",
3   status: "PROCESSED"
4 });
5 const runs = response.workflowRuns;

After

1 const response = await client.workflowRuns.list({
2   workflowId: "workflow_abc123",
3   status: "PROCESSED"
4 });
5 const runs = response.data;

Getting a Workflow Run

TypeScript

Python

Before

1 const response = await client.workflowRun.get("workflow_run_abc123");
2 const run = response.workflowRun;
3 console.log(run.outputs);

After

1 const run = await client.workflowRuns.retrieve("workflow_run_abc123");
2 console.log(run.stepRuns);

Using Raw Text Instead of Files

TypeScript

Python

Before (2025-04-21)

1 const response = await client.workflowRun.create({
2   workflowId: "workflow_abc123",
3   rawTexts: ["Invoice #123\nVendor: Acme Corp\nTotal: $500"]
4 });

After (2026-02-09)

1 const run = await client.workflowRuns.create({
2   workflow: { id: "workflow_abc123" },
3   file: { text: "Invoice #123\nVendor: Acme Corp\nTotal: $500" }
4 });

Endpoint Changes Summary

Old Endpoint	New Endpoint	Notes
`POST /workflow_runs`	`POST /workflow_runs`	Request/response shape changed significantly
`GET /workflow_runs`	`GET /workflow_runs`	Response shape changed
`GET /workflow_runs/{workflowRunId}`	`GET /workflow_runs/{id}`	Path param renamed
`POST /workflow_runs/{workflowRunId}`	`POST /workflow_runs/{id}`	Path param renamed
`DELETE /workflow_runs/{workflowRunId}`	`DELETE /workflow_runs/{id}`	Path param renamed, response simplified
`POST /workflow_runs/{workflowRunId}/cancel`	`POST /workflow_runs/{id}/cancel`	Path param renamed
`POST /workflow_runs/{workflowRunId}/outputs/{outputId}`	(removed)	Correct Outputs endpoint removed
`POST /workflow_runs/batch`	`POST /workflow_runs/batch`	Request shape changed

Request Changes

File Properties (All Endpoints)

Old	New
`fileUrl`	`url`
`fileId`	`id`
`fileName`	`name`
`rawTexts` (array)	`file.text` (single string via `FileFromText`)

Creating a Workflow Run

Old	New	Notes
`workflowId`	`workflow.id`	Nested in `workflow` object
`version`	`workflow.version`	Nested in `workflow` object
`files` (array)	`file` (single object)	One file per request. Use batch endpoint for multiple files
`files[].fileUrl`	`file.url`	Renamed
`files[].fileId`	`file.id`	Renamed
`files[].fileName`	`file.name`	Renamed
`rawTexts`	`file.text`	Use `FileFromText` input
`files[].outputs`	`outputs`	Moved to top-level
`files[].outputs[].processorId`	`outputs[].processorId`	Now references extractor/classifier/splitter IDs (e.g., `ex_`, `cl_`, `sp_` prefixed)
—	`secrets`	New. Pass secrets to processors in the workflow

Breaking change: The files array has been replaced with a single file object. If you previously processed multiple files in one request, you’ll need to either make separate requests or use the Batch Run Workflow endpoint.

Example: Create Request

1 {
2   "workflowId": "workflow_abc123",
3   "version": "3",
4   "files": [
5     {
6       "fileUrl": "https://example.com/invoice.pdf",
7       "fileName": "invoice.pdf"
8     }
9   ],
10   "metadata": { "customerId": "cust_123" }
11 }

Batch Run Request

1 {
2   "workflowId": "workflow_abc123",
3   "version": "2",
4   "inputs": [
5     {
6       "file": { "fileUrl": "https://example.com/file1.pdf", "fileName": "file1.pdf" },
7       "metadata": { "source": "upload" }
8     },
9     {
10       "rawText": "Raw invoice data here...",
11       "metadata": { "source": "email" }
12     }
13   ]
14 }

Response Changes

Response shape changes: Single object responses are now returned directly (no wrapper key), and list responses use { "object": "list", "data": [...] } format. See Simplified Response Shapes for details.

Key Differences

Old	New	Notes
`success: true`	(removed)	Use HTTP status codes
`{ workflowRuns: [...] }` (create)	Direct `WorkflowRun` object	Single file = single response
`{ workflowRun: {...} }` (get/update)	Direct `WorkflowRun` object	Unwrapped
`{ workflowRuns: [...] }` (list)	`{ object: "list", data: [...] }`	Standardized list format
`run.url`	`run.dashboardUrl`	Renamed
`run.name`	(removed)	No longer on the run object
`run.workflow` (flat object)	`run.workflow` + `run.workflowVersion`	Split into two objects
`run.workflow.version`	`run.workflowVersion.version`	Moved to separate object
`run.outputs` (ProcessorRun[])	(removed)	Replaced by `stepRuns`
`run.stepRuns` (validation only)	`run.stepRuns` (all step types)	Now includes extraction, classification, splitting, etc.
`run.reviewedBy`	`run.reviewedByUser`	Renamed
Optional fields (may be absent)	Required but nullable (always present)	Predictable response shape

Example: Create Response

1 {
2   "success": true,
3   "workflowRuns": [
4     {
5       "object": "workflow_run",
6       "id": "workflow_run_abc123",
7       "name": "invoice.pdf",
8       "url": "https://dashboard.extend.ai/workflows/workflow_abc?workflowRunId=workflow_run_abc123",
9       "status": "PENDING",
10       "metadata": {},
11       "batchId": "batch_xyz",
12       "files": [{ "id": "file_123", "name": "invoice.pdf", "type": "PDF" }],
13       "outputs": [],
14       "stepRuns": [],
15       "workflow": {
16         "object": "workflow",
17         "id": "workflow_abc",
18         "version": "3",
19         "name": "Invoice Processing"
20       }
21     }
22   ]
23 }

Example: Completed Response with Step Runs

The biggest change is how processor results are returned. Previously, results lived in the outputs array as ProcessorRun objects. Now, results are in stepRuns as typed StepRun objects:

1 {
2   "success": true,
3   "workflowRun": {
4     "id": "workflow_run_abc123",
5     "status": "PROCESSED",
6     "outputs": [
7       {
8         "object": "document_processor_run",
9         "id": "dpr_extract1",
10         "type": "EXTRACT",
11         "status": "PROCESSED",
12         "output": {
13           "value": { "vendorName": "Acme Corp", "total": 500.00 }
14         }
15       },
16       {
17         "object": "document_processor_run",
18         "id": "dpr_classify1",
19         "type": "CLASSIFY",
20         "status": "PROCESSED",
21         "output": {
22           "type": "INVOICE",
23           "confidence": 0.98
24         }
25       }
26     ],
27     "stepRuns": []
28   }
29 }

Example: List Response

1 {
2   "success": true,
3   "workflowRuns": [
4     {
5       "id": "workflow_run_abc123",
6       "status": "PROCESSED",
7       "workflowId": "workflow_abc",
8       "workflowName": "Invoice Processing",
9       "workflowVersionId": "workflow_version_xyz",
10       "createdAt": "2024-03-21T15:29:55Z",
11       "updatedAt": "2024-03-21T16:45:00Z"
12     }
13   ],
14   "nextPageToken": "..."
15 }

Example: Delete Response

1 {
2   "success": true,
3   "workflowRunId": "workflow_run_abc123",
4   "message": "Workflow run data has been successfully deleted."
5 }

Removed Endpoint: Correct Workflow Run Outputs

The POST /workflow_runs/{workflowRunId}/outputs/{outputId} endpoint for submitting corrected outputs has been removed. This was deprecated in the 2025-04-21 API.

SDK Method Reference

Old Method	New Method
`client.workflowRun.create()`	`client.workflowRuns.create()`
`client.workflowRun.get()`	`client.workflowRuns.retrieve()`
`client.workflowRun.list()`	`client.workflowRuns.list()`
`client.workflowRun.update()`	`client.workflowRuns.update()`
`client.workflowRun.delete()`	`client.workflowRuns.delete()`
`client.workflowRun.cancel()`	`client.workflowRuns.cancel()`
`client.batchWorkflowRun.create()`	`client.workflowRuns.createBatch()`
`client.workflowRunOutput.update()`	(removed)
—	`client.workflowRuns.createAndPoll()` (new)

Detailed Schema Changes

WorkflowRun Schema

Property	Old (2025-04-21)	New (2026-02-09)	Change
`object`	`"workflow_run"`	`"workflow_run"`	No change
`id`	Required `string`	Required `string`	No change
`name`	Required `string`	—	Removed
`url`	Required `string`	—	Renamed to `dashboardUrl`
`dashboardUrl`	—	Required `string`	New (replaces `url`)
`status`	Required	Required	No change
`metadata`	Optional `JsonObject`	Required `RunMetadata`	Now required
`batchId`	Optional `string`	Required but nullable `string`	Now required
`files`	Required `File[]`	Required `FileSummary[]`	Simplified file objects
`workflow`	`Workflow` (with `version`)	`WorkflowSummary` (no `version`)	Split into two fields
`workflowVersion`	—	Required `WorkflowVersionSummary`	New (version info moved here)
`outputs`	Required `ProcessorRun[]`	—	Removed. Use `stepRuns`
`stepRuns`	Required (validation types only)	Required (all step types)	Expanded. Now includes PARSE, EXTRACT, CLASSIFY, SPLIT, MERGE_EXTRACT, CONDITIONAL_EXTRACT, RULE_VALIDATION, and EXTERNAL_DATA_VALIDATION
`failureReason`	Optional `string`	Required but nullable `string`	Now required
`failureMessage`	Optional `string`	Required but nullable `string`	Now required
`initialRunAt`	Required `date-time`	Required but nullable `date-time`	Now nullable
`reviewedBy`	Optional `string`	—	Renamed to `reviewedByUser`
`reviewedByUser`	—	Required but nullable `string`	New (replaces `reviewedBy`)
`reviewed`	Required `boolean`	Required `boolean`	No change
`rejectionNote`	Optional `string`	Required but nullable `string`	Now required
`reviewedAt`	Optional `date-time`	Required but nullable `date-time`	Now required
`startTime`	Optional `date-time`	Required but nullable `date-time`	Now required
`endTime`	Optional `date-time`	Required but nullable `date-time`	Now required
`usage`	Optional `WorkflowRunCredits`	Required but nullable `RunUsage`	Now required, type changed

WorkflowRunSummary Schema (List Response)

Property	Old (2025-04-21)	New (2026-02-09)	Change
`object`	—	`"workflow_run"`	New
`id`	Required `string`	Required `string`	No change
`status`	Required	Required	No change
`workflowId`	Required `string`	—	Removed, see `workflow.id`
`workflowName`	Required `string`	—	Removed, see `workflow.name`
`workflowVersionId`	Required `string`	—	Removed, see `workflowVersion.id`
`workflow`	—	Required `WorkflowSummary`	New
`workflowVersion`	—	Required `WorkflowVersionSummary`	New
`dashboardUrl`	—	Required `string`	New
`createdAt`	Required `date-time`	Required `date-time`	No change
`updatedAt`	Required `date-time`	Required `date-time`	No change
`reviewedByUser`	Optional `string`	Required but nullable `string`	Now required
`reviewedAt`	Optional `date-time`	Required but nullable `date-time`	Now required
`initialRunAt`	Optional `date-time`	Required `date-time`	Now required
`startTime`	Optional `date-time`	Required `date-time`	Now required
`endTime`	Optional `date-time`	Required `date-time`	Now required
`batchId`	—	Required but nullable `string`	New
`rejectionNote`	—	Required but nullable `string`	New
`usage`	—	Required but nullable `RunUsage`	New

StepRun Schema

Old (2025-04-21)	New (2026-02-09)
Simple object type	Discriminated union (`oneOf`)
`step.type`: `EXTERNAL_DATA_VALIDATION`, `RULE_VALIDATION` only	`step.type`: `PARSE`, `EXTRACT`, `CLASSIFY`, `SPLIT`, `MERGE_EXTRACT`, `CONDITIONAL_EXTRACT`, `RULE_VALIDATION`, `EXTERNAL_DATA_VALIDATION`
`output` field	`result` field (typed per step type)
No `workflowRunId`	`workflowRunId` included
No `files`	`files` array included
Status: `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELLED`	Status: adds `WAITING`

Need Help?

If you encounter any issues while migrating, please contact our support team at support@extend.app.

Migration Guides

Guide	Migrating From	Migrating To
Overview	—	What’s new and how to upgrade
Extract Runs	`/processor_runs`	`/extract_runs` + `/extract`
Classify Runs	`/processor_runs`	`/classify_runs` + `/classify`
Split Runs	`/processor_runs`	`/split_runs` + `/split`
Parse Runs	`/parse`, `/parse/async`	`/parse_runs` + `/parse`
Edit Runs	`/edit`, `/edit/async`	`/edit_runs` + `/edit`
Extractors	`/processors`	`/extractors`
Classifiers	`/processors`	`/classifiers`
Splitters	`/processors`	`/splitters`
Files	`/files`	`/files` (breaking changes)
Evaluation Sets	evaluation endpoints	Updated evaluation endpoints
Workflow Runs	`/workflow_runs`	`/workflow_runs` (breaking changes)
Webhooks	`processor_run.*` events	`extract_run.`, `classify_run.`, etc.