Paginate Task Runs

API Reference

Overview
Python SDK Overview
Settings reference
REST API
- REST API overview
- Cloud API
- Server API
  - Server API Overview
  - Root
  - Flows
  - Flow Runs
  - Task Runs
    - POST
      Create Task Run
    - GET
      Read Task Run
    - DEL
      Delete Task Run
    - PATCH
      Update Task Run
    - POST
      Count Task Runs
    - POST
      Task Run History
    - POST
      Read Task Runs
    - POST
      Paginate Task Runs
    - POST
      Set Task Run State
  - Flow Run States
  - Task Run States
  - Flow Run Notification Policies
  - Deployments
  - SavedSearches
  - Logs
  - Concurrency Limits
  - Concurrency Limits V2
  - Block types
  - Block documents
  - Work Pools
  - Task Workers
  - Work Queues
  - Artifacts
  - Block schemas
  - Block capabilities
  - Collections
  - Variables
  - GET
    Create Csrf Token
  - Events
  - Automations
  - Admin
CLI Reference

POST

api

task_runs

paginate

{
  "results": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created": "2023-11-07T05:31:56Z",
      "updated": "2023-11-07T05:31:56Z",
      "name": "my-task-run",
      "flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "task_key": "<string>",
      "state_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "state": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "type": "SCHEDULED",
        "name": "<string>",
        "timestamp": "2023-11-07T05:31:56Z",
        "message": "Run started",
        "data": "<any>",
        "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": true,
          "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>"
        }
      },
      "task_version": "1.0",
      "parameters": {},
      "task_inputs": {},
      "context": {
        "my_var": "my_val"
      },
      "empirical_policy": {
        "max_retries": 0,
        "retry_delay_seconds": 0,
        "retries": 123,
        "retry_delay": 123,
        "retry_jitter_factor": 123
      },
      "tags": [
        "tag-1",
        "tag-2"
      ]
    }
  ],
  "count": 123,
  "limit": 123,
  "pages": 123,
  "page": 123
}

Headers

x-prefect-api-version

string

Body

application/json

sort

enum<string>

Defines task run sorting options.

Available options:

ID_DESC,

EXPECTED_START_TIME_ASC,

EXPECTED_START_TIME_DESC,

NAME_ASC,

NAME_DESC,

NEXT_SCHEDULED_START_TIME_ASC,

END_TIME_DESC

page

integer

default:1

Required range: x >= 1

flows

object | null

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

flows.operator

enum<string>

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

Available options:

and_,

or_

flows.id

object | null

Filter criteria for Flow.id

flows.deployment

object | null

Filter criteria for Flow deployments

flows.name

object | null

Filter criteria for Flow.name

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

object | null

Filter criteria for Flow.tags

flows.tags.operator

enum<string>

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

object | null

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

flow_runs.operator

enum<string>

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

Available options:

and_,

or_

flow_runs.id

object | null

Filter criteria for FlowRun.id

flow_runs.name

object | null

Filter criteria for FlowRun.name

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

object | null

Filter criteria for FlowRun.tags

flow_runs.tags.operator

enum<string>

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

object | null

Filter criteria for FlowRun.deployment_id

flow_runs.work_queue_name

object | null

Filter criteria for `FlowRun.work_queue_name

flow_runs.work_queue_name.operator

enum<string>

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

object | null

Filter criteria for FlowRun.state

flow_runs.flow_version

object | null

Filter criteria for FlowRun.flow_version

flow_runs.start_time

object | null

Filter criteria for FlowRun.start_time

flow_runs.end_time

object | null

Filter criteria for FlowRun.end_time

flow_runs.expected_start_time

object | null

Filter criteria for FlowRun.expected_start_time

flow_runs.next_scheduled_start_time

object | null

Filter criteria for FlowRun.next_scheduled_start_time

flow_runs.parent_flow_run_id

object | null

Filter criteria for subflows of the given flow runs

flow_runs.parent_task_run_id

object | null

Filter criteria for FlowRun.parent_task_run_id

flow_runs.idempotency_key

object | null

Filter criteria for FlowRun.idempotency_key

task_runs

object | null

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

task_runs.operator

enum<string>

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

Available options:

and_,

or_

task_runs.id

object | null

Filter criteria for TaskRun.id

task_runs.name

object | null

Filter criteria for TaskRun.name

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

object | null

Filter criteria for TaskRun.tags

task_runs.tags.operator

enum<string>

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

object | null

Filter criteria for TaskRun.state

task_runs.start_time

object | null

Filter criteria for TaskRun.start_time

task_runs.expected_start_time

object | null

Filter criteria for TaskRun.expected_start_time

task_runs.subflow_runs

object | null

Filter criteria for TaskRun.subflow_run

task_runs.flow_run_id

object | null

Filter criteria for TaskRun.flow_run_id

deployments

object | null

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

deployments.operator

enum<string>

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

Available options:

and_,

or_

deployments.id

object | null

Filter criteria for Deployment.id

deployments.name

object | null

Filter criteria for Deployment.name

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

object | null

Filter criteria for Deployment.name or Flow.name

deployments.paused

object | null

Filter criteria for Deployment.paused

deployments.tags

object | null

Filter criteria for Deployment.tags

deployments.tags.operator

enum<string>

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

object | null

Filter criteria for Deployment.work_queue_name

deployments.concurrency_limit

object | null

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.

limit

integer

Defaults to PREFECT_API_DEFAULT_LIMIT if not provided.

Response

200

application/json

Successful Response

results

object[]

required

results.id

string

required

results.created

string | null

required

results.updated

string | null

required

results.task_key

string

required

The key of the task this run represents.

results.name

string

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

Example:

"my-task-run"

results.flow_run_id

string | null

The id of the flow run this task run belongs to.

results.state_id

string | null

The id of the task run's current state.

results.state

object | null

The current state of the task run.

results.task_version

string | null

The version of the task executed in this task run.

Example:

"1.0"

results.parameters

object

Parameters for the task run.

results.task_inputs

object

Inputs provided to the task run.

results.context

object

Additional context for the task run.

Example:

{ "my_var": "my_val" }

results.empirical_policy

object

The task run's empirical retry policy.

results.tags

string[]

A list of tags for the task run.

Example:

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

count

integer

required

limit

integer

required

pages

integer

required

page

integer

required

Was this page helpful?

Read Task Runs Set Task Run State

{
  "results": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created": "2023-11-07T05:31:56Z",
      "updated": "2023-11-07T05:31:56Z",
      "name": "my-task-run",
      "flow_run_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "task_key": "<string>",
      "state_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "state": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "type": "SCHEDULED",
        "name": "<string>",
        "timestamp": "2023-11-07T05:31:56Z",
        "message": "Run started",
        "data": "<any>",
        "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": true,
          "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>"
        }
      },
      "task_version": "1.0",
      "parameters": {},
      "task_inputs": {},
      "context": {
        "my_var": "my_val"
      },
      "empirical_policy": {
        "max_retries": 0,
        "retry_delay_seconds": 0,
        "retries": 123,
        "retry_delay": 123,
        "retry_jitter_factor": 123
      },
      "tags": [
        "tag-1",
        "tag-2"
      ]
    }
  ],
  "count": 123,
  "limit": 123,
  "pages": 123,
  "page": 123
}