Prefect

Prefect REST API

Prefect REST API endpoints from Prefect

Data & analytics#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Prefect REST API endpoints from Prefect

Endpoints 180

Root

  • GETHealth Check/health
  • GETServer Version/version
  • GETHello/helloSay hello!
  • GETPerform Readiness Check/ready

Flows

  • POSTCreate Flow/flows/Creates a new flow from the provided schema. If a flow with the same name already exists, the existing flow is returned. For more information, see…
  • GETRead Flow/flows/:idGet a flow by id.
  • DELETEDelete Flow/flows/:idDelete a flow by id.
  • PATCHUpdate Flow/flows/:idUpdates a flow.
  • POSTCount Flows/flows/countCount flows.
  • GETRead Flow By Name/flows/name/:nameGet a flow by name.
  • POSTRead Flows/flows/filterQuery for flows.
  • POSTBulk Delete Flows/flows/bulk_deleteBulk delete flows matching the specified filter criteria. This also deletes all associated deployments. Returns the IDs of flows that were deleted.
  • POSTPaginate Flows/flows/paginatePagination query for flows.

Flow Runs

  • POSTCreate Flow Run/flow_runs/Create a flow run. If a flow run with the same flow_id and idempotency key already exists, the existing flow run will be returned. If no state is provided,…
  • GETRead Flow Run/flow_runs/:idGet a flow run by id.
  • DELETEDelete Flow Run/flow_runs/:idDelete a flow run by id.
  • PATCHUpdate Flow Run/flow_runs/:idUpdates a flow run.
  • POSTCount Flow Runs/flow_runs/countQuery for flow runs.
  • POSTAverage Flow Run Lateness/flow_runs/latenessQuery for average flow-run lateness in seconds.
  • POSTFlow Run History/flow_runs/historyQuery for flow run history data across a given range and interval.
  • GETRead Flow Run Graph V1/flow_runs/:id/graphGet a task run dependency map for a given flow run.
  • GETRead Flow Run Graph V2/flow_runs/:id/graph-v2?since=0001-01-01T00:00:00ZGet a graph of the tasks and subflow runs for the given flow run
  • POSTResume Flow Run/flow_runs/:id/resumeResume a paused flow run.
  • POSTRead Flow Runs/flow_runs/filterQuery for flow runs.
  • POSTBulk Delete Flow Runs/flow_runs/bulk_deleteBulk delete flow runs matching the specified filter criteria. Returns the IDs of flow runs that were deleted.
  • POSTBulk Set Flow Run State/flow_runs/bulk_set_stateBulk set state for flow runs matching the specified filter criteria. Returns the orchestration results for each flow run.
  • POSTSet Flow Run State/flow_runs/:id/set_stateSet a flow run state, invoking any orchestration rules.
  • POSTCreate Flow Run Input/flow_runs/:id/inputCreate a key/value input for a flow run.
  • POSTFilter Flow Run Input/flow_runs/:id/input/filterFilter flow run inputs by key prefix
  • GETRead Flow Run Input/flow_runs/:id/input/:keyCreate a value from a flow run input
  • DELETEDelete Flow Run Input/flow_runs/:id/input/:keyDelete a flow run input
  • POSTPaginate Flow Runs/flow_runs/paginatePagination query for flow runs.
  • GETDownload Logs/flow_runs/:id/logs/downloadDownload all flow run logs as a CSV file, collecting all logs until there are no more logs to retrieve.
  • PATCHUpdate Flow Run Labels/flow_runs/:id/labelsUpdate the labels of a flow run.

Task Runs

  • POSTCreate Task Run/task_runs/Create a task run. If a task run with the same flow_run_id, task_key, and dynamic_key already exists, the existing task run will be returned. If no state is…
  • GETRead Task Run/task_runs/:idGet a task run by id.
  • DELETEDelete Task Run/task_runs/:idDelete a task run by id.
  • PATCHUpdate Task Run/task_runs/:idUpdates a task run.
  • POSTCount Task Runs/task_runs/countCount task runs.
  • POSTTask Run History/task_runs/historyQuery for task run history data across a given range and interval.
  • POSTRead Task Runs/task_runs/filterQuery for task runs.
  • POSTPaginate Task Runs/task_runs/paginatePagination query for task runs.
  • POSTSet Task Run State/task_runs/:id/set_stateSet a task run state, invoking any orchestration rules.

Flow Run States

  • GETRead Flow Run State/flow_run_states/:idGet a flow run state by id. For more information, see https://www.prefect.io/docs/v3/concepts/flows#final-state-determination.
  • GETRead Flow Run States/flow_run_states/?flow_run_id=3fa85f64-5717-4562-b3fc-2c963f66afa6Get states associated with a flow run.

Task Run States

  • GETRead Task Run State/task_run_states/:idGet a task run state by id. For more information, see https://www.prefect.io/docs/v3/concepts/tasks.
  • GETRead Task Run States/task_run_states/?task_run_id=3fa85f64-5717-4562-b3fc-2c963f66afa6Get states associated with a task run.

Observed States

  • GETRead Observed States/observed-states?query=string&order_by=NAME_ASC&limit=200Discover exact state names and types from retained run transitions. Search by case-insensitive name or type prefix. Timestamps describe retained history;…

Deployments

  • POSTCreate Deployment/deployments/Creates a new deployment from the provided schema. If a deployment with the same name and flow_id already exists, the deployment is updated. If the deployment…
  • GETRead Deployment/deployments/:idGet a deployment by id.
  • DELETEDelete Deployment/deployments/:idDelete a deployment by id.
  • PATCHUpdate Deployment/deployments/:id
  • GETRead Deployment By Name/deployments/name/:flow_name/:deployment_nameGet a deployment using the name of the flow and the deployment.
  • POSTRead Deployments/deployments/filterQuery for deployments.
  • POSTPaginate Deployments/deployments/paginatePagination query for flow runs.
  • POSTGet Scheduled Flow Runs For Deployments/deployments/get_scheduled_flow_runsGet scheduled runs for a set of deployments. Used by a runner to poll for work.
  • POSTCount Deployments/deployments/countCount deployments.
  • POSTBulk Delete Deployments/deployments/bulk_deleteBulk delete deployments matching the specified filter criteria. Returns the IDs of deployments that were deleted.
  • POSTSchedule Deployment/deployments/:id/scheduleSchedule runs for a deployment. For backfills, provide start/end times in the past. This function will generate the minimum number of runs that satisfy the…
  • POSTResume Deployment/deployments/:id/resume_deploymentSet a deployment schedule to active. Runs will be scheduled immediately.
  • POSTPause Deployment/deployments/:id/pause_deploymentSet a deployment schedule to inactive. Any auto-scheduled runs still in a Scheduled state will be deleted.
  • POSTCreate Flow Run From Deployment/deployments/:id/create_flow_runCreate a flow run from a deployment. Any parameters not provided will be inferred from the deployment's parameters. If tags are not provided, the deployment's…
  • POSTBulk Create Flow Runs From Deployment/deployments/:id/create_flow_run/bulkCreate multiple flow runs from a deployment. Any parameters not provided will be inferred from the deployment's parameters. If tags are not provided, the…
  • GETWork Queue Check For Deployment/deployments/:id/work_queue_checkDeprecated. Get list of work-queues that are able to pick up the specified deployment. This endpoint is intended to be used by the UI to provide users…
  • GETRead Deployment Schedules/deployments/:id/schedules
  • POSTCreate Deployment Schedules/deployments/:id/schedules
  • DELETEDelete Deployment Schedule/deployments/:id/schedules/:schedule_id
  • PATCHUpdate Deployment Schedule/deployments/:id/schedules/:schedule_id

SavedSearches

  • PUTCreate Saved Search/saved_searches/Creates a new saved search from the provided schema. If a saved search with the same name already exists, the saved search's fields are replaced.
  • GETRead Saved Search/saved_searches/:idGet a saved search by id.
  • DELETEDelete Saved Search/saved_searches/:idDelete a saved search by id.
  • POSTRead Saved Searches/saved_searches/filterQuery for saved searches.

Logs

  • POSTCreate Logs/logs/Create new logs from the provided schema. For more information, see https://www.prefect.io/docs/v3/how-to-guides/workflows/add-logging.
  • POSTRead Logs/logs/filterQuery for logs.

Concurrency Limits

  • POSTCreate Concurrency Limit/concurrency_limits/Create a task run concurrency limit. For more information, see https://www.prefect.io/docs/v3/concepts/tag-based-concurrency-limits.
  • GETRead Concurrency Limit/concurrency_limits/:idGet a concurrency limit by id. The active slots field contains a list of TaskRun IDs currently using a concurrency slot for the specified tag.
  • DELETEDelete Concurrency Limit/concurrency_limits/:id
  • GETRead Concurrency Limit By Tag/concurrency_limits/tag/:tagGet a concurrency limit by tag. The active slots field contains a list of TaskRun IDs currently using a concurrency slot for the specified tag.
  • DELETEDelete Concurrency Limit By Tag/concurrency_limits/tag/:tag
  • POSTRead Concurrency Limits/concurrency_limits/filterQuery for concurrency limits. For each concurrency limit the active slots field contains a list of TaskRun IDs currently using a concurrency slot for the…
  • POSTReset Concurrency Limit By Tag/concurrency_limits/tag/:tag/reset
  • POSTIncrement Concurrency Limits V1/concurrency_limits/incrementIncrement concurrency limits for the given tags. During migration, this handles both V1 and V2 limits to support mixed states. Post-migration, it only uses V2…
  • POSTDecrement Concurrency Limits V1/concurrency_limits/decrementDecrement concurrency limits for the given tags. Finds and revokes the lease for V2 limits or decrements V1 active slots. Returns the list of limits that were…

Concurrency Limits V2

  • POSTCreate Concurrency Limit V2/v2/concurrency_limits/Create a task run concurrency limit. For more information, see https://www.prefect.io/docs/v3/how-to-guides/workflows/global-concurrency-limits.
  • GETRead Concurrency Limit V2/v2/concurrency_limits/:id_or_name
  • DELETEDelete Concurrency Limit V2/v2/concurrency_limits/:id_or_name
  • PATCHUpdate Concurrency Limit V2/v2/concurrency_limits/:id_or_name
  • POSTRead All Concurrency Limits V2/v2/concurrency_limits/filter
  • POSTBulk Increment Active Slots/v2/concurrency_limits/increment
  • POSTBulk Increment Active Slots With Lease/v2/concurrency_limits/increment-with-lease
  • POSTBulk Decrement Active Slots/v2/concurrency_limits/decrement
  • POSTBulk Decrement Active Slots With Lease/v2/concurrency_limits/decrement-with-lease
  • POSTRenew Concurrency Lease/v2/concurrency_limits/leases/:lease_id/renew

Block types

  • POSTCreate Block Type/block_types/Create a new block type. For more information, see https://www.prefect.io/docs/v3/concepts/blocks.
  • GETRead Block Type By Id/block_types/:idGet a block type by ID.
  • DELETEDelete Block Type/block_types/:id
  • PATCHUpdate Block Type/block_types/:idUpdate a block type.
  • GETRead Block Type By Slug/block_types/slug/:slugGet a block type by name.
  • POSTRead Block Types/block_types/filterGets all block types. Optionally limit return with limit and offset.
  • GETRead Block Documents For Block Type/block_types/slug/:slug/block_documents?include_secrets=false
  • GETRead Block Document By Name For Block Type/block_types/slug/:slug/block_documents/name/:block_document_name?include_secrets=false
  • POSTInstall System Block Types/block_types/install_system_block_types

Block documents

  • POSTCreate Block Document/block_documents/Create a new block document. For more information, see https://www.prefect.io/docs/v3/concepts/blocks.
  • POSTRead Block Documents/block_documents/filterQuery for block documents.
  • POSTCount Block Documents/block_documents/countCount block documents.
  • GETRead Block Document By Id/block_documents/:id?include_secrets=false
  • DELETEDelete Block Document/block_documents/:id
  • PATCHUpdate Block Document Data/block_documents/:id

Work Pools

  • POSTCreate Work Pool/work_pools/Creates a new work pool. If a work pool with the same name already exists, an error will be raised. For more information, see…
  • GETRead Work Pool/work_pools/:nameRead a work pool by name
  • DELETEDelete Work Pool/work_pools/:nameDelete a work pool
  • PATCHUpdate Work Pool/work_pools/:nameUpdate a work pool
  • POSTRead Work Pools/work_pools/filterRead multiple work pools
  • POSTCount Work Pools/work_pools/countCount work pools
  • POSTRead Work Pool Concurrency Status/work_pools/:name/concurrency_statusRead concurrency status for a work pool, including per-queue breakdown with flow run summaries. Queues are paginated; flow runs per queue are capped by…
  • POSTGet Scheduled Flow Runs/work_pools/:name/get_scheduled_flow_runsLoad scheduled runs for a worker
  • POSTCreate Work Queue/work_pools/:work_pool_name/queuesCreates a new work pool queue. If a work pool queue with the same name already exists, an error will be raised. For more information, see…
  • GETRead Work Queue/work_pools/:work_pool_name/queues/:nameRead a work pool queue
  • DELETEDelete Work Queue/work_pools/:work_pool_name/queues/:nameDelete a work pool queue
  • PATCHUpdate Work Queue/work_pools/:work_pool_name/queues/:nameUpdate a work pool queue
  • POSTRead Work Queues/work_pools/:work_pool_name/queues/filterRead all work pool queues
  • POSTWorker Heartbeat/work_pools/:work_pool_name/workers/heartbeat
  • POSTRead Workers/work_pools/:work_pool_name/workers/filterRead all worker processes
  • DELETEDelete Worker/work_pools/:work_pool_name/workers/:nameDelete a work pool's worker

Task Workers

  • POSTRead Task Workers/task_workers/filterRead active task workers. Optionally filter by task keys. For more information, see https://www.prefect.io/docs/v3/how-to-guides/workflows/run-background-tasks.

Work Queues

  • POSTCreate Work Queue/work_queues/Creates a new work queue. If a work queue with the same name already exists, an error will be raised. For more information, see…
  • GETRead Work Queue/work_queues/:idGet a work queue by id.
  • DELETEDelete Work Queue/work_queues/:idDelete a work queue by id.
  • PATCHUpdate Work Queue/work_queues/:idUpdates an existing work queue.
  • GETRead Work Queue By Name/work_queues/name/:nameGet a work queue by id.
  • POSTRead Work Queue Runs/work_queues/:id/get_runsGet flow runs from the work queue.
  • POSTRead Work Queues/work_queues/filterQuery for work queues.
  • POSTRead Work Queue Concurrency Status/work_queues/:id/concurrency_statusRead concurrency status for a work queue, including paginated flow run summaries. active_slots always reflects the total count.
  • GETRead Work Queue Status/work_queues/:id/statusGet the status of a work queue.

Artifacts

  • POSTCreate Artifact/artifacts/Create an artifact. For more information, see https://www.prefect.io/docs/v3/concepts/artifacts.
  • GETRead Artifact/artifacts/:idRetrieve an artifact from the database.
  • DELETEDelete Artifact/artifacts/:idDelete an artifact from the database.
  • PATCHUpdate Artifact/artifacts/:idUpdate an artifact in the database.
  • GETRead Latest Artifact/artifacts/:key/latestRetrieve the latest artifact from the artifact table.
  • POSTRead Artifacts/artifacts/filterRetrieve artifacts from the database.
  • POSTRead Latest Artifacts/artifacts/latest/filterRetrieve artifacts from the database.
  • POSTCount Artifacts/artifacts/countCount artifacts from the database.
  • POSTCount Latest Artifacts/artifacts/latest/countCount artifacts from the database.

Block schemas

  • POSTCreate Block Schema/block_schemas/Create a block schema. For more information, see https://www.prefect.io/docs/v3/concepts/blocks.
  • GETRead Block Schema By Id/block_schemas/:idGet a block schema by id.
  • DELETEDelete Block Schema/block_schemas/:idDelete a block schema by id.
  • POSTRead Block Schemas/block_schemas/filterRead all block schemas, optionally filtered by type
  • GETRead Block Schema By Checksum/block_schemas/checksum/:checksum?version=string

Block capabilities

  • GETRead Available Block Capabilities/block_capabilities/Get available block capabilities. For more information, see https://www.prefect.io/docs/v3/concepts/blocks.

Collections

  • GETRead View Content/collections/views/:viewReads the content of a view from the prefect-collection-registry.

Variables

  • POSTCreate Variable/variables/Create a variable. For more information, see https://www.prefect.io/docs/v3/concepts/variables.
  • GETRead Variable/variables/:id
  • DELETEDelete Variable/variables/:id
  • PATCHUpdate Variable/variables/:id
  • GETRead Variable By Name/variables/name/:name
  • DELETEDelete Variable By Name/variables/name/:name
  • PATCHUpdate Variable By Name/variables/name/:name
  • POSTRead Variables/variables/filter
  • POSTCount Variables/variables/count

Events

  • POSTCreate Events/eventsRecord a batch of Events. For more information, see https://www.prefect.io/docs/v3/concepts/events.
  • POSTRead Events/events/filterQueries for Events matching the given filter criteria in the given Account. Returns the first page of results, and the URL to request the next page (if there…
  • GETRead Account Events Page/events/filter/next?page-token=stringReturns the next page of Events for a previous query against the given Account, and the URL to request the next page (if there are more results).
  • POSTCount Account Events/events/count-by/:countableReturns distinct objects and the count of events associated with them. Objects that can be counted include the day the event occurred, the type of event, or…

Automations

  • POSTCreate Automation/automations/Create an automation. For more information, see https://www.prefect.io/docs/v3/concepts/automations.
  • GETRead Automation/automations/:id
  • PUTUpdate Automation/automations/:id
  • DELETEDelete Automation/automations/:id
  • PATCHPatch Automation/automations/:id
  • POSTRead Automations/automations/filter
  • POSTCount Automations/automations/count
  • GETRead Automations Related To Resource/automations/related-to/:resource_id
  • DELETEDelete Automations Owned By Resource/automations/owned-by/:resource_id
  • POSTValidate Template/templates/validate
  • POSTValidate Template/automations/templates/validate

Admin

  • GETRead Settings/admin/settingsGet the current Prefect REST API settings. Secret setting values will be obfuscated.
  • GETRead Version/admin/versionReturns the Prefect version number
  • GETRead Server Default Result Storage/admin/storageGet the configured server default result storage block.
  • PUTUpdate Server Default Result Storage/admin/storageSet the server default result storage block.
  • DELETEClear Server Default Result Storage/admin/storageClear the configured server default result storage block.
  • GETCreate Csrf Token/csrf-token?client=stringCreate or update a CSRF token for a client

API details

Authentication
None declared in the description
Operations
180 operations on 142 pathsPOST 88GET 50DELETE 23PATCH 16PUT 3
1 marked deprecated
Main resources
Flow Runs 21Deployments 20Work Pools 16Automations 11Block types 11Concurrency Limits V2 10Artifacts 9Concurrency Limits 9Flows 9Task Runs 9
Response formats
application/json
Description format
OpenAPI 3.1.0, API version v3

How to test the Prefect REST API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Prefect REST API collection, without the publisher's secrets.
  3. Add your credentialsOpen the collection's variables or an environment and enter your API key or token, if the API needs one.
  4. Send a requestPick an endpoint, for example “Health Check” (GET /health), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Prefect REST API?

Prefect REST API endpoints from Prefect It is listed under Data & analytics and has 180 endpoints.

Who publishes the Prefect REST API?

It is listed from Prefect's public API description (an OpenAPI document), not published by Prefect on Swastik Codes. Anyone who controls prefect.io can claim the profile by adding a DNS TXT record.

How do I authenticate with the Prefect REST API?

Its OpenAPI description does not declare an authentication scheme. Some endpoints may be open; check the provider's documentation before relying on that.

How many endpoints does the Prefect REST API have?

180 operations on 142 paths (88 POST, 50 GET, 23 DELETE, 16 PATCH, 3 PUT). The largest groups are Flow Runs, Deployments, Work Pools, Automations.

Is forking the Prefect REST API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.