# Instances ## List of workflow instances `client.workflows.instances.list(stringworkflowName, InstanceListParamsparams, RequestOptionsoptions?): V4PagePaginationArray` **get** `/accounts/{account_id}/workflows/{workflow_name}/instances` Lists all instances of a workflow with their execution status. ### Parameters - `workflowName: string` - `params: InstanceListParams` - `account_id: string` Path param - `cursor?: string` Query param: Opaque token for cursor-based pagination. Mutually exclusive with `page`. - `date_end?: string` Query param: Accepts ISO 8601 with no timezone offsets and in UTC. - `date_start?: string` Query param: Accepts ISO 8601 with no timezone offsets and in UTC. - `direction?: "asc" | "desc"` Query param: Defines the direction for cursor-based pagination. - `"asc"` - `"desc"` - `page?: number` Query param: Deprecated: use `cursor` for pagination instead. - `per_page?: number` Query param - `status?: "queued" | "running" | "paused" | 6 more` Query param - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` ### Returns - `InstanceListResponse` - `id: string` - `created_on: string` - `ended_on: string | null` - `modified_on: string` - `started_on: string | null` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `version_id: string` - `workflow_id: string` - `trigger_source?: "unknown" | "api" | "binding" | 2 more` - `"unknown"` - `"api"` - `"binding"` - `"event"` - `"cron"` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const instanceListResponse of client.workflows.instances.list('x', { account_id: 'account_id', })) { console.log(instanceListResponse.id); } ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "result": [ { "id": "x", "created_on": "2019-12-27T18:11:19.117Z", "ended_on": "2019-12-27T18:11:19.117Z", "modified_on": "2019-12-27T18:11:19.117Z", "started_on": "2019-12-27T18:11:19.117Z", "status": "queued", "version_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "workflow_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "trigger_source": "unknown" } ], "success": true, "result_info": { "count": 0, "per_page": 0, "total_count": 0, "cursor": "cursor", "page": 0, "total_pages": 0 } } ``` ## Get logs and status from instance `client.workflows.instances.get(stringinstanceID, InstanceGetParamsparams, RequestOptionsoptions?): InstanceGetResponse` **get** `/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}` Retrieves logs and execution status for a specific workflow instance. ### Parameters - `instanceID: string` Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression. - `params: InstanceGetParams` - `account_id: string` Path param - `workflow_name: string` Path param - `order?: "asc" | "desc"` Query param: Step ordering: "asc" (default, oldest first) or "desc" (newest first). - `"asc"` - `"desc"` - `simple?: "true" | "false"` Query param: When true, omits step details and returns only metadata with step_count. - `"true"` - `"false"` ### Returns - `InstanceGetResponse` - `end: string | null` - `error: Error | null` - `message: string` - `name: string` - `output: string | number` - `string` - `number` - `params: unknown` - `queued: string` - `rollback: Rollback | null` - `error: Error | null` - `message: string` - `name: string` - `outcome: "complete" | "failed"` - `"complete"` - `"failed"` - `start: string | null` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `step_count: number` - `steps: Array` - `UnionMember0` - `attempts: Array` - `end: string | null` - `error: Error | null` - `message: string` - `name: string` - `start: string` - `success: boolean | null` - `config: Config` - `retries: Retries` - `delay: string | number` Specifies the delay duration. '[dynamic]' indicates the delay is computed by a user-supplied function. - `string` - `number` - `limit: number` - `backoff?: "constant" | "linear" | "exponential"` - `"constant"` - `"linear"` - `"exponential"` - `timeout: string | number` Specifies the timeout duration. - `string` - `number` - `sensitive?: "output"` When set to 'output', step output is redacted from log and step output responses. - `"output"` - `end: string | null` - `name: string` - `output: string | null` - `start: string` - `success: boolean | null` - `type: "step" | "rollback"` - `"step"` - `"rollback"` - `UnionMember1` - `end: string` - `error: Error | null` - `message: string` - `name: string` - `finished: boolean` - `name: string` - `start: string` - `type: "sleep"` - `"sleep"` - `UnionMember2` - `trigger: Trigger` - `source: string` - `type: "termination"` - `"termination"` - `UnionMember3` - `end: string` - `error: Error | null` - `message: string` - `name: string` - `finished: boolean` - `name: string` - `start: string` - `type: "waitForEvent"` - `"waitForEvent"` - `output?: string` - `success: boolean | null` - `trigger: Trigger` - `source: "unknown" | "api" | "binding" | 2 more` - `"unknown"` - `"api"` - `"binding"` - `"event"` - `"cron"` - `versionId: string` - `schedule?: Schedule` - `cron: string` - `scheduledTime: number` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const instance = await client.workflows.instances.get('x', { account_id: 'account_id', workflow_name: 'x', }); console.log(instance.end); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "result": { "end": "2019-12-27T18:11:19.117Z", "error": { "message": "message", "name": "name" }, "output": "string", "params": {}, "queued": "2019-12-27T18:11:19.117Z", "rollback": { "error": { "message": "message", "name": "name" }, "outcome": "complete" }, "start": "2019-12-27T18:11:19.117Z", "status": "queued", "step_count": 0, "steps": [ { "attempts": [ { "end": "2019-12-27T18:11:19.117Z", "error": { "message": "message", "name": "name" }, "start": "2019-12-27T18:11:19.117Z", "success": true } ], "config": { "retries": { "delay": "string", "limit": 0, "backoff": "constant" }, "timeout": "string", "sensitive": "output" }, "end": "2019-12-27T18:11:19.117Z", "name": "name", "output": "output", "start": "2019-12-27T18:11:19.117Z", "success": true, "type": "step" } ], "success": true, "trigger": { "source": "unknown" }, "versionId": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "schedule": { "cron": "cron", "scheduledTime": 0 } }, "success": true, "result_info": { "count": 0, "per_page": 0, "total_count": 0, "cursor": "cursor", "page": 0, "total_pages": 0 } } ``` ## Create a new workflow instance `client.workflows.instances.create(stringworkflowName, InstanceCreateParamsparams, RequestOptionsoptions?): InstanceCreateResponse` **post** `/accounts/{account_id}/workflows/{workflow_name}/instances` Creates a new instance of a workflow, starting its execution. ### Parameters - `workflowName: string` - `params: InstanceCreateParams` - `account_id: string` Path param - `instance_id?: string` Body param - `instance_retention?: InstanceRetention` Body param - `error_retention?: number | string` Specifies the duration in milliseconds or as a string like '5 minutes'. - `number` - `string` - `success_retention?: number | string` Specifies the duration in milliseconds or as a string like '5 minutes'. - `number` - `string` - `params?: unknown` Body param ### Returns - `InstanceCreateResponse` - `id: string` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `version_id: string` - `workflow_id: string` - `trigger_source?: "unknown" | "api" | "binding" | 2 more` - `"unknown"` - `"api"` - `"binding"` - `"event"` - `"cron"` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const instance = await client.workflows.instances.create('x', { account_id: 'account_id' }); console.log(instance.id); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "result": { "id": "x", "status": "queued", "version_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "workflow_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "trigger_source": "unknown" }, "success": true, "result_info": { "count": 0, "per_page": 0, "total_count": 0, "cursor": "cursor", "page": 0, "total_pages": 0 } } ``` ## Batch create new Workflow instances `client.workflows.instances.bulk(stringworkflowName, InstanceBulkParamsparams, RequestOptionsoptions?): SinglePage` **post** `/accounts/{account_id}/workflows/{workflow_name}/instances/batch` Creates multiple workflow instances in a single batch operation. ### Parameters - `workflowName: string` - `params: InstanceBulkParams` - `account_id: string` Path param - `body?: Array` Body param - `instance_id?: string` - `instance_retention?: InstanceRetention` - `error_retention?: number | string` Specifies the duration in milliseconds or as a string like '5 minutes'. - `number` - `string` - `success_retention?: number | string` Specifies the duration in milliseconds or as a string like '5 minutes'. - `number` - `string` - `params?: unknown` ### Returns - `InstanceBulkResponse` - `id: string` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `version_id: string` - `workflow_id: string` - `trigger_source?: "unknown" | "api" | "binding" | 2 more` - `"unknown"` - `"api"` - `"binding"` - `"event"` - `"cron"` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const instanceBulkResponse of client.workflows.instances.bulk('x', { account_id: 'account_id', })) { console.log(instanceBulkResponse.id); } ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "result": [ { "id": "x", "status": "queued", "version_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "workflow_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", "trigger_source": "unknown" } ], "success": true, "result_info": { "count": 0, "per_page": 0, "total_count": 0, "cursor": "cursor", "page": 0, "total_pages": 0 } } ``` ## Get full step output from instance `client.workflows.instances.step(stringinstanceID, InstanceStepParamsparams, RequestOptionsoptions?): InstanceStepResponse` **get** `/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/step` Retrieves the full, untruncated output for a specific step on a workflow instance. Returns a flat status-shaped JSON body with step `status` ('running' | 'waiting' | 'complete' | 'errored'), `error` (nullable), and `output` (the step value, or null while running/waiting/errored). When the step returned a ReadableStream from step.do, the response is served as 'application/octet-stream' with the raw bytes as the body instead of JSON. A `status='running'` response with non-null `error` indicates the step is currently retrying after a prior attempt failed. ### Parameters - `instanceID: string` Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression. - `params: InstanceStepParams` - `account_id: string` Path param - `workflow_name: string` Path param - `name: string` Query param: Exact step name from the instance logs response, including the generated counter suffix. - `type: "step" | "waitForEvent"` Query param: Step type to disambiguate step.do and waitForEvent entries that share the same name. - `"step"` - `"waitForEvent"` - `attempt?: number` Query param: Specific attempt number to retrieve output or error for. ### Returns - `InstanceStepResponse` - `error: Error | null` Error details when status='errored'; null otherwise. - `message: string` - `name: string` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `output?: unknown` Full step output or waitForEvent payload without truncation. Sensitive outputs are returned as '[REDACTED]'. Populated when status='complete'. May be a ReadableStream when the step returned one from step.do; stream outputs are served as application/octet-stream rather than JSON. ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const response = await client.workflows.instances.step('x', { account_id: 'account_id', workflow_name: 'x', name: 'x', type: 'step', }); console.log(response.error); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "result": { "error": { "message": "message", "name": "name" }, "status": "queued", "output": {} }, "success": true, "result_info": { "count": 0, "per_page": 0, "total_count": 0, "cursor": "cursor", "page": 0, "total_pages": 0 } } ``` ## Domain Types ### Instance List Response - `InstanceListResponse` - `id: string` - `created_on: string` - `ended_on: string | null` - `modified_on: string` - `started_on: string | null` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `version_id: string` - `workflow_id: string` - `trigger_source?: "unknown" | "api" | "binding" | 2 more` - `"unknown"` - `"api"` - `"binding"` - `"event"` - `"cron"` ### Instance Get Response - `InstanceGetResponse` - `end: string | null` - `error: Error | null` - `message: string` - `name: string` - `output: string | number` - `string` - `number` - `params: unknown` - `queued: string` - `rollback: Rollback | null` - `error: Error | null` - `message: string` - `name: string` - `outcome: "complete" | "failed"` - `"complete"` - `"failed"` - `start: string | null` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `step_count: number` - `steps: Array` - `UnionMember0` - `attempts: Array` - `end: string | null` - `error: Error | null` - `message: string` - `name: string` - `start: string` - `success: boolean | null` - `config: Config` - `retries: Retries` - `delay: string | number` Specifies the delay duration. '[dynamic]' indicates the delay is computed by a user-supplied function. - `string` - `number` - `limit: number` - `backoff?: "constant" | "linear" | "exponential"` - `"constant"` - `"linear"` - `"exponential"` - `timeout: string | number` Specifies the timeout duration. - `string` - `number` - `sensitive?: "output"` When set to 'output', step output is redacted from log and step output responses. - `"output"` - `end: string | null` - `name: string` - `output: string | null` - `start: string` - `success: boolean | null` - `type: "step" | "rollback"` - `"step"` - `"rollback"` - `UnionMember1` - `end: string` - `error: Error | null` - `message: string` - `name: string` - `finished: boolean` - `name: string` - `start: string` - `type: "sleep"` - `"sleep"` - `UnionMember2` - `trigger: Trigger` - `source: string` - `type: "termination"` - `"termination"` - `UnionMember3` - `end: string` - `error: Error | null` - `message: string` - `name: string` - `finished: boolean` - `name: string` - `start: string` - `type: "waitForEvent"` - `"waitForEvent"` - `output?: string` - `success: boolean | null` - `trigger: Trigger` - `source: "unknown" | "api" | "binding" | 2 more` - `"unknown"` - `"api"` - `"binding"` - `"event"` - `"cron"` - `versionId: string` - `schedule?: Schedule` - `cron: string` - `scheduledTime: number` ### Instance Create Response - `InstanceCreateResponse` - `id: string` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `version_id: string` - `workflow_id: string` - `trigger_source?: "unknown" | "api" | "binding" | 2 more` - `"unknown"` - `"api"` - `"binding"` - `"event"` - `"cron"` ### Instance Bulk Response - `InstanceBulkResponse` - `id: string` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `version_id: string` - `workflow_id: string` - `trigger_source?: "unknown" | "api" | "binding" | 2 more` - `"unknown"` - `"api"` - `"binding"` - `"event"` - `"cron"` ### Instance Step Response - `InstanceStepResponse` - `error: Error | null` Error details when status='errored'; null otherwise. - `message: string` - `name: string` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `output?: unknown` Full step output or waitForEvent payload without truncation. Sensitive outputs are returned as '[REDACTED]'. Populated when status='complete'. May be a ReadableStream when the step returned one from step.do; stream outputs are served as application/octet-stream rather than JSON. # Status ## Change status of instance `client.workflows.instances.status.edit(stringinstanceID, StatusEditParamsparams, RequestOptionsoptions?): StatusEditResponse` **patch** `/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/status` Changes the execution status of a workflow instance (e.g., pause, resume, terminate). ### Parameters - `instanceID: string` Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression. - `StatusEditParams = Variant0 | Variant1 | Variant2 | Variant3` - `StatusEditParamsBase` - `account_id: string` Path param - `workflow_name: string` Path param - `status: "pause"` Body param - `"pause"` - `Variant0 extends StatusEditParamsBase` - `Variant1 extends StatusEditParamsBase` - `Variant2 extends StatusEditParamsBase` - `Variant3 extends StatusEditParamsBase` ### Returns - `StatusEditResponse` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `timestamp: string` Accepts ISO 8601 with no timezone offsets and in UTC. ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const response = await client.workflows.instances.status.edit('x', { account_id: 'account_id', workflow_name: 'x', status: 'pause', }); console.log(response.status); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "result": { "status": "queued", "timestamp": "2019-12-27T18:11:19.117Z" }, "success": true, "result_info": { "count": 0, "per_page": 0, "total_count": 0, "cursor": "cursor", "page": 0, "total_pages": 0 } } ``` ## Domain Types ### Status Edit Response - `StatusEditResponse` - `status: "queued" | "running" | "paused" | 6 more` - `"queued"` - `"running"` - `"paused"` - `"errored"` - `"terminated"` - `"complete"` - `"waitingForPause"` - `"waiting"` - `"rollingBack"` - `timestamp: string` Accepts ISO 8601 with no timezone offsets and in UTC. # Events ## Send event to instance `client.workflows.instances.events.create(stringeventType, EventCreateParamsparams, RequestOptionsoptions?): EventCreateResponse` **post** `/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}/events/{event_type}` Sends an event to a running workflow instance to trigger state transitions. ### Parameters - `eventType: string` - `params: EventCreateParams` - `account_id: string` Path param - `workflow_name: string` Path param - `instance_id: string` Path param: Instance identifier. User-created instances match `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$` (max 100 characters); cron-triggered instances can use a longer, system-generated id derived from the cron expression. - `body?: unknown` Body param ### Returns - `EventCreateResponse = unknown` ### Example ```typescript import Cloudflare from 'cloudflare'; const client = new Cloudflare({ apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted }); const event = await client.workflows.instances.events.create('x', { account_id: 'account_id', workflow_name: 'x', instance_id: 'x', }); console.log(event); ``` #### Response ```json { "errors": [ { "code": 0, "message": "message" } ], "messages": [ { "code": 0, "message": "message" } ], "success": true, "result": {}, "result_info": { "count": 0, "per_page": 0, "total_count": 0, "cursor": "cursor", "page": 0, "total_pages": 0 } } ``` ## Domain Types ### Event Create Response - `EventCreateResponse = unknown`