--- title: Create a new workflow instance --- [Skip to content](#_top) [API Reference](https://developers.cloudflare.com/api) [Workflows](https://developers.cloudflare.com/api/resources/workflows) [Instances](https://developers.cloudflare.com/api/resources/workflows/subresources/instances) Copy Markdown Open in **Claude**Open in **ChatGPT**Open in **Cursor** --- **Copy Markdown****View as Markdown** # Create a new workflow instance POST/accounts/{account\_id}/workflows/{workflow\_name}/instances Creates a new instance of a workflow, starting its execution. ##### Security
API Token The preferred authorization scheme for interacting with the Cloudflare API. Create a token. **Example:**Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY
API Email + API Key The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key. **Example:**X-Auth-Email: user@example.com The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys. **Example:**X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194
##### Accepted Permissions (at least one required) `Workers Scripts Write` ##### P ath ParametersExpand Collapse account\_id: string [Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(params)%20default%20%3E%20(param)%20account_id%20%3E%20(schema)>) workflow\_name: string maxLength64 minLength1 [Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(params)%20default%20%3E%20(param)%20workflow_name%20%3E%20(schema)>) ##### Body ParametersJSONExpand Collapse instance\_id: optional string The system reserves IDs that consist of the `cf_` prefix and exactly 64 lowercase hexadecimal characters. maximum100 minimum1 [Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20instance_id%20%3E%20(schema)>)
instance\_retention: optional object {error\_retention, success\_retention }
error\_retention: optional numberor string Specifies the duration in milliseconds or as a string like ‘5 minutes’. One of the following: number Specifies the duration in milliseconds. Link to this property string Link to this property
Link to this property
success\_retention: optional numberor string Specifies the duration in milliseconds or as a string like ‘5 minutes’. One of the following: number Specifies the duration in milliseconds. Link to this property string Link to this property
Link to this property
[Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20instance_retention%20%3E%20(schema)>)
location\_hint: optional "wnam"or "weur"or "enam"or 8 more One of the following: "wnam" Link to this property "weur" Link to this property "enam" Link to this property "eeur" Link to this property "apac" Link to this property "apac-ne" Link to this property "apac-se" Link to this property "oc" Link to this property "sam" Link to this property "afr" Link to this property "me" Link to this property
[Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20location_hint%20%3E%20(schema)>) params: optional string JSON-encoded event payload passed into the new instance. [Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(params)%200%20%3E%20(param)%20params%20%3E%20(schema)>) ##### ReturnsExpand Collapse
errors: array of object {code, message } code: number Link to this property message: string Link to this property
[Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(network%20schema)%20%3E%20(property)%20errors>)
messages: array of object {code, message } code: number Link to this property message: string Link to this property
[Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(network%20schema)%20%3E%20(property)%20messages>)
result: object {id, status, version\_id, 2 more } id: string maxLength100 minLength1 Link to this property
status: "queued"or "running"or "paused"or 6 more One of the following: "queued" Link to this property "running" Link to this property "paused" Link to this property "errored" Link to this property "terminated" Link to this property "complete" Link to this property "waitingForPause" Link to this property "waiting" Link to this property "rollingBack" Link to this property
Link to this property version\_id: string formatuuid Link to this property workflow\_id: string formatuuid Link to this property
trigger\_source: optional "unknown"or "api"or "binding"or 2 more One of the following: "unknown" Link to this property "api" Link to this property "binding" Link to this property "event" Link to this property "cron" Link to this property
Link to this property
[Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(network%20schema)%20%3E%20(property)%20result>) success: true [Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(network%20schema)%20%3E%20(property)%20success>)
result\_info: optional object {count, per\_page, total\_count, 3 more } count: number Link to this property per\_page: number Link to this property total\_count: number Link to this property cursor: optional string Link to this property page: optional number Link to this property total\_pages: optional number Link to this property
[Link to this property](<#(resource)%20workflows.instances%20%3E%20(method)%20create%20%3E%20(network%20schema)%20%3E%20(property)%20result_info>) ### Create a new workflow instance HTTP HTTPTypeScriptPythonGoTerraform ``` curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workflows/$WORKFLOW_NAME/instances \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \ -d '{}' ``` 200 example ``` { "errors": [], "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 } } ``` ##### Returns Examples 200 example ``` { "errors": [], "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 } } ```