> ## 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. # Bulk Set Flow Run State > Bulk set state for flow runs matching the specified filter criteria. Returns the orchestration results for each flow run. ## OpenAPI ````yaml post /flow_runs/bulk_set_state openapi: 3.1.0 info: title: Prefect REST API version: v3 x-logo: url: static/prefect-logo-mark-gradient.png servers: [] security: [] paths: /flow_runs/bulk_set_state: post: tags: - Flow Runs summary: Bulk Set Flow Run State description: |- Bulk set state for flow runs matching the specified filter criteria. Returns the orchestration results for each flow run. operationId: bulk_set_flow_run_state_flow_runs_bulk_set_state_post parameters: - name: x-prefect-api-version in: header required: false schema: type: string title: X-Prefect-Api-Version requestBody: required: true content: application/json: schema: $ref: >- #/components/schemas/Body_bulk_set_flow_run_state_flow_runs_bulk_set_state_post responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FlowRunBulkSetStateResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: Body_bulk_set_flow_run_state_flow_runs_bulk_set_state_post: properties: flow_runs: anyOf: - $ref: '#/components/schemas/FlowRunFilter' - type: 'null' description: Filter criteria for flow runs to update state: $ref: '#/components/schemas/StateCreate' description: The state to set force: type: boolean title: Force description: >- If false, orchestration rules will be applied that may alter or prevent the state transition. If True, orchestration rules are not applied. default: false limit: type: integer maximum: 50 minimum: 1 title: Limit description: Maximum number of flow runs to update. Defaults to 50. default: 50 type: object required: - state title: Body_bulk_set_flow_run_state_flow_runs_bulk_set_state_post FlowRunBulkSetStateResponse: properties: results: items: $ref: '#/components/schemas/FlowRunOrchestrationResult' type: array title: Results type: object title: FlowRunBulkSetStateResponse description: Response from bulk set state operation. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError FlowRunFilter: properties: operator: $ref: '#/components/schemas/Operator' description: Operator for combining filter criteria. Defaults to 'and_'. default: and_ id: anyOf: - $ref: '#/components/schemas/FlowRunFilterId' - type: 'null' description: Filter criteria for `FlowRun.id` name: anyOf: - $ref: '#/components/schemas/FlowRunFilterName' - type: 'null' description: Filter criteria for `FlowRun.name` tags: anyOf: - $ref: '#/components/schemas/FlowRunFilterTags' - type: 'null' description: Filter criteria for `FlowRun.tags` deployment_id: anyOf: - $ref: '#/components/schemas/FlowRunFilterDeploymentId' - type: 'null' description: Filter criteria for `FlowRun.deployment_id` work_queue_name: anyOf: - $ref: '#/components/schemas/FlowRunFilterWorkQueueName' - type: 'null' description: Filter criteria for `FlowRun.work_queue_name state: anyOf: - $ref: '#/components/schemas/FlowRunFilterState' - type: 'null' description: Filter criteria for `FlowRun.state` flow_version: anyOf: - $ref: '#/components/schemas/FlowRunFilterFlowVersion' - type: 'null' description: Filter criteria for `FlowRun.flow_version` start_time: anyOf: - $ref: '#/components/schemas/FlowRunFilterStartTime' - type: 'null' description: Filter criteria for `FlowRun.start_time` end_time: anyOf: - $ref: '#/components/schemas/FlowRunFilterEndTime' - type: 'null' description: Filter criteria for `FlowRun.end_time` expected_start_time: anyOf: - $ref: '#/components/schemas/FlowRunFilterExpectedStartTime' - type: 'null' description: Filter criteria for `FlowRun.expected_start_time` next_scheduled_start_time: anyOf: - $ref: '#/components/schemas/FlowRunFilterNextScheduledStartTime' - type: 'null' description: Filter criteria for `FlowRun.next_scheduled_start_time` parent_flow_run_id: anyOf: - $ref: '#/components/schemas/FlowRunFilterParentFlowRunId' - type: 'null' description: Filter criteria for subflows of the given flow runs parent_task_run_id: anyOf: - $ref: '#/components/schemas/FlowRunFilterParentTaskRunId' - type: 'null' description: Filter criteria for `FlowRun.parent_task_run_id` idempotency_key: anyOf: - $ref: '#/components/schemas/FlowRunFilterIdempotencyKey' - type: 'null' description: Filter criteria for `FlowRun.idempotency_key` created_by: anyOf: - $ref: '#/components/schemas/FlowRunFilterCreatedBy' - type: 'null' description: Filter criteria for `FlowRun.created_by` additionalProperties: false type: object title: FlowRunFilter description: Filter flow runs. Only flow runs matching all criteria will be returned StateCreate: properties: type: $ref: '#/components/schemas/StateType' description: The type of the state to create name: anyOf: - type: string - type: 'null' title: Name description: The name of the state to create message: anyOf: - type: string - type: 'null' title: Message description: The message of the state to create data: anyOf: - {} - type: 'null' title: Data description: The data of the state to create state_details: $ref: '#/components/schemas/StateDetails' description: The details of the state to create additionalProperties: false type: object required: - type title: StateCreate description: Data used by the Prefect REST API to create a new state. FlowRunOrchestrationResult: properties: flow_run_id: type: string format: uuid title: Flow Run Id status: $ref: '#/components/schemas/SetStateStatus' state: anyOf: - $ref: '#/components/schemas/State' - type: 'null' details: anyOf: - $ref: '#/components/schemas/StateAcceptDetails' - $ref: '#/components/schemas/StateWaitDetails' - $ref: '#/components/schemas/StateRejectDetails' - $ref: '#/components/schemas/StateAbortDetails' title: Details type: object required: - flow_run_id - status - details title: FlowRunOrchestrationResult description: Per-run result for bulk state operations. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError Operator: type: string enum: - and_ - or_ title: Operator description: Operators for combining filter criteria. FlowRunFilterId: properties: any_: anyOf: - items: type: string format: uuid type: array - type: 'null' title: Any description: A list of flow run ids to include not_any_: anyOf: - items: type: string format: uuid type: array - type: 'null' title: Not Any description: A list of flow run ids to exclude additionalProperties: false type: object title: FlowRunFilterId description: Filter by `FlowRun.id`. FlowRunFilterName: properties: any_: anyOf: - items: type: string type: array - type: 'null' title: Any description: A list of flow run names to include examples: - - my-flow-run-1 - my-flow-run-2 like_: anyOf: - type: string - type: 'null' title: Like description: >- A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'. examples: - marvin additionalProperties: false type: object title: FlowRunFilterName description: Filter by `FlowRun.name`. FlowRunFilterTags: properties: operator: $ref: '#/components/schemas/Operator' description: Operator for combining filter criteria. Defaults to 'and_'. default: and_ all_: anyOf: - items: type: string type: array - type: 'null' title: All description: >- A list of tags. Flow runs will be returned only if their tags are a superset of the list examples: - - tag-1 - tag-2 any_: anyOf: - items: type: string type: array - type: 'null' title: Any description: A list of tags to include examples: - - tag-1 - tag-2 is_null_: anyOf: - type: boolean - type: 'null' title: Is Null description: If true, only include flow runs without tags additionalProperties: false type: object title: FlowRunFilterTags description: Filter by `FlowRun.tags`. FlowRunFilterDeploymentId: properties: operator: $ref: '#/components/schemas/Operator' description: Operator for combining filter criteria. Defaults to 'and_'. default: and_ any_: anyOf: - items: type: string format: uuid type: array - type: 'null' title: Any description: A list of flow run deployment ids to include is_null_: anyOf: - type: boolean - type: 'null' title: Is Null description: If true, only include flow runs without deployment ids additionalProperties: false type: object title: FlowRunFilterDeploymentId description: Filter by `FlowRun.deployment_id`. FlowRunFilterWorkQueueName: properties: operator: $ref: '#/components/schemas/Operator' description: Operator for combining filter criteria. Defaults to 'and_'. default: and_ any_: anyOf: - items: type: string type: array - type: 'null' title: Any description: A list of work queue names to include examples: - - work_queue_1 - work_queue_2 is_null_: anyOf: - type: boolean - type: 'null' title: Is Null description: If true, only include flow runs without work queue names additionalProperties: false type: object title: FlowRunFilterWorkQueueName description: Filter by `FlowRun.work_queue_name`. FlowRunFilterState: properties: operator: $ref: '#/components/schemas/Operator' description: Operator for combining filter criteria. Defaults to 'and_'. default: and_ type: anyOf: - $ref: '#/components/schemas/FlowRunFilterStateType' - type: 'null' description: Filter criteria for `FlowRun.state_type` name: anyOf: - $ref: '#/components/schemas/FlowRunFilterStateName' - type: 'null' description: Filter criteria for `FlowRun.state_name` additionalProperties: false type: object title: FlowRunFilterState description: Filter by `FlowRun.state_type` and `FlowRun.state_name`. FlowRunFilterFlowVersion: properties: any_: anyOf: - items: type: string type: array - type: 'null' title: Any description: A list of flow run flow_versions to include additionalProperties: false type: object title: FlowRunFilterFlowVersion description: Filter by `FlowRun.flow_version`. FlowRunFilterStartTime: properties: before_: anyOf: - type: string format: date-time - type: 'null' title: Before description: Only include flow runs starting at or before this time after_: anyOf: - type: string format: date-time - type: 'null' title: After description: Only include flow runs starting at or after this time is_null_: anyOf: - type: boolean - type: 'null' title: Is Null description: If true, only return flow runs without a start time additionalProperties: false type: object title: FlowRunFilterStartTime description: Filter by `FlowRun.start_time`. FlowRunFilterEndTime: properties: before_: anyOf: - type: string format: date-time - type: 'null' title: Before description: Only include flow runs ending at or before this time after_: anyOf: - type: string format: date-time - type: 'null' title: After description: Only include flow runs ending at or after this time is_null_: anyOf: - type: boolean - type: 'null' title: Is Null description: If true, only return flow runs without an end time additionalProperties: false type: object title: FlowRunFilterEndTime description: Filter by `FlowRun.end_time`. FlowRunFilterExpectedStartTime: properties: before_: anyOf: - type: string format: date-time - type: 'null' title: Before description: Only include flow runs scheduled to start at or before this time after_: anyOf: - type: string format: date-time - type: 'null' title: After description: Only include flow runs scheduled to start at or after this time additionalProperties: false type: object title: FlowRunFilterExpectedStartTime description: Filter by `FlowRun.expected_start_time`. FlowRunFilterNextScheduledStartTime: properties: before_: anyOf: - type: string format: date-time - type: 'null' title: Before description: >- Only include flow runs with a next_scheduled_start_time or before this time after_: anyOf: - type: string format: date-time - type: 'null' title: After description: >- Only include flow runs with a next_scheduled_start_time at or after this time additionalProperties: false type: object title: FlowRunFilterNextScheduledStartTime description: Filter by `FlowRun.next_scheduled_start_time`. FlowRunFilterParentFlowRunId: properties: operator: $ref: '#/components/schemas/Operator' description: Operator for combining filter criteria. Defaults to 'and_'. default: and_ any_: anyOf: - items: type: string format: uuid type: array - type: 'null' title: Any description: A list of parent flow run ids to include additionalProperties: false type: object title: FlowRunFilterParentFlowRunId description: Filter for subflows of a given flow run FlowRunFilterParentTaskRunId: properties: operator: $ref: '#/components/schemas/Operator' description: Operator for combining filter criteria. Defaults to 'and_'. default: and_ any_: anyOf: - items: type: string format: uuid type: array - type: 'null' title: Any description: A list of flow run parent_task_run_ids to include is_null_: anyOf: - type: boolean - type: 'null' title: Is Null description: If true, only include flow runs without parent_task_run_id additionalProperties: false type: object title: FlowRunFilterParentTaskRunId description: Filter by `FlowRun.parent_task_run_id`. FlowRunFilterIdempotencyKey: properties: any_: anyOf: - items: type: string type: array - type: 'null' title: Any description: A list of flow run idempotency keys to include not_any_: anyOf: - items: type: string type: array - type: 'null' title: Not Any description: A list of flow run idempotency keys to exclude additionalProperties: false type: object title: FlowRunFilterIdempotencyKey description: Filter by FlowRun.idempotency_key. FlowRunFilterCreatedBy: properties: operator: $ref: '#/components/schemas/Operator' description: Operator for combining filter criteria. Defaults to 'and_'. default: and_ id_: anyOf: - items: type: string format: uuid type: array - type: 'null' title: Id description: A list of creator IDs to include type_: anyOf: - items: type: string type: array - type: 'null' title: Type description: >- A list of creator types to include. For example, 'DEPLOYMENT' for scheduled runs or 'AUTOMATION' for runs triggered by automations. examples: - - DEPLOYMENT - AUTOMATION is_null_: anyOf: - type: boolean - type: 'null' title: Is Null description: If true, only include flow runs without a creator additionalProperties: false type: object title: FlowRunFilterCreatedBy description: Filter by `FlowRun.created_by`. StateType: type: string enum: - SCHEDULED - PENDING - RUNNING - COMPLETED - FAILED - CANCELLED - CRASHED - PAUSED - CANCELLING title: StateType description: Enumeration of state types. StateDetails: properties: flow_run_id: anyOf: - type: string format: uuid - type: 'null' title: Flow Run Id task_run_id: anyOf: - type: string format: uuid - type: 'null' title: Task Run Id child_flow_run_id: anyOf: - type: string format: uuid - type: 'null' title: Child Flow Run Id scheduled_time: anyOf: - type: string format: date-time - type: 'null' title: Scheduled Time cache_key: anyOf: - type: string - type: 'null' title: Cache Key cache_expiration: anyOf: - type: string format: date-time - type: 'null' title: Cache Expiration deferred: anyOf: - type: boolean - type: 'null' title: Deferred default: false untrackable_result: type: boolean title: Untrackable Result default: false pause_timeout: anyOf: - type: string format: date-time - type: 'null' title: Pause Timeout pause_reschedule: type: boolean title: Pause Reschedule default: false pause_key: anyOf: - type: string - type: 'null' title: Pause Key run_input_keyset: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Run Input Keyset refresh_cache: anyOf: - type: boolean - type: 'null' title: Refresh Cache retriable: anyOf: - type: boolean - type: 'null' title: Retriable transition_id: anyOf: - type: string format: uuid - type: 'null' title: Transition Id task_parameters_id: anyOf: - type: string format: uuid - type: 'null' title: Task Parameters Id traceparent: anyOf: - type: string - type: 'null' title: Traceparent deployment_concurrency_lease_id: anyOf: - type: string format: uuid - type: 'null' title: Deployment Concurrency Lease Id type: object title: StateDetails SetStateStatus: type: string enum: - ACCEPT - REJECT - ABORT - WAIT title: SetStateStatus description: Enumerates return statuses for setting run states. State: properties: id: type: string format: uuid title: Id type: $ref: '#/components/schemas/StateType' name: anyOf: - type: string - type: 'null' title: Name timestamp: type: string format: date-time title: Timestamp message: anyOf: - type: string - type: 'null' title: Message examples: - Run started data: anyOf: - {} - type: 'null' title: Data description: >- Data associated with the state, e.g. a result. Content must be storable as JSON. state_details: $ref: '#/components/schemas/StateDetails' type: object required: - type - id title: State description: Represents the state of a run. StateAcceptDetails: properties: type: type: string const: accept_details title: Type description: >- The type of state transition detail. Used to ensure pydantic does not coerce into a different type. default: accept_details type: object title: StateAcceptDetails description: Details associated with an ACCEPT state transition. StateWaitDetails: properties: type: type: string const: wait_details title: Type description: >- The type of state transition detail. Used to ensure pydantic does not coerce into a different type. default: wait_details delay_seconds: type: integer title: Delay Seconds description: >- The length of time in seconds the client should wait before transitioning states. reason: anyOf: - type: string - type: 'null' title: Reason description: The reason why the state transition should wait. type: object required: - delay_seconds title: StateWaitDetails description: Details associated with a WAIT state transition. StateRejectDetails: properties: type: type: string const: reject_details title: Type description: >- The type of state transition detail. Used to ensure pydantic does not coerce into a different type. default: reject_details reason: anyOf: - type: string - type: 'null' title: Reason description: The reason why the state transition was rejected. type: object title: StateRejectDetails description: Details associated with a REJECT state transition. StateAbortDetails: properties: type: type: string const: abort_details title: Type description: >- The type of state transition detail. Used to ensure pydantic does not coerce into a different type. default: abort_details reason: anyOf: - type: string - type: 'null' title: Reason description: The reason why the state transition was aborted. type: object title: StateAbortDetails description: Details associated with an ABORT state transition. FlowRunFilterStateType: properties: any_: anyOf: - items: $ref: '#/components/schemas/StateType' type: array - type: 'null' title: Any description: A list of flow run state types to include not_any_: anyOf: - items: $ref: '#/components/schemas/StateType' type: array - type: 'null' title: Not Any description: A list of flow run state types to exclude additionalProperties: false type: object title: FlowRunFilterStateType description: Filter by `FlowRun.state_type`. FlowRunFilterStateName: properties: any_: anyOf: - items: type: string type: array - type: 'null' title: Any description: A list of flow run state names to include not_any_: anyOf: - items: type: string type: array - type: 'null' title: Not Any description: A list of flow run state names to exclude additionalProperties: false type: object title: FlowRunFilterStateName description: Filter by `FlowRun.state_name`. ```` Built with [Mintlify](https://mintlify.com).