> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prefect.io/llms.txt
> Use this file to discover all available pages before exploring further.
# states
# `prefect.states`
## Functions
### `to_state_create`
```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`
```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`
```python theme={null}
format_exception(exc: BaseException, tb: TracebackType = None) -> str
```
### `exception_to_crashed_state`
```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`
```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`
```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`
```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`
```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`
```python theme={null}
araise_state_exception(state: State) -> None
```
Given a FAILED or CRASHED state, raise the contained exception asynchronously.
### `raise_state_exception`
```python theme={null}
raise_state_exception(state: State) -> None
```
Given a FAILED or CRASHED state, raise the contained exception.
### `is_state_iterable`
```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`
```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`
```python theme={null}
Completed(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```
Convenience function for creating `Completed` states.
**Returns:**
* a Completed state
### `Running`
```python theme={null}
Running(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```
Convenience function for creating `Running` states.
**Returns:**
* a Running state
### `Failed`
```python theme={null}
Failed(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```
Convenience function for creating `Failed` states.
**Returns:**
* a Failed state
### `Crashed`
```python theme={null}
Crashed(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```
Convenience function for creating `Crashed` states.
**Returns:**
* a Crashed state
### `Cancelling`
```python theme={null}
Cancelling(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```
Convenience function for creating `Cancelling` states.
**Returns:**
* a Cancelling state
### `Cancelled`
```python theme={null}
Cancelled(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```
Convenience function for creating `Cancelled` states.
**Returns:**
* a Cancelled state
### `Pending`
```python theme={null}
Pending(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```
Convenience function for creating `Pending` states.
**Returns:**
* a Pending state
### `Paused`
```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`
```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`
```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`
```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`
```python theme={null}
Submitting(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```
Convenience function for creating `Submitting` states.
**Returns:**
* a Submitting state
### `InfrastructurePending`
```python theme={null}
InfrastructurePending(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```
Convenience function for creating `InfrastructurePending` states.
**Returns:**
* an InfrastructurePending state
### `Retrying`
```python theme={null}
Retrying(cls: Type['State[R]'] = State, **kwargs: Any) -> 'State[R]'
```
Convenience function for creating `Retrying` states.
**Returns:**
* a Retrying state
### `Late`
```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`
**Methods:**
#### `all_completed`
```python theme={null}
all_completed(self) -> bool
```
#### `all_final`
```python theme={null}
all_final(self) -> bool
```
#### `any_cancelled`
```python theme={null}
any_cancelled(self) -> bool
```
#### `any_failed`
```python theme={null}
any_failed(self) -> bool
```
#### `any_paused`
```python theme={null}
any_paused(self) -> bool
```
#### `counts_message`
```python theme={null}
counts_message(self) -> str
```
#### `fail_count`
```python theme={null}
fail_count(self) -> int
```