> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# states

# `prefect.states`

## Functions

### `to_state_create` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L46](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L46)</sup>

```python theme={null}
to_state_create(state: State) -> 'StateCreate'
```

Convert the state to a `StateCreate` type which can be used to set the state of
a run in the API.

This method will drop this state's `data` if it is not a result type. Only
results should be sent to the API. Other data is only available locally.

### `get_state_result` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L78](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L78)</sup>

```python theme={null}
get_state_result(state: 'State[R]', raise_on_failure: bool = True, retry_result_failure: bool = True) -> 'R'
```

Get the result from a state.

See `State.result()`

### `format_exception` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L187](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L187)</sup>

```python theme={null}
format_exception(exc: BaseException, tb: TracebackType = None) -> str
```

### `exception_to_crashed_state` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L203](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L203)</sup>

```python theme={null}
exception_to_crashed_state(exc: BaseException, result_store: Optional['ResultStore'] = None) -> State
```

Takes an exception that occurs *outside* of user code and converts it to a
'Crash' exception with a 'Crashed' state.

### `exception_to_failed_state` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L255](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L255)</sup>

```python theme={null}
exception_to_failed_state(exc: Optional[BaseException] = None, result_store: Optional['ResultStore'] = None, write_result: bool = False, **kwargs: Any) -> State[BaseException]
```

Convenience function for creating `Failed` states from exceptions

### `return_value_to_state` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L308](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L308)</sup>

```python theme={null}
return_value_to_state(retval: 'R', result_store: 'ResultStore', key: Optional[str] = None, expiration: Optional[datetime.datetime] = None, write_result: bool = False) -> 'State[R]'
```

Given a return value from a user's function, create a `State` the run should
be placed in.

* If data is returned, we create a 'COMPLETED' state with the data
* If a single, manually created state is returned, we use that state as given
  (manual creation is determined by the lack of ids)
* If an upstream state or iterable of upstream states is returned, we apply the
  aggregate rule

The aggregate rule says that given multiple states we will determine the final state
such that:

* If any states are not COMPLETED the final state is FAILED
* If all of the states are COMPLETED the final state is COMPLETED
* The states will be placed in the final state `data` attribute

Callers should resolve all futures into states before passing return values to this
function.

### `aget_state_exception` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L449](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L449)</sup>

```python theme={null}
aget_state_exception(state: State) -> BaseException
```

Get the exception from a state asynchronously.

If not given a FAILED or CRASHED state, this raise a value error.

If the state result is a state, its exception will be returned.

If the state result is an iterable of states, the exception of the first failure
will be returned.

If the state result is a string, a wrapper exception will be returned with the
string as the message.

If the state result is null, a wrapper exception will be returned with the state
message attached.

If the state result is not of a known type, a `TypeError` will be returned.

When a wrapper exception is returned, the type will be:

* `FailedRun` if the state type is FAILED.
* `CrashedRun` if the state type is CRASHED.
* `CancelledRun` if the state type is CANCELLED.

### `get_state_exception` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L535](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L535)</sup>

```python theme={null}
get_state_exception(state: State) -> BaseException
```

Get the exception from a state.

If not given a FAILED or CRASHED state, this raise a value error.

If the state result is a state, its exception will be returned.

If the state result is an iterable of states, the exception of the first failure
will be returned.

If the state result is a string, a wrapper exception will be returned with the
string as the message.

If the state result is null, a wrapper exception will be returned with the state
message attached.

If the state result is not of a known type, a `TypeError` will be returned.

When a wrapper exception is returned, the type will be:

* `FailedRun` if the state type is FAILED.
* `CrashedRun` if the state type is CRASHED.
* `CancelledRun` if the state type is CANCELLED.

### `araise_state_exception` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L635](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L635)</sup>

```python theme={null}
araise_state_exception(state: State) -> None
```

Given a FAILED or CRASHED state, raise the contained exception asynchronously.

### `raise_state_exception` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L646](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L646)</sup>

```python theme={null}
raise_state_exception(state: State) -> None
```

Given a FAILED or CRASHED state, raise the contained exception.

### `is_state_iterable` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L656](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L656)</sup>

```python theme={null}
is_state_iterable(obj: Any) -> TypeGuard[Iterable[State]]
```

Check if a the given object is an iterable of states types

Supported iterables are:

* set
* list
* tuple

Other iterables will return `False` even if they contain states.

### `Scheduled` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L742](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L742)</sup>

```python theme={null}
Scheduled(cls: Type['State[R]'] = State, scheduled_time: Optional[datetime.datetime] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Scheduled` states.

**Returns:**

* a Scheduled state

### `Completed` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L762](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L762)</sup>

```python theme={null}
Completed(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Completed` states.

**Returns:**

* a Completed state

### `Running` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L772](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L772)</sup>

```python theme={null}
Running(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Running` states.

**Returns:**

* a Running state

### `Failed` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L781](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L781)</sup>

```python theme={null}
Failed(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Failed` states.

**Returns:**

* a Failed state

### `Crashed` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L790](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L790)</sup>

```python theme={null}
Crashed(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Crashed` states.

**Returns:**

* a Crashed state

### `Cancelling` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L799](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L799)</sup>

```python theme={null}
Cancelling(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Cancelling` states.

**Returns:**

* a Cancelling state

### `Cancelled` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L808](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L808)</sup>

```python theme={null}
Cancelled(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Cancelled` states.

**Returns:**

* a Cancelled state

### `Pending` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L817](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L817)</sup>

```python theme={null}
Pending(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Pending` states.

**Returns:**

* a Pending state

### `Paused` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L826](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L826)</sup>

```python theme={null}
Paused(cls: Type['State[R]'] = State, timeout_seconds: Optional[int] = None, pause_expiration_time: Optional[datetime.datetime] = None, reschedule: bool = False, pause_key: Optional[str] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Paused` states.

**Returns:**

* a Paused state

### `Suspended` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L864](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L864)</sup>

```python theme={null}
Suspended(cls: Type['State[R]'] = State, timeout_seconds: Optional[int] = None, pause_expiration_time: Optional[datetime.datetime] = None, pause_key: Optional[str] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Suspended` states.

**Returns:**

* a Suspended state

### `AwaitingRetry` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L887](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L887)</sup>

```python theme={null}
AwaitingRetry(cls: Type['State[R]'] = State, scheduled_time: Optional[datetime.datetime] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `AwaitingRetry` states.

**Returns:**

* an AwaitingRetry state

### `AwaitingConcurrencySlot` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L902](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L902)</sup>

```python theme={null}
AwaitingConcurrencySlot(cls: Type['State[R]'] = State, scheduled_time: Optional[datetime.datetime] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `AwaitingConcurrencySlot` states.

**Returns:**

* an AwaitingConcurrencySlot state

### `Submitting` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L917](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L917)</sup>

```python theme={null}
Submitting(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Submitting` states.

**Returns:**

* a Submitting state

### `InfrastructurePending` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L926](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L926)</sup>

```python theme={null}
InfrastructurePending(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `InfrastructurePending` states.

**Returns:**

* an InfrastructurePending state

### `Retrying` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L935](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L935)</sup>

```python theme={null}
Retrying(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Retrying` states.

**Returns:**

* a Retrying state

### `Late` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L944](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L944)</sup>

```python theme={null}
Late(cls: Type['State[R]'] = State, scheduled_time: Optional[datetime.datetime] = None, **kwargs: Any) -> 'State[R]'
```

Convenience function for creating `Late` states.

**Returns:**

* a Late state

## Classes

### `StateGroup` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L679](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L679)</sup>

**Methods:**

#### `all_completed` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L693](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L693)</sup>

```python theme={null}
all_completed(self) -> bool
```

#### `all_final` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L708](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L708)</sup>

```python theme={null}
all_final(self) -> bool
```

#### `any_cancelled` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L696](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L696)</sup>

```python theme={null}
any_cancelled(self) -> bool
```

#### `any_failed` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L699](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L699)</sup>

```python theme={null}
any_failed(self) -> bool
```

#### `any_paused` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L705](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L705)</sup>

```python theme={null}
any_paused(self) -> bool
```

#### `counts_message` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L711](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L711)</sup>

```python theme={null}
counts_message(self) -> str
```

#### `fail_count` <sup>[https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L690](https://github.com/PrefectHQ/prefect/blob/main/src/prefect/states.py#L690)</sup>

```python theme={null}
fail_count(self) -> int
```