Workflows

Workflow management and execution endpoints

Timeouts for Synchronous API Calls

A workflow run via the API is synchronous — there is no separate status or polling endpoint. The request stays open until the workflow finishes or an infrastructure timeout occurs, typically around five minutes. Plan workflows meant for API calls to finish well within that window, or trigger them asynchronously via an external automation (e.g. Make) that checks completion separately.

Uploading additional documents per run

You can attach additional documents to a workflow run (multipart/form-data request, max. 10 files, max. 50 MB per file — the same check as for assistant runs; details in the API reference).

Document output response

When a workflow's output format produces a document (e.g. DOCX, PDF, PPTX, or a table/Excel output), the response from POST /workflows/v1/{workflowId}/run does not contain the file itself. Instead, the documentUrl field returns a signed download link valid for approximately one hour. To retrieve the actual file, make a separate GET request to that documentUrl - only that response contains the file bytes, with the correct Content-Type and Content-Disposition.

Automations (e.g. Power Automate, Make, n8n) that want to save or forward the generated document therefore need two steps: trigger the workflow run and read documentUrl from the response, then download the file via a second HTTP GET step. Because the link expires after about an hour, this second step should happen promptly and should not be part of a long-running, multi-hour approval process.

Steps without an answer (422)

A step that produces no text fails the run with 422 instead of returning an empty content string. The message names the step number and the reason:

• The step used up its 20 tool-calling steps without answering — usually too much work in one step, or attachments large enough that the model spends the budget searching them. Split the step or attach smaller files.
• The step reached the model's output limit before writing any text.

Practical Usage

• Create and test workflows: /platform/workflows-create
• Use workflows in the platform: /platform/workflows
• Set up authentication before API calls: /api/authentication