Read Flow Runs

curl --request POST \
  --url https://api.example.com/api/flow_runs/filter \
  --header 'Content-Type: application/json' \
  --data '
{
  "sort": "ID_DESC",
  "offset": 0,
  "flows": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "deployment": {
      "operator": "and_",
      "is_null_": true
    },
    "name": {
      "any_": [
        "my-flow-1",
        "my-flow-2"
      ],
      "like_": "marvin"
    },
    "tags": {
      "operator": "and_",
      "all_": [
        "tag-1",
        "tag-2"
      ],
      "is_null_": true
    }
  },
  "flow_runs": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "not_any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "name": {
      "any_": [
        "my-flow-run-1",
        "my-flow-run-2"
      ],
      "like_": "marvin"
    },
    "tags": {
      "operator": "and_",
      "all_": [
        "tag-1",
        "tag-2"
      ],
      "any_": [
        "tag-1",
        "tag-2"
      ],
      "is_null_": true
    },
    "deployment_id": {
      "operator": "and_",
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "is_null_": true
    },
    "work_queue_name": {
      "operator": "and_",
      "any_": [
        "work_queue_1",
        "work_queue_2"
      ],
      "is_null_": true
    },
    "state": {
      "operator": "and_",
      "type": {
        "any_": [
          "SCHEDULED"
        ],
        "not_any_": [
          "SCHEDULED"
        ]
      },
      "name": {
        "any_": [
          "<string>"
        ],
        "not_any_": [
          "<string>"
        ]
      }
    },
    "flow_version": {
      "any_": [
        "<string>"
      ]
    },
    "start_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z",
      "is_null_": true
    },
    "end_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z",
      "is_null_": true
    },
    "expected_start_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z"
    },
    "next_scheduled_start_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z"
    },
    "parent_flow_run_id": {
      "operator": "and_",
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "parent_task_run_id": {
      "operator": "and_",
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "is_null_": true
    },
    "idempotency_key": {
      "any_": [
        "<string>"
      ],
      "not_any_": [
        "<string>"
      ]
    }
  },
  "task_runs": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "name": {
      "any_": [
        "my-task-run-1",
        "my-task-run-2"
      ],
      "like_": "marvin"
    },
    "tags": {
      "operator": "and_",
      "all_": [
        "tag-1",
        "tag-2"
      ],
      "is_null_": true
    },
    "state": {
      "operator": "and_",
      "type": {
        "any_": [
          "SCHEDULED"
        ]
      },
      "name": {
        "any_": [
          "<string>"
        ]
      }
    },
    "start_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z",
      "is_null_": true
    },
    "expected_start_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z"
    },
    "subflow_runs": {
      "exists_": true
    },
    "flow_run_id": {
      "operator": "and_",
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "is_null_": false
    }
  },
  "deployments": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "not_any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "name": {
      "any_": [
        "my-deployment-1",
        "my-deployment-2"
      ],
      "like_": "marvin"
    },
    "flow_or_deployment_name": {
      "like_": "<string>"
    },
    "paused": {
      "eq_": true
    },
    "tags": {
      "operator": "and_",
      "all_": [
        "tag-1",
        "tag-2"
      ],
      "any_": [
        "tag-1",
        "tag-2"
      ],
      "is_null_": true
    },
    "work_queue_name": {
      "any_": [
        "work_queue_1",
        "work_queue_2"
      ]
    },
    "concurrency_limit": {
      "ge_": 123,
      "le_": 123,
      "is_null_": true
    }
  },
  "work_pools": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "name": {
      "any_": [
        "<string>"
      ]
    },
    "type": {
      "any_": [
        "<string>"
      ]
    }
  },
  "work_pool_queues": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "name": {
      "any_": [
        "wq-1",
        "wq-2"
      ],
      "startswith_": [
        "marvin",
        "Marvin-robot"
      ]
    }
  },
  "limit": 123
}
'

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created": "2023-11-07T05:31:56Z",
    "updated": "2023-11-07T05:31:56Z",
    "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "state_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "deployment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "deployment_version": "1.0",
    "work_queue_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "work_queue_name": "<string>",
    "flow_version": "1.0",
    "parameters": {},
    "idempotency_key": "<string>",
    "context": {},
    "empirical_policy": {
      "max_retries": 0,
      "retry_delay_seconds": 0,
      "retries": 123,
      "retry_delay": 123,
      "pause_keys": [
        "<string>"
      ],
      "resuming": false,
      "retry_type": "in_process"
    },
    "tags": [
      "<string>"
    ],
    "labels": {},
    "parent_task_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "state_type": "SCHEDULED",
    "state_name": "<string>",
    "run_count": 0,
    "expected_start_time": "2023-11-07T05:31:56Z",
    "next_scheduled_start_time": "2023-11-07T05:31:56Z",
    "start_time": "2023-11-07T05:31:56Z",
    "end_time": "2023-11-07T05:31:56Z",
    "total_run_time": 0,
    "estimated_run_time": 0,
    "estimated_start_time_delta": 0,
    "auto_scheduled": false,
    "infrastructure_document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "infrastructure_pid": "<string>",
    "created_by": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "<string>",
      "display_value": "<string>"
    },
    "work_pool_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "work_pool_name": "my-work-pool",
    "state": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "SCHEDULED",
      "name": "<string>",
      "timestamp": "2023-11-07T05:31:56Z",
      "message": "Run started",
      "data": "<unknown>",
      "state_details": {
        "flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "task_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "child_flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "scheduled_time": "2023-11-07T05:31:56Z",
        "cache_key": "<string>",
        "cache_expiration": "2023-11-07T05:31:56Z",
        "deferred": false,
        "untrackable_result": false,
        "pause_timeout": "2023-11-07T05:31:56Z",
        "pause_reschedule": false,
        "pause_key": "<string>",
        "run_input_keyset": {},
        "refresh_cache": true,
        "retriable": true,
        "transition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "task_parameters_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "traceparent": "<string>",
        "deployment_concurrency_lease_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    },
    "job_variables": {}
  }
]

POST

api

flow_runs

filter

Read Flow Runs

curl --request POST \
  --url https://api.example.com/api/flow_runs/filter \
  --header 'Content-Type: application/json' \
  --data '
{
  "sort": "ID_DESC",
  "offset": 0,
  "flows": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "deployment": {
      "operator": "and_",
      "is_null_": true
    },
    "name": {
      "any_": [
        "my-flow-1",
        "my-flow-2"
      ],
      "like_": "marvin"
    },
    "tags": {
      "operator": "and_",
      "all_": [
        "tag-1",
        "tag-2"
      ],
      "is_null_": true
    }
  },
  "flow_runs": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "not_any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "name": {
      "any_": [
        "my-flow-run-1",
        "my-flow-run-2"
      ],
      "like_": "marvin"
    },
    "tags": {
      "operator": "and_",
      "all_": [
        "tag-1",
        "tag-2"
      ],
      "any_": [
        "tag-1",
        "tag-2"
      ],
      "is_null_": true
    },
    "deployment_id": {
      "operator": "and_",
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "is_null_": true
    },
    "work_queue_name": {
      "operator": "and_",
      "any_": [
        "work_queue_1",
        "work_queue_2"
      ],
      "is_null_": true
    },
    "state": {
      "operator": "and_",
      "type": {
        "any_": [
          "SCHEDULED"
        ],
        "not_any_": [
          "SCHEDULED"
        ]
      },
      "name": {
        "any_": [
          "<string>"
        ],
        "not_any_": [
          "<string>"
        ]
      }
    },
    "flow_version": {
      "any_": [
        "<string>"
      ]
    },
    "start_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z",
      "is_null_": true
    },
    "end_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z",
      "is_null_": true
    },
    "expected_start_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z"
    },
    "next_scheduled_start_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z"
    },
    "parent_flow_run_id": {
      "operator": "and_",
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "parent_task_run_id": {
      "operator": "and_",
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "is_null_": true
    },
    "idempotency_key": {
      "any_": [
        "<string>"
      ],
      "not_any_": [
        "<string>"
      ]
    }
  },
  "task_runs": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "name": {
      "any_": [
        "my-task-run-1",
        "my-task-run-2"
      ],
      "like_": "marvin"
    },
    "tags": {
      "operator": "and_",
      "all_": [
        "tag-1",
        "tag-2"
      ],
      "is_null_": true
    },
    "state": {
      "operator": "and_",
      "type": {
        "any_": [
          "SCHEDULED"
        ]
      },
      "name": {
        "any_": [
          "<string>"
        ]
      }
    },
    "start_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z",
      "is_null_": true
    },
    "expected_start_time": {
      "before_": "2023-11-07T05:31:56Z",
      "after_": "2023-11-07T05:31:56Z"
    },
    "subflow_runs": {
      "exists_": true
    },
    "flow_run_id": {
      "operator": "and_",
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "is_null_": false
    }
  },
  "deployments": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ],
      "not_any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "name": {
      "any_": [
        "my-deployment-1",
        "my-deployment-2"
      ],
      "like_": "marvin"
    },
    "flow_or_deployment_name": {
      "like_": "<string>"
    },
    "paused": {
      "eq_": true
    },
    "tags": {
      "operator": "and_",
      "all_": [
        "tag-1",
        "tag-2"
      ],
      "any_": [
        "tag-1",
        "tag-2"
      ],
      "is_null_": true
    },
    "work_queue_name": {
      "any_": [
        "work_queue_1",
        "work_queue_2"
      ]
    },
    "concurrency_limit": {
      "ge_": 123,
      "le_": 123,
      "is_null_": true
    }
  },
  "work_pools": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "name": {
      "any_": [
        "<string>"
      ]
    },
    "type": {
      "any_": [
        "<string>"
      ]
    }
  },
  "work_pool_queues": {
    "operator": "and_",
    "id": {
      "any_": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "name": {
      "any_": [
        "wq-1",
        "wq-2"
      ],
      "startswith_": [
        "marvin",
        "Marvin-robot"
      ]
    }
  },
  "limit": 123
}
'

[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created": "2023-11-07T05:31:56Z",
    "updated": "2023-11-07T05:31:56Z",
    "flow_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "state_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "deployment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "deployment_version": "1.0",
    "work_queue_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "work_queue_name": "<string>",
    "flow_version": "1.0",
    "parameters": {},
    "idempotency_key": "<string>",
    "context": {},
    "empirical_policy": {
      "max_retries": 0,
      "retry_delay_seconds": 0,
      "retries": 123,
      "retry_delay": 123,
      "pause_keys": [
        "<string>"
      ],
      "resuming": false,
      "retry_type": "in_process"
    },
    "tags": [
      "<string>"
    ],
    "labels": {},
    "parent_task_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "state_type": "SCHEDULED",
    "state_name": "<string>",
    "run_count": 0,
    "expected_start_time": "2023-11-07T05:31:56Z",
    "next_scheduled_start_time": "2023-11-07T05:31:56Z",
    "start_time": "2023-11-07T05:31:56Z",
    "end_time": "2023-11-07T05:31:56Z",
    "total_run_time": 0,
    "estimated_run_time": 0,
    "estimated_start_time_delta": 0,
    "auto_scheduled": false,
    "infrastructure_document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "infrastructure_pid": "<string>",
    "created_by": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "<string>",
      "display_value": "<string>"
    },
    "work_pool_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "work_pool_name": "my-work-pool",
    "state": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "type": "SCHEDULED",
      "name": "<string>",
      "timestamp": "2023-11-07T05:31:56Z",
      "message": "Run started",
      "data": "<unknown>",
      "state_details": {
        "flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "task_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "child_flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "scheduled_time": "2023-11-07T05:31:56Z",
        "cache_key": "<string>",
        "cache_expiration": "2023-11-07T05:31:56Z",
        "deferred": false,
        "untrackable_result": false,
        "pause_timeout": "2023-11-07T05:31:56Z",
        "pause_reschedule": false,
        "pause_key": "<string>",
        "run_input_keyset": {},
        "refresh_cache": true,
        "retriable": true,
        "transition_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "task_parameters_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "traceparent": "<string>",
        "deployment_concurrency_lease_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    },
    "job_variables": {}
  }
]

Headers

x-prefect-api-version

string

Body

application/json

sort

enum<string>

default:ID_DESC

Defines flow run sorting options.

Available options:

ID_DESC,

START_TIME_ASC,

START_TIME_DESC,

EXPECTED_START_TIME_ASC,

EXPECTED_START_TIME_DESC,

NAME_ASC,

NAME_DESC,

NEXT_SCHEDULED_START_TIME_ASC,

END_TIME_DESC

offset

integer

default:0

Required range: x >= 0

flows

FlowFilter · object

Filter for flows. Only flows matching all criteria will be returned.

Show child attributes

flows.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flows.id

FlowFilterId · object

Filter criteria for Flow.id

Show child attributes

flows.id.any_

string<uuid>[] | null

A list of flow ids to include

flows.deployment

FlowFilterDeployment · object

Filter criteria for Flow deployments

Show child attributes

flows.deployment.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flows.deployment.is_null_

boolean | null

If true, only include flows without deployments

flows.name

FlowFilterName · object

Filter criteria for Flow.name

Show child attributes

flows.name.any_

string[] | null

A list of flow names to include

Example:

["my-flow-1", "my-flow-2"]

flows.name.like_

string | null

A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.

Example:

"marvin"

flows.tags

FlowFilterTags · object

Filter criteria for Flow.tags

Show child attributes

flows.tags.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flows.tags.all_

string[] | null

A list of tags. Flows will be returned only if their tags are a superset of the list

Example:

["tag-1", "tag-2"]

flows.tags.is_null_

boolean | null

If true, only include flows without tags

flow_runs

FlowRunFilter · object

Filter flow runs. Only flow runs matching all criteria will be returned

Show child attributes

flow_runs.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.id

FlowRunFilterId · object

Filter criteria for FlowRun.id

Show child attributes

flow_runs.id.any_

string<uuid>[] | null

A list of flow run ids to include

flow_runs.id.not_any_

string<uuid>[] | null

A list of flow run ids to exclude

flow_runs.name

FlowRunFilterName · object

Filter criteria for FlowRun.name

Show child attributes

flow_runs.name.any_

string[] | null

A list of flow run names to include

Example:

["my-flow-run-1", "my-flow-run-2"]

flow_runs.name.like_

string | null

A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.

Example:

"marvin"

flow_runs.tags

FlowRunFilterTags · object

Filter criteria for FlowRun.tags

Show child attributes

flow_runs.tags.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.tags.all_

string[] | null

A list of tags. Flow runs will be returned only if their tags are a superset of the list

Example:

["tag-1", "tag-2"]

flow_runs.tags.any_

string[] | null

A list of tags to include

Example:

["tag-1", "tag-2"]

flow_runs.tags.is_null_

boolean | null

If true, only include flow runs without tags

flow_runs.deployment_id

FlowRunFilterDeploymentId · object

Filter criteria for FlowRun.deployment_id

Show child attributes

flow_runs.deployment_id.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.deployment_id.any_

string<uuid>[] | null

A list of flow run deployment ids to include

flow_runs.deployment_id.is_null_

boolean | null

If true, only include flow runs without deployment ids

flow_runs.work_queue_name

FlowRunFilterWorkQueueName · object

Filter criteria for `FlowRun.work_queue_name

Show child attributes

flow_runs.work_queue_name.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.work_queue_name.any_

string[] | null

A list of work queue names to include

Example:

["work_queue_1", "work_queue_2"]

flow_runs.work_queue_name.is_null_

boolean | null

If true, only include flow runs without work queue names

flow_runs.state

FlowRunFilterState · object

Filter criteria for FlowRun.state

Show child attributes

flow_runs.state.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.state.type

FlowRunFilterStateType · object

Filter criteria for FlowRun.state_type

Show child attributes

flow_runs.state.type.any_

enum<string>[] | null

A list of flow run state types to include

Enumeration of state types.

Available options:

SCHEDULED,

PENDING,

RUNNING,

COMPLETED,

FAILED,

CANCELLED,

CRASHED,

PAUSED,

CANCELLING

flow_runs.state.type.not_any_

enum<string>[] | null

A list of flow run state types to exclude

Enumeration of state types.

Available options:

SCHEDULED,

PENDING,

RUNNING,

COMPLETED,

FAILED,

CANCELLED,

CRASHED,

PAUSED,

CANCELLING

flow_runs.state.name

FlowRunFilterStateName · object

Filter criteria for FlowRun.state_name

Show child attributes

flow_runs.state.name.any_

string[] | null

A list of flow run state names to include

flow_runs.state.name.not_any_

string[] | null

A list of flow run state names to exclude

flow_runs.flow_version

FlowRunFilterFlowVersion · object

Filter criteria for FlowRun.flow_version

Show child attributes

flow_runs.flow_version.any_

string[] | null

A list of flow run flow_versions to include

flow_runs.start_time

FlowRunFilterStartTime · object

Filter criteria for FlowRun.start_time

Show child attributes

flow_runs.start_time.before_

string<date-time> | null

Only include flow runs starting at or before this time

flow_runs.start_time.after_

string<date-time> | null

Only include flow runs starting at or after this time

flow_runs.start_time.is_null_

boolean | null

If true, only return flow runs without a start time

flow_runs.end_time

FlowRunFilterEndTime · object

Filter criteria for FlowRun.end_time

Show child attributes

flow_runs.end_time.before_

string<date-time> | null

Only include flow runs ending at or before this time

flow_runs.end_time.after_

string<date-time> | null

Only include flow runs ending at or after this time

flow_runs.end_time.is_null_

boolean | null

If true, only return flow runs without an end time

flow_runs.expected_start_time

FlowRunFilterExpectedStartTime · object

Filter criteria for FlowRun.expected_start_time

Show child attributes

flow_runs.expected_start_time.before_

string<date-time> | null

Only include flow runs scheduled to start at or before this time

flow_runs.expected_start_time.after_

string<date-time> | null

Only include flow runs scheduled to start at or after this time

flow_runs.next_scheduled_start_time

FlowRunFilterNextScheduledStartTime · object

Filter criteria for FlowRun.next_scheduled_start_time

Show child attributes

flow_runs.next_scheduled_start_time.before_

string<date-time> | null

Only include flow runs with a next_scheduled_start_time or before this time

flow_runs.next_scheduled_start_time.after_

string<date-time> | null

Only include flow runs with a next_scheduled_start_time at or after this time

flow_runs.parent_flow_run_id

FlowRunFilterParentFlowRunId · object

Filter criteria for subflows of the given flow runs

Show child attributes

flow_runs.parent_flow_run_id.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.parent_flow_run_id.any_

string<uuid>[] | null

A list of parent flow run ids to include

flow_runs.parent_task_run_id

FlowRunFilterParentTaskRunId · object

Filter criteria for FlowRun.parent_task_run_id

Show child attributes

flow_runs.parent_task_run_id.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

flow_runs.parent_task_run_id.any_

string<uuid>[] | null

A list of flow run parent_task_run_ids to include

flow_runs.parent_task_run_id.is_null_

boolean | null

If true, only include flow runs without parent_task_run_id

flow_runs.idempotency_key

FlowRunFilterIdempotencyKey · object

Filter criteria for FlowRun.idempotency_key

Show child attributes

flow_runs.idempotency_key.any_

string[] | null

A list of flow run idempotency keys to include

flow_runs.idempotency_key.not_any_

string[] | null

A list of flow run idempotency keys to exclude

task_runs

TaskRunFilter · object

Filter task runs. Only task runs matching all criteria will be returned

Show child attributes

task_runs.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

task_runs.id

TaskRunFilterId · object

Filter criteria for TaskRun.id

Show child attributes

task_runs.id.any_

string<uuid>[] | null

A list of task run ids to include

task_runs.name

TaskRunFilterName · object

Filter criteria for TaskRun.name

Show child attributes

task_runs.name.any_

string[] | null

A list of task run names to include

Example:

["my-task-run-1", "my-task-run-2"]

task_runs.name.like_

string | null

A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.

Example:

"marvin"

task_runs.tags

TaskRunFilterTags · object

Filter criteria for TaskRun.tags

Show child attributes

task_runs.tags.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

task_runs.tags.all_

string[] | null

A list of tags. Task runs will be returned only if their tags are a superset of the list

Example:

["tag-1", "tag-2"]

task_runs.tags.is_null_

boolean | null

If true, only include task runs without tags

task_runs.state

TaskRunFilterState · object

Filter criteria for TaskRun.state

Show child attributes

task_runs.state.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

task_runs.state.type

TaskRunFilterStateType · object

Filter criteria for TaskRun.state_type

Show child attributes

task_runs.state.type.any_

enum<string>[] | null

A list of task run state types to include

Enumeration of state types.

Available options:

SCHEDULED,

PENDING,

RUNNING,

COMPLETED,

FAILED,

CANCELLED,

CRASHED,

PAUSED,

CANCELLING

task_runs.state.name

TaskRunFilterStateName · object

Filter criteria for TaskRun.state_name

Show child attributes

task_runs.state.name.any_

string[] | null

A list of task run state names to include

task_runs.start_time

TaskRunFilterStartTime · object

Filter criteria for TaskRun.start_time

Show child attributes

task_runs.start_time.before_

string<date-time> | null

Only include task runs starting at or before this time

task_runs.start_time.after_

string<date-time> | null

Only include task runs starting at or after this time

task_runs.start_time.is_null_

boolean | null

If true, only return task runs without a start time

task_runs.expected_start_time

TaskRunFilterExpectedStartTime · object

Filter criteria for TaskRun.expected_start_time

Show child attributes

task_runs.expected_start_time.before_

string<date-time> | null

Only include task runs expected to start at or before this time

task_runs.expected_start_time.after_

string<date-time> | null

Only include task runs expected to start at or after this time

task_runs.subflow_runs

TaskRunFilterSubFlowRuns · object

Filter criteria for TaskRun.subflow_run

Show child attributes

task_runs.subflow_runs.exists_

boolean | null

If true, only include task runs that are subflow run parents; if false, exclude parent task runs

task_runs.flow_run_id

TaskRunFilterFlowRunId · object

Filter criteria for TaskRun.flow_run_id

Show child attributes

task_runs.flow_run_id.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

task_runs.flow_run_id.any_

string<uuid>[] | null

A list of task run flow run ids to include

task_runs.flow_run_id.is_null_

boolean | null

default:false

Filter for task runs with None as their flow run id

deployments

DeploymentFilter · object

Filter for deployments. Only deployments matching all criteria will be returned.

Show child attributes

deployments.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

deployments.id

DeploymentFilterId · object

Filter criteria for Deployment.id

Show child attributes

deployments.id.any_

string<uuid>[] | null

A list of deployment ids to include

deployments.id.not_any_

string<uuid>[] | null

A list of deployment ids to exclude

deployments.name

DeploymentFilterName · object

Filter criteria for Deployment.name

Show child attributes

deployments.name.any_

string[] | null

A list of deployment names to include

Example:

["my-deployment-1", "my-deployment-2"]

deployments.name.like_

string | null

A case-insensitive partial match. For example, passing 'marvin' will match 'marvin', 'sad-Marvin', and 'marvin-robot'.

Example:

"marvin"

deployments.flow_or_deployment_name

DeploymentOrFlowNameFilter · object

Filter criteria for Deployment.name or Flow.name

Show child attributes

deployments.flow_or_deployment_name.like_

string | null

A case-insensitive partial match on deployment or flow names. For example, passing 'example' might match deployments or flows with 'example' in their names.

deployments.paused

DeploymentFilterPaused · object

Filter criteria for Deployment.paused

Show child attributes

deployments.paused.eq_

boolean | null

Only returns where deployment is/is not paused

deployments.tags

DeploymentFilterTags · object

Filter criteria for Deployment.tags

Show child attributes

deployments.tags.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

deployments.tags.all_

string[] | null

A list of tags. Deployments will be returned only if their tags are a superset of the list

Example:

["tag-1", "tag-2"]

deployments.tags.any_

string[] | null

A list of tags to include

Example:

["tag-1", "tag-2"]

deployments.tags.is_null_

boolean | null

If true, only include deployments without tags

deployments.work_queue_name

DeploymentFilterWorkQueueName · object

Filter criteria for Deployment.work_queue_name

Show child attributes

deployments.work_queue_name.any_

string[] | null

A list of work queue names to include

Example:

["work_queue_1", "work_queue_2"]

deployments.concurrency_limit

DeploymentFilterConcurrencyLimit · object

deprecated

DEPRECATED: Prefer Deployment.concurrency_limit_id over Deployment.concurrency_limit. If provided, will be ignored for backwards-compatibility. Will be removed after December 2024.

Show child attributes

deployments.concurrency_limit.ge_

integer | null

Only include deployments with a concurrency limit greater than or equal to this value

deployments.concurrency_limit.le_

integer | null

Only include deployments with a concurrency limit less than or equal to this value

deployments.concurrency_limit.is_null_

boolean | null

If true, only include deployments without a concurrency limit

work_pools

WorkPoolFilter · object

Filter work pools. Only work pools matching all criteria will be returned

Show child attributes

work_pools.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

work_pools.id

WorkPoolFilterId · object

Filter criteria for WorkPool.id

Show child attributes

work_pools.id.any_

string<uuid>[] | null

A list of work pool ids to include

work_pools.name

WorkPoolFilterName · object

Filter criteria for WorkPool.name

Show child attributes

work_pools.name.any_

string[] | null

A list of work pool names to include

work_pools.type

WorkPoolFilterType · object

Filter criteria for WorkPool.type

Show child attributes

work_pools.type.any_

string[] | null

A list of work pool types to include

work_pool_queues

WorkQueueFilter · object

Filter work queues. Only work queues matching all criteria will be returned

Show child attributes

work_pool_queues.operator

enum<string>

default:and_

Operator for combining filter criteria. Defaults to 'and_'.

Available options:

and_,

or_

work_pool_queues.id

WorkQueueFilterId · object

Filter criteria for WorkQueue.id

Show child attributes

work_pool_queues.id.any_

string<uuid>[] | null

A list of work queue ids to include

work_pool_queues.name

WorkQueueFilterName · object

Filter criteria for WorkQueue.name

Show child attributes

work_pool_queues.name.any_

string[] | null

A list of work queue names to include

Example:

["wq-1", "wq-2"]

work_pool_queues.name.startswith_

string[] | null

A list of case-insensitive starts-with matches. For example, passing 'marvin' will match 'marvin', and 'Marvin-robot', but not 'sad-marvin'.

Example:

["marvin", "Marvin-robot"]

limit

integer

Defaults to PREFECT_API_DEFAULT_LIMIT if not provided.

Response

Successful Response

string<uuid>

required

created

string<date-time> | null

required

updated

string<date-time> | null

required

flow_id

string<uuid>

required

The id of the flow being run.

name

string

The name of the flow run. Defaults to a random slug if not specified.

state_id

string<uuid> | null

The id of the flow run's current state.

deployment_id

string<uuid> | null

The id of the deployment associated with this flow run, if available.

deployment_version

string | null

The version of the deployment associated with this flow run.

Example:

"1.0"

work_queue_id

string<uuid> | null

The id of the run's work pool queue.

work_queue_name

string | null

The work queue that handled this flow run.

flow_version

string | null

The version of the flow executed in this flow run.

Example:

"1.0"

parameters

Parameters · object

Parameters for the flow run.

idempotency_key

string | null

An optional idempotency key for the flow run. Used to ensure the same flow run is not created multiple times.

context

Context · object

Additional context for the flow run.

empirical_policy

FlowRunPolicy · object

Defines of how a flow run should retry.

Show child attributes

empirical_policy.max_retries

integer

default:0

deprecated

The maximum number of retries. Field is not used. Please use retries instead.

empirical_policy.retry_delay_seconds

number

default:0

deprecated

The delay between retries. Field is not used. Please use retry_delay instead.

empirical_policy.retries

integer | null

The number of retries.

empirical_policy.retry_delay

integer | null

The delay time between retries, in seconds.

empirical_policy.pause_keys

string[] | null

Tracks pauses this run has observed.

empirical_policy.resuming

boolean | null

default:false

Indicates if this run is resuming from a pause.

empirical_policy.retry_type

enum<string> | null

The type of retry this run is undergoing.

Available options:

in_process,

reschedule

API Reference

Headers

Body

Response