Prefect REST API for interacting with Prefect Cloud & self-hosted Prefect server.
http://localhost:4200/docs
or the /docs
endpoint of the PREFECT_API_URL you have configured to access the server. You must have the server running with prefect server start
to access the interactive documentation.PrefectClient
, which is part of the Prefect Python SDK.PrefectClient
with self-hosted Prefect server:
--data-raw "{}"
is required and is where you can specify other aspects of the flow run such as the state. Windows users substitute ^
for \
for line multi-line commands.
prefect profile inspect my_profile
. This command will also display your Prefect API key, as shown below:
https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here
.
/flows
or /runs
).GET /flows/:id
.GET /task_runs
./task_runs
with a flow run filter instead of accessing /flow_runs/:id/task_runs
./api/:version
prefix that (optionally) allows versioning in the future. By convention, we treat that as part of the base URL and do not include that in API examples.POST
requests where applicable.
limit
and offset
.sort
parameter.GET
, PUT
and DELETE
requests are always idempotent. POST
and PATCH
are not guaranteed to be idempotent.GET
requests cannot receive information from the request body.POST
requests can receive information from the request body.POST /collection
creates a new member of the collection.GET /collection
lists all members of the collection.GET /collection/:id
gets a specific member of the collection by ID.DELETE /collection/:id
deletes a specific member of the collection.PUT /collection/:id
creates or replaces a specific member of the collection.PATCH /collection/:id
partially updates a specific member of the collection.POST /collection/action
is how we implement non-CRUD actions. For example, to set a flow run’s state, we use POST /flow_runs/:id/set_state
.POST /collection/action
may also be used for read-only queries. This is to allow us to send complex arguments as body arguments (which often cannot be done via GET
). Examples include POST /flow_runs/filter
, POST /flow_runs/count
, and POST /flow_runs/history
.POST
request. When multiple criteria are specified, logical AND will be applied to the criteria.
Filter criteria are structured as follows:
objects
is the name of the collection to filter over (for example, flows
). The collection can be either the object being queried for (flows
for POST /flows/filter
) or a related object (flow_runs
for POST /flows/filter
).
object_field
is the name of the field over which to filter (name
for flows
). Note that some objects may have nested object fields, such as {flow_run: {state: {type: {any_: []}}}}
.
field_operator_
is the operator to apply to a field when filtering. Common examples include:
any_
: return objects where this field matches any of the following values.is_null_
: return objects where this field is or is not null.eq_
: return objects where this field is equal to the following value.all_
: return objects where this field matches all of the following values.before_
: return objects where this datetime field is less than or equal to the following value.after_
: return objects where this datetime field is greater than or equal to the following value."database"
and failed flow runs, POST /flows/filter
with the following request body: