Sign in

v50

latestOpenAPI 3.1.0raw.githubusercontent.com2025-01-16170291390.7 KB
Flow Runs

Read Flow Runs

Query for flow runs.

post/api/flow_runs/filter

Headers

x-prefect-api-versionstring

Request body

sort'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'

Defines flow run sorting options.

offsetinteger
limitinteger

Defaults to PREFECT_API_DEFAULT_LIMIT if not provided.

Example request

{
  "flows": {
    "name": {
      "any_": [
        "my-flow-1",
        "my-flow-2"
      ],
      "like_": "marvin"
    },
    "tags": {
      "all_": [
        "tag-1",
        "tag-2"
      ]
    }
  },
  "flow_runs": {
    "name": {
      "any_": [
        "my-flow-run-1",
        "my-flow-run-2"
      ],
      "like_": "marvin"
    },
    "tags": {
      "all_": [
        "tag-1",
        "tag-2"
      ]
    },
    "work_queue_name": {
      "any_": [
        "work_queue_1",
        "work_queue_2"
      ]
    }
  },
  "task_runs": {
    "name": {
      "any_": [
        "my-task-run-1",
        "my-task-run-2"
      ],
      "like_": "marvin"
    },
    "tags": {
      "all_": [
        "tag-1",
        "tag-2"
      ]
    }
  },
  "deployments": {
    "name": {
      "any_": [
        "my-deployment-1",
        "my-deployment-2"
      ],
      "like_": "marvin"
    },
    "tags": {
      "all_": [
        "tag-1",
        "tag-2"
      ]
    },
    "work_queue_name": {
      "any_": [
        "work_queue_1",
        "work_queue_2"
      ]
    }
  },
  "work_pool_queues": {
    "name": {
      "any_": [
        "wq-1",
        "wq-2"
      ],
      "startswith_": [
        "marvin",
        "Marvin-robot"
      ]
    }
  }
}

Response

Successful Response

idstring uuid
createdstring date-time
updatedstring date-time
namestring

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

flow_idstring uuid required

The id of the flow being run.

state_idstring uuid

The id of the flow run's current state.

deployment_idstring uuid

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

deployment_versionstring

The version of the deployment associated with this flow run.

work_queue_idstring uuid

The id of the run's work pool queue.

work_queue_namestring

The work queue that handled this flow run.

flow_versionstring

The version of the flow executed in this flow run.

parametersobject

Parameters for the flow run.

idempotency_keystring

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

contextobject

Additional context for the flow run.

tagsstring[]

A list of tags on the flow run

parent_task_run_idstring uuid

If the flow run is a subflow, the id of the 'dummy' task in the parent flow used to track subflow state.

state_type'SCHEDULED' | 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'CRASHED' | 'PAUSED' | 'CANCELLING'

Enumeration of state types.

state_namestring

The name of the current flow run state.

run_countinteger

The number of times the flow run was executed.

expected_start_timestring date-time

The flow run's expected start time.

next_scheduled_start_timestring date-time

The next time the flow run is scheduled to start.

start_timestring date-time

The actual start time.

end_timestring date-time

The actual end time.

total_run_timenumber

Total run time. If the flow run was executed multiple times, the time of each run will be summed.

estimated_run_timenumber

A real-time estimate of the total run time.

estimated_start_time_deltanumber

The difference between actual and expected start time.

auto_scheduledboolean

Whether or not the flow run was automatically scheduled.

infrastructure_document_idstring uuid

The block document defining infrastructure to use this flow run.

infrastructure_pidstring

The id of the flow run as returned by an infrastructure block.

work_pool_idstring uuid

The id of the flow run's work pool.

work_pool_namestring

The name of the flow run's work pool.

job_variablesobject

Variables used as overrides in the base job template

Example response

[
  {
    "name": "my-flow-run",
    "deployment_version": "1.0",
    "flow_version": "1.0",
    "context": {
      "my_var": "my_val"
    },
    "tags": [
      "tag-1",
      "tag-2"
    ],
    "work_pool_name": "my-work-pool",
    "state": {
      "message": "Run started"
    }
  }
]