> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://docs.plextera.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.plextera.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.plextera.com/_mcp/server.

# Workflow Runs

Use workflow runs when the full process is configured in Plextera Studio and your application only needs to start it, monitor it, and consume the result.

Workflows can include Document Insights, web automation, data transformation, file handling, and custom processing steps.

## Before you start

You need:

* An API key. See [Authentication](/guides/introduction/authentication).
* A published workflow identifier provided by the workflow owner or your Plextera contact.
  This is the value used in `/workflows/{workflowId}/runs`; it can differ from the identifier in a Studio browser URL.
* The input shape expected by that workflow.
  Plextera does not validate workflow-specific input at the Public API boundary - a wrong shape is accepted initially and surfaces later as a failed run.

> **Info**
>
> Workflow input is defined by the workflow configuration. The same endpoint can accept different JSON shapes for different workflows.

---

## Start a workflow with JSON

Use JSON when the workflow trigger expects structured request data.

```bash
curl -X POST https://api.plextera.com/api/public/v1/workflows/invoice-processing/runs \
  -H "Authorization: api-key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "customer-42",
    "document": {
      "fileId": "file_01JY7M4ZVX5R1P3M3Q0TA1S7ZM"
    }
  }'
```

The response is accepted asynchronously:

```json
{
  "id": "69d224901610662a576cd7e6",
  "status": "PROCESSING",
  "workflow": {
    "id": "invoice-processing",
    "name": "Invoice Processing"
  }
}
```

---

## Start a workflow with multipart form-data

Use multipart form-data when the workflow was designed to consume form fields and uploaded files, similar to a webhook trigger.

```bash
curl -X POST https://api.plextera.com/api/public/v1/workflows/invoice-processing/runs \
  -H "Authorization: api-key YOUR_API_KEY" \
  -F "invoiceId=invoice-42" \
  -F "sourceSystem=erp" \
  -F "document=@invoice.pdf"
```

Multipart behavior:

* Text fields are forwarded under their original part names.
* JSON parts are parsed as JSON when their content type is `application/json`.
* File parts are uploaded to Plextera File Service.
* File parts are exposed to the workflow under the same part name as file-node arrays.

Part names are workflow-specific. Send the exact names that the target workflow expects.

> **Warning**
>
> Multipart input should only be used when the workflow is configured to expect form-data semantics. Otherwise, prefer JSON.

---

## Poll a workflow run

Call `GET /workflow-runs/{runId}` until the run reaches a terminal status.
Workflow runtimes vary with the configured steps.
Poll every few seconds at first, then back off to every 15-30 seconds for long-running workflows.

```bash
curl https://api.plextera.com/api/public/v1/workflow-runs/69d224901610662a576cd7e6 \
  -H "Authorization: api-key YOUR_API_KEY"
```

The response includes step-level output passed through from Plextera Studio. Nested workflow output is represented inside `steps[*].nestedRuns`. The output shape, property names, and enum casing depend on the step type and may evolve with Studio. That is why an internal value such as `APPLICATION_PDF` can appear here while typed public API fields use the standard MIME value `application/pdf`. For `document_insights` steps, `output.extractionId` is the stable correlation field - fetch the canonical, typed result with `GET /document-insights/extractions/{extractionId}`. The full Studio-native output is intentionally retained below.

```json
{
  "id": "69d224901610662a576cd7e6",
  "status": "COMPLETED",
  "workflow": {
    "id": "invoice-processing",
    "name": "Invoice Processing"
  },
  "durationMs": 146000,
  "computedDurationMs": 142000,
  "steps": [
    {
      "id": "step_01",
      "name": "Extract Invoice",
      "type": "document_insights",
      "status": "COMPLETED",
      "output": {
        "extractionId": "69654f0bc073ef404baec649",
        "fileName": "invoice.pdf",
        "fields": [
          {
            "id": "605c644cbf48241234f62121",
            "name": "vendorName",
            "type": "TEXT",
            "value": "Acme Industries Ltd"
          }
        ],
        "metaAttributes": {
          "recordId": "69654f0bc073ef404baec649"
        },
        "document": {
          "id": "69d224901610662a576cd800",
          "fileName": "invoice.pdf",
          "mimeType": "APPLICATION_PDF",
          "source": "DOCUMENT_INSIGHTS",
          "size": 126
        }
      },
      "nestedRuns": {
        "count": 0,
        "data": []
      }
    }
  ]
}
```

Terminal statuses are `COMPLETED`, `FAILED`, and `CLOSED`.

## List and filter workflow runs

Use `GET /workflow-runs` to list recent workflow runs.

```bash
curl "https://api.plextera.com/api/public/v1/workflow-runs?workflowId=invoice-processing&status=CLOSED" \
  -H "Authorization: api-key YOUR_API_KEY"
```

| Filter       | Description                                                                           |
| ------------ | ------------------------------------------------------------------------------------- |
| `workflowId` | Return runs for one workflow.                                                         |
| `status`     | Return runs in one lifecycle state: `PROCESSING`, `COMPLETED`, `FAILED`, or `CLOSED`. |

`CLOSED` is a terminal Studio state. Use it when you need to find runs that were closed in Plextera Studio.

Results are always newest first and paged with `page`/`size` (default 50, max 100).

---

## Receive workflow events

Subscribe to workflow events when your application should be notified after a run completes or fails:

* `workflow.run.completed`
* `workflow.run.failed`

For completed workflow runs, the event payload includes the full run model with step-level outputs.

Runs closed in Plextera Studio (`CLOSED`) also trigger `workflow.run.failed`; the event payload carries `status: "CLOSED"` so your handler can distinguish a closure from a processing failure.

See [Event Subscriptions](/guides/core-guides/event-subscriptions) for setup, headers, signatures, and retry behavior.

## Related reference

* [API Reference](/api/api-reference)
* [Event Reference](/api/event-reference)