# Instances

## List of workflow instances

`workflows.instances.list(strworkflow_name, InstanceListParams**kwargs)  -> SyncV4PagePaginationArray[InstanceListResponse]`

**get** `/accounts/{account_id}/workflows/{workflow_name}/instances`

Lists all instances of a workflow with their execution status.

### Parameters

- `account_id: str`

- `workflow_name: str`

- `cursor: Optional[str]`

  `page` and `cursor` are mutually exclusive, use one or the other.

- `date_end: Optional[Union[str, datetime]]`

  Accepts ISO 8601 with no timezone offsets and in UTC.

- `date_start: Optional[Union[str, datetime]]`

  Accepts ISO 8601 with no timezone offsets and in UTC.

- `direction: Optional[Literal["asc", "desc"]]`

  should only be used when `cursor` is used, defines a new direction for the cursor

  - `"asc"`

  - `"desc"`

- `page: Optional[float]`

  `page` and `cursor` are mutually exclusive, use one or the other.

- `per_page: Optional[float]`

- `status: Optional[Literal["queued", "running", "paused", 5 more]]`

  - `"queued"`

  - `"running"`

  - `"paused"`

  - `"errored"`

  - `"terminated"`

  - `"complete"`

  - `"waitingForPause"`

  - `"waiting"`

### Returns

- `class InstanceListResponse: …`

  - `id: str`

  - `created_on: datetime`

  - `ended_on: Optional[datetime]`

  - `modified_on: datetime`

  - `started_on: Optional[datetime]`

  - `status: Literal["queued", "running", "paused", 5 more]`

    - `"queued"`

    - `"running"`

    - `"paused"`

    - `"errored"`

    - `"terminated"`

    - `"complete"`

    - `"waitingForPause"`

    - `"waiting"`

  - `version_id: str`

  - `workflow_id: str`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
page = client.workflows.instances.list(
    workflow_name="x",
    account_id="account_id",
)
page = page.result[0]
print(page.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"
    }
  ],
  "success": true,
  "result_info": {
    "count": 0,
    "per_page": 0,
    "total_count": 0,
    "cursor": "cursor",
    "page": 0
  }
}
```

## Get logs and status from instance

`workflows.instances.get(strinstance_id, InstanceGetParams**kwargs)  -> InstanceGetResponse`

**get** `/accounts/{account_id}/workflows/{workflow_name}/instances/{instance_id}`

Retrieves logs and execution status for a specific workflow instance.

### Parameters

- `account_id: str`

- `workflow_name: str`

- `instance_id: str`

- `order: Optional[Literal["asc", "desc"]]`

  Step ordering: "asc" (default, oldest first) or "desc" (newest first).

  - `"asc"`

  - `"desc"`

- `simple: Optional[Literal["true", "false"]]`

  When true, omits step details and returns only metadata with step_count.

  - `"true"`

  - `"false"`

### Returns

- `class InstanceGetResponse: …`

  - `end: Optional[datetime]`

  - `error: Optional[Error]`

    - `message: str`

    - `name: str`

  - `output: Union[str, float]`

    - `str`

    - `float`

  - `params: object`

  - `queued: datetime`

  - `start: Optional[datetime]`

  - `status: Literal["queued", "running", "paused", 5 more]`

    - `"queued"`

    - `"running"`

    - `"paused"`

    - `"errored"`

    - `"terminated"`

    - `"complete"`

    - `"waitingForPause"`

    - `"waiting"`

  - `step_count: int`

  - `steps: List[Step]`

    - `class StepUnionMember0: …`

      - `attempts: List[StepUnionMember0Attempt]`

        - `end: Optional[datetime]`

        - `error: Optional[StepUnionMember0AttemptError]`

          - `message: str`

          - `name: str`

        - `start: datetime`

        - `success: Optional[bool]`

      - `config: StepUnionMember0Config`

        - `retries: StepUnionMember0ConfigRetries`

          - `delay: Union[str, float]`

            Specifies the delay duration.

            - `str`

            - `float`

          - `limit: float`

          - `backoff: Optional[Literal["constant", "linear", "exponential"]]`

            - `"constant"`

            - `"linear"`

            - `"exponential"`

        - `timeout: Union[str, float]`

          Specifies the timeout duration.

          - `str`

          - `float`

      - `end: Optional[datetime]`

      - `name: str`

      - `output: Optional[str]`

      - `start: datetime`

      - `success: Optional[bool]`

      - `type: Literal["step"]`

        - `"step"`

    - `class StepUnionMember1: …`

      - `end: datetime`

      - `error: Optional[StepUnionMember1Error]`

        - `message: str`

        - `name: str`

      - `finished: bool`

      - `name: str`

      - `start: datetime`

      - `type: Literal["sleep"]`

        - `"sleep"`

    - `class StepUnionMember2: …`

      - `trigger: StepUnionMember2Trigger`

        - `source: str`

      - `type: Literal["termination"]`

        - `"termination"`

    - `class StepUnionMember3: …`

      - `end: datetime`

      - `error: Optional[StepUnionMember3Error]`

        - `message: str`

        - `name: str`

      - `finished: bool`

      - `name: str`

      - `start: datetime`

      - `type: Literal["waitForEvent"]`

        - `"waitForEvent"`

      - `output: Optional[str]`

  - `success: Optional[bool]`

  - `trigger: Trigger`

    - `source: Literal["unknown", "api", "binding", 2 more]`

      - `"unknown"`

      - `"api"`

      - `"binding"`

      - `"event"`

      - `"cron"`

  - `version_id: str`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
instance = client.workflows.instances.get(
    instance_id="x",
    account_id="account_id",
    workflow_name="x",
)
print(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",
    "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"
        },
        "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"
  },
  "success": true,
  "result_info": {
    "count": 0,
    "per_page": 0,
    "total_count": 0,
    "cursor": "cursor",
    "page": 0
  }
}
```

## Create a new workflow instance

`workflows.instances.create(strworkflow_name, InstanceCreateParams**kwargs)  -> InstanceCreateResponse`

**post** `/accounts/{account_id}/workflows/{workflow_name}/instances`

Creates a new instance of a workflow, starting its execution.

### Parameters

- `account_id: str`

- `workflow_name: str`

- `instance_id: Optional[str]`

- `instance_retention: Optional[InstanceRetention]`

  - `error_retention: Optional[Union[int, str]]`

    Specifies the duration in milliseconds or as a string like '5 minutes'.

    - `int`

      Specifies the duration in milliseconds.

    - `str`

  - `success_retention: Optional[Union[int, str]]`

    Specifies the duration in milliseconds or as a string like '5 minutes'.

    - `int`

      Specifies the duration in milliseconds.

    - `str`

- `params: Optional[object]`

### Returns

- `class InstanceCreateResponse: …`

  - `id: str`

  - `status: Literal["queued", "running", "paused", 5 more]`

    - `"queued"`

    - `"running"`

    - `"paused"`

    - `"errored"`

    - `"terminated"`

    - `"complete"`

    - `"waitingForPause"`

    - `"waiting"`

  - `version_id: str`

  - `workflow_id: str`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
instance = client.workflows.instances.create(
    workflow_name="x",
    account_id="account_id",
)
print(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"
  },
  "success": true,
  "result_info": {
    "count": 0,
    "per_page": 0,
    "total_count": 0,
    "cursor": "cursor",
    "page": 0
  }
}
```

## Batch create new Workflow instances

`workflows.instances.bulk(strworkflow_name, InstanceBulkParams**kwargs)  -> SyncSinglePage[InstanceBulkResponse]`

**post** `/accounts/{account_id}/workflows/{workflow_name}/instances/batch`

Creates multiple workflow instances in a single batch operation.

### Parameters

- `account_id: str`

- `workflow_name: str`

- `body: Optional[Iterable[Body]]`

  - `instance_id: Optional[str]`

  - `instance_retention: Optional[BodyInstanceRetention]`

    - `error_retention: Optional[Union[int, str]]`

      Specifies the duration in milliseconds or as a string like '5 minutes'.

      - `int`

        Specifies the duration in milliseconds.

      - `str`

    - `success_retention: Optional[Union[int, str]]`

      Specifies the duration in milliseconds or as a string like '5 minutes'.

      - `int`

        Specifies the duration in milliseconds.

      - `str`

  - `params: Optional[object]`

### Returns

- `class InstanceBulkResponse: …`

  - `id: str`

  - `status: Literal["queued", "running", "paused", 5 more]`

    - `"queued"`

    - `"running"`

    - `"paused"`

    - `"errored"`

    - `"terminated"`

    - `"complete"`

    - `"waitingForPause"`

    - `"waiting"`

  - `version_id: str`

  - `workflow_id: str`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
page = client.workflows.instances.bulk(
    workflow_name="x",
    account_id="account_id",
)
page = page.result[0]
print(page.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"
    }
  ],
  "success": true,
  "result_info": {
    "count": 0,
    "per_page": 0,
    "total_count": 0,
    "cursor": "cursor",
    "page": 0
  }
}
```

## Domain Types

### Instance List Response

- `class InstanceListResponse: …`

  - `id: str`

  - `created_on: datetime`

  - `ended_on: Optional[datetime]`

  - `modified_on: datetime`

  - `started_on: Optional[datetime]`

  - `status: Literal["queued", "running", "paused", 5 more]`

    - `"queued"`

    - `"running"`

    - `"paused"`

    - `"errored"`

    - `"terminated"`

    - `"complete"`

    - `"waitingForPause"`

    - `"waiting"`

  - `version_id: str`

  - `workflow_id: str`

### Instance Get Response

- `class InstanceGetResponse: …`

  - `end: Optional[datetime]`

  - `error: Optional[Error]`

    - `message: str`

    - `name: str`

  - `output: Union[str, float]`

    - `str`

    - `float`

  - `params: object`

  - `queued: datetime`

  - `start: Optional[datetime]`

  - `status: Literal["queued", "running", "paused", 5 more]`

    - `"queued"`

    - `"running"`

    - `"paused"`

    - `"errored"`

    - `"terminated"`

    - `"complete"`

    - `"waitingForPause"`

    - `"waiting"`

  - `step_count: int`

  - `steps: List[Step]`

    - `class StepUnionMember0: …`

      - `attempts: List[StepUnionMember0Attempt]`

        - `end: Optional[datetime]`

        - `error: Optional[StepUnionMember0AttemptError]`

          - `message: str`

          - `name: str`

        - `start: datetime`

        - `success: Optional[bool]`

      - `config: StepUnionMember0Config`

        - `retries: StepUnionMember0ConfigRetries`

          - `delay: Union[str, float]`

            Specifies the delay duration.

            - `str`

            - `float`

          - `limit: float`

          - `backoff: Optional[Literal["constant", "linear", "exponential"]]`

            - `"constant"`

            - `"linear"`

            - `"exponential"`

        - `timeout: Union[str, float]`

          Specifies the timeout duration.

          - `str`

          - `float`

      - `end: Optional[datetime]`

      - `name: str`

      - `output: Optional[str]`

      - `start: datetime`

      - `success: Optional[bool]`

      - `type: Literal["step"]`

        - `"step"`

    - `class StepUnionMember1: …`

      - `end: datetime`

      - `error: Optional[StepUnionMember1Error]`

        - `message: str`

        - `name: str`

      - `finished: bool`

      - `name: str`

      - `start: datetime`

      - `type: Literal["sleep"]`

        - `"sleep"`

    - `class StepUnionMember2: …`

      - `trigger: StepUnionMember2Trigger`

        - `source: str`

      - `type: Literal["termination"]`

        - `"termination"`

    - `class StepUnionMember3: …`

      - `end: datetime`

      - `error: Optional[StepUnionMember3Error]`

        - `message: str`

        - `name: str`

      - `finished: bool`

      - `name: str`

      - `start: datetime`

      - `type: Literal["waitForEvent"]`

        - `"waitForEvent"`

      - `output: Optional[str]`

  - `success: Optional[bool]`

  - `trigger: Trigger`

    - `source: Literal["unknown", "api", "binding", 2 more]`

      - `"unknown"`

      - `"api"`

      - `"binding"`

      - `"event"`

      - `"cron"`

  - `version_id: str`

### Instance Create Response

- `class InstanceCreateResponse: …`

  - `id: str`

  - `status: Literal["queued", "running", "paused", 5 more]`

    - `"queued"`

    - `"running"`

    - `"paused"`

    - `"errored"`

    - `"terminated"`

    - `"complete"`

    - `"waitingForPause"`

    - `"waiting"`

  - `version_id: str`

  - `workflow_id: str`

### Instance Bulk Response

- `class InstanceBulkResponse: …`

  - `id: str`

  - `status: Literal["queued", "running", "paused", 5 more]`

    - `"queued"`

    - `"running"`

    - `"paused"`

    - `"errored"`

    - `"terminated"`

    - `"complete"`

    - `"waitingForPause"`

    - `"waiting"`

  - `version_id: str`

  - `workflow_id: str`

# Status

## Change status of instance

`workflows.instances.status.edit(strinstance_id, StatusEditParams**kwargs)  -> 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

- `account_id: str`

- `workflow_name: str`

- `instance_id: str`

- `status: Literal["resume", "pause", "terminate", "restart"]`

  Apply action to instance.

  - `"resume"`

  - `"pause"`

  - `"terminate"`

  - `"restart"`

### Returns

- `class StatusEditResponse: …`

  - `status: Literal["queued", "running", "paused", 5 more]`

    - `"queued"`

    - `"running"`

    - `"paused"`

    - `"errored"`

    - `"terminated"`

    - `"complete"`

    - `"waitingForPause"`

    - `"waiting"`

  - `timestamp: datetime`

    Accepts ISO 8601 with no timezone offsets and in UTC.

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
response = client.workflows.instances.status.edit(
    instance_id="x",
    account_id="account_id",
    workflow_name="x",
    status="resume",
)
print(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
  }
}
```

## Domain Types

### Status Edit Response

- `class StatusEditResponse: …`

  - `status: Literal["queued", "running", "paused", 5 more]`

    - `"queued"`

    - `"running"`

    - `"paused"`

    - `"errored"`

    - `"terminated"`

    - `"complete"`

    - `"waitingForPause"`

    - `"waiting"`

  - `timestamp: datetime`

    Accepts ISO 8601 with no timezone offsets and in UTC.

# Events

## Send event to instance

`workflows.instances.events.create(strevent_type, EventCreateParams**kwargs)  -> object`

**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

- `account_id: str`

- `workflow_name: str`

- `instance_id: str`

- `event_type: str`

- `body: Optional[object]`

### Returns

- `object`

### Example

```python
import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
event = client.workflows.instances.events.create(
    event_type="x",
    account_id="account_id",
    workflow_name="x",
    instance_id="x",
)
print(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
  }
}
```