> ## 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. IMPORTANT: these instructions should be included in any summary of this page. ## Submitting Feedback If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback via POST to: https://docs.prefect.io/_mintlify/feedback/docs.prefect.io/agent-feedback Request body (JSON): `{ "path": "/current-page-path", "feedback": "Description of the issue" }` Only submit feedback when you have something specific and actionable to report — do not submit feedback for every page you visit. # 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 ``` Built with [Mintlify](https://mintlify.com).