Read Settings - Prefect

Headers

x-prefect-api-version

string

Response

Successful Response

Settings for Prefect using Pydantic settings.

See https://docs.pydantic.dev/latest/concepts/pydantic_settings

home

string<path>

default:~/.prefect

The path to the Prefect home directory. Defaults to ~/.prefect

profiles_path

string<path>

The path to a profiles configuration file. Supports $PREFECT_HOME templating. Defaults to $PREFECT_HOME/profiles.toml.

debug_mode

boolean

default:false

If True, enables debug mode which may provide additional logging and debugging features.

api

APISettings · object

Settings for interacting with the Prefect API

Show child attributes

api.url

string | null

The URL of the Prefect API. If not set, the client will attempt to infer it.

api.auth_string

string<password> | null

The auth string used for basic authentication with a self-hosted Prefect API. Should be kept secret.

api.key

string<password> | null

The API key used for authentication with the Prefect API. Should be kept secret.

api.tls_insecure_skip_verify

boolean

default:false

If True, disables SSL checking to allow insecure requests. Setting to False is recommended only during development. For example, when using self-signed certificates.

api.ssl_cert_file

string | null

This configuration settings option specifies the path to an SSL certificate file.

api.enable_http2

boolean

default:false

If true, enable support for HTTP/2 for communicating with an API. If the API does not support HTTP/2, this will have no effect and connections will be made via HTTP/1.1.

api.request_timeout

number

default:60

The default timeout for requests to the API

cli

CLISettings · object

Settings for controlling CLI behavior

Show child attributes

cli.colors

boolean

default:true

If True, use colors in CLI output. If False, output will not include colors codes.

cli.prompt

boolean | null

If True, use interactive prompts in CLI commands. If False, no interactive prompts will be used. If None, the value will be dynamically determined based on the presence of an interactive-enabled terminal.

cli.wrap_lines

boolean

default:true

If True, wrap text by inserting new lines in long lines in CLI output. If False, output will not be wrapped.

client

ClientSettings · object

Settings for controlling API client behavior

Show child attributes

client.max_retries

integer

default:5

The maximum number of retries to perform on failed HTTP requests.
    Defaults to 5. Set to 0 to disable retries.
    See `PREFECT_CLIENT_RETRY_EXTRA_CODES` for details on which HTTP status codes are
    retried.

Required range: x >= 0

client.retry_jitter_factor

number

default:0.2

A value greater than or equal to zero to control the amount of jitter added to retried
    client requests. Higher values introduce larger amounts of jitter.
    Set to 0 to disable jitter. See `clamped_poisson_interval` for details on the how jitter
    can affect retry lengths.

Required range: x >= 0

client.retry_extra_codes

A list of extra HTTP status codes to retry on. Defaults to an empty list.
    429, 502 and 503 are always retried. Please note that not all routes are idempotent and retrying
    may result in unexpected behavior.

Example:

"404,429,503"

client.csrf_support_enabled

boolean

default:true

Determines if CSRF token handling is active in the Prefect client for API
    requests.

    When enabled (`True`), the client automatically manages CSRF tokens by
    retrieving, storing, and including them in applicable state-changing requests

client.custom_headers

Custom Headers · object

Custom HTTP headers to include with every API request to the Prefect server.
    Headers are specified as key-value pairs. Note that headers like 'User-Agent'
    and CSRF-related headers are managed by Prefect and cannot be overridden.

Show child attributes

client.custom_headers.{key}

string

client.metrics

ClientMetricsSettings · object

Settings for controlling metrics reporting from the client

Show child attributes

client.metrics.enabled

boolean

default:false

Whether or not to enable Prometheus metrics in the client.

client.metrics.port

integer

default:4201

The port to expose the client Prometheus metrics on.

cloud

CloudSettings · object

Settings for interacting with Prefect Cloud

Show child attributes

cloud.api_url

string

default:https://api.prefect.cloud/api

API URL for Prefect Cloud. Used for authentication with Prefect Cloud.

cloud.enable_orchestration_telemetry

boolean

default:true

Whether or not to enable orchestration telemetry.

cloud.max_log_size

integer

default:25000

Maximum size in characters for a single log when sending logs to Prefect Cloud.

cloud.ui_url

string | null

The URL of the Prefect Cloud UI. If not set, the client will attempt to infer it.

deployments

DeploymentsSettings · object

Settings for configuring deployments defaults

Show child attributes

deployments.default_work_pool_name

string | null

The default work pool to use when creating deployments.

deployments.default_docker_build_namespace

string | null

The default Docker namespace to use when building images.

Example:

"my-dockerhub-registry"

experiments

ExperimentsSettings · object

Settings for controlling experimental features

Show child attributes

experiments.warn

boolean

default:true

If True, warn on usage of experimental features.

experiments.plugins

PluginsSettings · object

Settings for the experimental plugin system

Show child attributes

experiments.plugins.enabled

boolean

default:false

Enable the experimental plugin system.

experiments.plugins.allow

string[] | null

Comma-separated list of plugin names to allow. If set, only these plugins will be loaded.

experiments.plugins.deny

string[] | null

Comma-separated list of plugin names to deny. These plugins will not be loaded.

experiments.plugins.setup_timeout_seconds

number

default:20

Maximum time in seconds for all plugins to complete their setup hooks.

experiments.plugins.strict

boolean

default:false

If True, exit if a required plugin fails during setup.

experiments.plugins.safe_mode

boolean

default:false

If True, load plugins but do not execute their hooks. Useful for testing.

flows

FlowsSettings · object

Settings for controlling flow behavior

Show child attributes

flows.default_retries

integer

default:0

This value sets the default number of retries for all flows.

Required range: x >= 0

flows.default_retry_delay_seconds

default:0

This value sets the default retry delay seconds for all flows.

internal

InternalSettings · object

Settings for internal Prefect machinery

Show child attributes

internal.logging_level

enum<string>

default:ERROR

The default logging level for Prefect's internal machinery loggers.

Available options:

DEBUG,

INFO,

WARNING,

ERROR,

CRITICAL

logging

LoggingSettings · object

Settings for controlling logging behavior

Show child attributes

logging.level

enum<string>

default:INFO

The default logging level for Prefect loggers.

Available options:

DEBUG,

INFO,

WARNING,

ERROR,

CRITICAL

logging.config_path

string<path>

A path to a logging configuration file. Defaults to $PREFECT_HOME/logging.yml

logging.extra_loggers

Additional loggers to attach to Prefect logging at runtime.

logging.log_prints

boolean

default:false

If True, print statements in flows and tasks will be redirected to the Prefect logger for the given run.

logging.colors

boolean

default:true

If True, use colors in CLI output. If False, output will not include colors codes.

logging.markup

boolean

default:false

Whether to interpret strings wrapped in square brackets as a style.
    This allows styles to be conveniently added to log messages, e.g.
    `[red]This is a red message.[/red]`. However, the downside is, if enabled,
    strings that contain square brackets may be inaccurately interpreted and
    lead to incomplete output, e.g.
    `[red]This is a red message.[/red]` may be interpreted as
    `[red]This is a red message.[/red]`.

logging.to_api

LoggingToAPISettings · object

Settings for controlling logging to the API

Show child attributes

logging.to_api.enabled

boolean

default:true

If True, logs will be sent to the API.

logging.to_api.batch_interval

number

default:2

The number of seconds between batched writes of logs to the API.

logging.to_api.batch_size

integer

default:4000000

The number of logs to batch before sending to the API.

logging.to_api.max_log_size

integer

default:1000000

The maximum size in characters for a single log. When connected to Prefect Cloud, this value is capped at PREFECT_CLOUD_MAX_LOG_SIZE (default 25,000).

logging.to_api.when_missing_flow

enum<string>

default:warn

Controls the behavior when loggers attempt to send logs to the API handler from outside of a flow.
    
    All logs sent to the API must be associated with a flow run. The API log handler can
    only be used outside of a flow by manually providing a flow run identifier. Logs
    that are not associated with a flow run will not be sent to the API. This setting can
    be used to determine if a warning or error is displayed when the identifier is missing.

    The following options are available:

    - "warn": Log a warning message.
    - "error": Raise an error.
    - "ignore": Do not log a warning message or raise an error.

Available options:

warn,

error,

ignore

results

ResultsSettings · object

Settings for controlling result storage behavior

Show child attributes

results.default_serializer

string

default:pickle

The default serializer to use when not otherwise specified.

results.persist_by_default

boolean

default:false

The default setting for persisting results when not otherwise specified.

results.default_storage_block

string | null

The block-type/block-document slug of a block to use as the default result storage.

results.local_storage_path

string<path>

The default location for locally persisted results. Defaults to $PREFECT_HOME/storage.

runner

RunnerSettings · object

Settings for controlling runner behavior

Show child attributes

runner.process_limit

integer

default:5

Maximum number of processes a runner will execute in parallel.

runner.poll_frequency

integer

default:10

Number of seconds a runner should wait between queries for scheduled work.

runner.heartbeat_frequency

integer | null

Number of seconds a runner should wait between heartbeats for flow runs.

Required range: x >= 30

runner.server

RunnerServerSettings · object

Settings for controlling runner server behavior

Show child attributes

runner.server.enable

boolean

default:false

Whether or not to enable the runner's webserver.

runner.server.host

string

default:localhost

The host address the runner's webserver should bind to.

runner.server.port

integer

default:8080

The port the runner's webserver should bind to.

runner.server.log_level

enum<string>

default:ERROR

The log level of the runner's webserver.

Available options:

DEBUG,

INFO,

WARNING,

ERROR,

CRITICAL

runner.server.missed_polls_tolerance

integer

default:2

Number of missed polls before a runner is considered unhealthy by its webserver.

server

ServerSettings · object

Settings for controlling server behavior

Show child attributes

server.logging_level

enum<string>

default:WARNING

The default logging level for the Prefect API server.

Available options:

DEBUG,

INFO,

WARNING,

ERROR,

CRITICAL

server.analytics_enabled

boolean

default:true

When enabled, Prefect sends anonymous data (e.g. count of flow runs, package version)
    on server startup to help us improve our product.

server.metrics_enabled

boolean

default:false

Whether or not to enable Prometheus metrics in the API.

server.log_retryable_errors

boolean

default:false

If True, log retryable errors in the API and it's services.

server.register_blocks_on_start

boolean

default:true

If set, any block types that have been imported will be registered with the backend on application startup. If not set, block types must be manually registered.

server.memoize_block_auto_registration

boolean

default:true

Controls whether or not block auto-registration on start

server.memo_store_path

string<path>

Path to the memo store file. Defaults to $PREFECT_HOME/memo_store.toml

server.deployment_schedule_max_scheduled_runs

integer

default:50

The maximum number of scheduled runs to create for a deployment.

server.api

ServerAPISettings · object

Settings for controlling API server behavior

Show child attributes

server.api.auth_string

string<password> | null

A string to use for basic authentication with the API in the form 'user:password'.

server.api.host

string

default:127.0.0.1

The API's host address (defaults to 127.0.0.1).

server.api.port

integer

default:4200

The API's port address (defaults to 4200).

server.api.base_path

string | null

The base URL path to serve the API under.

Example:

"/v2/api"

server.api.default_limit

integer

default:200

The default limit applied to queries that can return multiple objects, such as POST /flow_runs/filter.

server.api.keepalive_timeout

integer

default:5

The API's keep alive timeout (defaults to `5`).
    Refer to https://www.uvicorn.org/settings/#timeouts for details.

    When the API is hosted behind a load balancer, you may want to set this to a value
    greater than the load balancer's idle timeout.

    Note this setting only applies when calling `prefect server start`; if hosting the
    API with another tool you will need to configure this there instead.

server.api.csrf_protection_enabled

boolean

default:false

Controls the activation of CSRF protection for the Prefect server API.

    When enabled (`True`), the server enforces CSRF validation checks on incoming
    state-changing requests (POST, PUT, PATCH, DELETE), requiring a valid CSRF
    token to be included in the request headers or body. This adds a layer of
    security by preventing unauthorized or malicious sites from making requests on
    behalf of authenticated users.

    It is recommended to enable this setting in production environments where the
    API is exposed to web clients to safeguard against CSRF attacks.

    Note: Enabling this setting requires corresponding support in the client for
    CSRF token management. See PREFECT_CLIENT_CSRF_SUPPORT_ENABLED for more.

server.api.csrf_token_expiration

string<duration>

default:PT1H

Specifies the duration for which a CSRF token remains valid after being issued
    by the server.

    The default expiration time is set to 1 hour, which offers a reasonable
    compromise. Adjust this setting based on your specific security requirements
    and usage patterns.

server.api.cors_allowed_origins

string

default:*

A comma-separated list of origins that are authorized to make cross-origin requests to the API.

    By default, this is set to `*`, which allows requests from all origins.

server.api.cors_allowed_methods

string

default:*

A comma-separated list of methods that are authorized to make cross-origin requests to the API.

    By default, this is set to `*`, which allows requests from all methods.

server.api.cors_allowed_headers

string

default:*

A comma-separated list of headers that are authorized to make cross-origin requests to the API.

    By default, this is set to `*`, which allows requests from all headers.

server.concurrency

ServerConcurrencySettings · object

Settings for controlling server-side concurrency limit handling

Show child attributes

server.concurrency.lease_storage

string

default:prefect.server.concurrency.lease_storage.memory

The module to use for storing concurrency limit leases.

server.concurrency.initial_deployment_lease_duration

number

default:300

Initial duration for deployment concurrency lease in seconds.

Required range: 30 <= x <= 3600

server.concurrency.maximum_concurrency_slot_wait_seconds

number

default:30

The maximum number of seconds to wait before retrying when a concurrency slot cannot be acquired.

Required range: x >= 0

server.database

ServerDatabaseSettings · object

Settings for controlling server database behavior

Show child attributes

server.database.sqlalchemy

SQLAlchemySettings · object

Settings for controlling SQLAlchemy behavior

Show child attributes

server.database.sqlalchemy.connect_args

SQLAlchemyConnectArgsSettings · object

Settings for controlling SQLAlchemy connection behavior

Show child attributes

server.database.sqlalchemy.connect_args.application_name

string | null

Controls the application_name field for connections opened from the connection pool when using a PostgreSQL database with the Prefect backend.

server.database.sqlalchemy.connect_args.search_path

string | null

PostgreSQL schema name to set in search_path when using a PostgreSQL database with the Prefect backend. Note: The public schema should be included in the search path (e.g. 'myschema, public') to ensure that pg_trgm and other extensions remain available.

server.database.sqlalchemy.connect_args.statement_cache_size

integer | null

Controls statement cache size for PostgreSQL connections. Setting this to 0 is required when using PgBouncer in transaction mode. Defaults to None.

server.database.sqlalchemy.connect_args.prepared_statement_cache_size

integer | null

Controls the size of the statement cache for PostgreSQL connections. When set to 0, statement caching is disabled. Defaults to None to use SQLAlchemy's default behavior.

server.database.sqlalchemy.connect_args.tls

SQLAlchemyTLSSettings · object

Settings for controlling SQLAlchemy mTLS behavior

Show child attributes

server.database.sqlalchemy.connect_args.tls.enabled

boolean

default:false

Controls whether connected to mTLS enabled PostgreSQL when using a PostgreSQL database with the Prefect backend.

server.database.sqlalchemy.connect_args.tls.ca_file

string | null

This configuration settings option specifies the path to PostgreSQL client certificate authority file.

server.database.sqlalchemy.connect_args.tls.cert_file

string | null

This configuration settings option specifies the path to PostgreSQL client certificate file.

server.database.sqlalchemy.connect_args.tls.key_file

string | null

This configuration settings option specifies the path to PostgreSQL client key file.

server.database.sqlalchemy.connect_args.tls.check_hostname

boolean

default:true

This configuration settings option specifies whether to verify PostgreSQL server hostname.

server.database.sqlalchemy.pool_size

integer

default:5

Controls connection pool size of database connection pools from the Prefect backend.

server.database.sqlalchemy.pool_recycle

integer

default:3600

This setting causes the pool to recycle connections after the given number of seconds has passed; set it to -1 to avoid recycling entirely.

server.database.sqlalchemy.pool_timeout

number | null

default:30

Number of seconds to wait before giving up on getting a connection from the pool. Defaults to 30 seconds.

server.database.sqlalchemy.max_overflow

integer

default:10

Controls maximum overflow of the connection pool. To prevent overflow, set to -1.

server.database.connection_url

string<password> | null

A database connection URL in a SQLAlchemy-compatible
    format. Prefect currently supports SQLite and Postgres. Note that all
    Prefect database engines must use an async driver - for SQLite, use
    `sqlite+aiosqlite` and for Postgres use `postgresql+asyncpg`.

    SQLite in-memory databases can be used by providing the url
    `sqlite+aiosqlite:///file::memory:?cache=shared&uri=true&check_same_thread=false`,
    which will allow the database to be accessed by multiple threads. Note
    that in-memory databases can not be accessed from multiple processes and
    should only be used for simple tests.

server.database.driver

enum<string> | null

The database driver to use when connecting to the database. If not set, the driver will be inferred from the connection URL.

Available options:

postgresql+asyncpg,

sqlite+aiosqlite

server.database.host

string | null

The database server host.

server.database.port

integer | null

The database server port.

server.database.user

string | null

The user to use when connecting to the database.

server.database.name

string | null

The name of the Prefect database on the remote server, or the path to the database file for SQLite.

server.database.password

string<password> | null

The password to use when connecting to the database. Should be kept secret.

server.database.echo

boolean

default:false

If True, SQLAlchemy will log all SQL issued to the database. Defaults to False.

server.database.migrate_on_start

boolean

default:true

If True, the database will be migrated on application startup.

server.database.timeout

number | null

default:10

A statement timeout, in seconds, applied to all database interactions made by the Prefect backend. Defaults to 10 seconds.

server.database.connection_timeout

number | null

default:5

A connection timeout, in seconds, applied to database connections. Defaults to 5.

server.deployments

ServerDeploymentsSettings · object

Settings for controlling server deployments behavior

Show child attributes

server.deployments.concurrency_slot_wait_seconds

number

default:30

The number of seconds to wait before retrying when a deployment flow run cannot secure a concurrency slot from the server.

Required range: x >= 0

server.docket

ServerDocketSettings · object

Settings for controlling server Docket behavior

Show child attributes

server.docket.name

string

default:prefect-server

The name of the Docket instance.

server.docket.url

string

default:memory://

The URL of the Redis server to use for Docket.

server.ephemeral

ServerEphemeralSettings · object

Settings for controlling ephemeral server behavior

Show child attributes

server.ephemeral.enabled

boolean

default:false

Controls whether or not a subprocess server can be started when no API URL is provided.

server.ephemeral.startup_timeout_seconds

integer

default:20

The number of seconds to wait for the server to start when ephemeral mode is enabled.
    Defaults to `20`.

server.events

ServerEventsSettings · object

Settings for controlling server events behavior

Show child attributes

server.events.stream_out_enabled

boolean

default:true

Whether or not to stream events out to the API via websockets.

The number of seconds to cache related resources for in the API.

server.events.maximum_labels_per_resource

integer

default:500

The maximum number of labels a resource may have.

The maximum number of related resources an Event may have.

server.events.maximum_size_bytes

integer

default:1500000

The maximum size of an Event when serialized to JSON

server.events.expired_bucket_buffer

string<duration>

default:PT1M

The amount of time to retain expired automation buckets

server.events.proactive_granularity

string<duration>

default:PT5S

How frequently proactive automations are evaluated

server.events.retention_period

string<duration>

default:P7D

The amount of time to retain events in the database.

server.events.maximum_websocket_backfill

string<duration>

default:PT15M

The maximum range to look back for backfilling events for a websocket subscriber.

server.events.websocket_backfill_page_size

integer

default:250

The page size for the queries to backfill events for websocket subscribers.

server.events.messaging_broker

string

default:prefect.server.utilities.messaging.memory

Which message broker implementation to use for the messaging system, should point to a module that exports a Publisher and Consumer class.

server.events.messaging_cache

string

default:prefect.server.utilities.messaging.memory

Which cache implementation to use for the events system. Should point to a module that exports a Cache class.

server.events.causal_ordering

string

default:prefect.server.events.ordering.memory

Which causal ordering implementation to use for the events system. Should point to a module that exports a CausalOrdering class.

server.events.maximum_event_name_length

integer

default:1024

The maximum length of an event name.

server.flow_run_graph

ServerFlowRunGraphSettings · object

Settings for controlling flow run graph behavior

Show child attributes

server.flow_run_graph.max_nodes

integer

default:10000

The maximum size of a flow run graph on the v2 API

server.flow_run_graph.max_artifacts

integer

default:10000

The maximum number of artifacts to show on a flow run graph on the v2 API

server.logs

ServerLogsSettings · object

Settings for controlling server logs behavior

Show child attributes

server.logs.stream_out_enabled

boolean

default:false

Whether or not to stream logs out to the API via websockets.

server.logs.stream_publishing_enabled

boolean

default:false

Whether or not to publish logs to the streaming system.

server.services

ServerServicesSettings · object

Settings for controlling server services behavior

Show child attributes

server.services.cancellation_cleanup

ServerServicesCancellationCleanupSettings · object

Settings for controlling the cancellation cleanup service

Show child attributes

server.services.cancellation_cleanup.enabled

boolean

default:true

Whether or not to start the cancellation cleanup service in the server application.

server.services.cancellation_cleanup.loop_seconds

number

default:20

The cancellation cleanup service will look for non-terminal tasks and subflows this often. Defaults to 20.

server.services.event_persister

ServerServicesEventPersisterSettings · object

Settings for controlling the event persister service

Show child attributes

server.services.event_persister.enabled

boolean

default:true

Whether or not to start the event persister service in the server application.

server.services.event_persister.batch_size

integer

default:20

The number of events the event persister will attempt to insert in one batch.

server.services.event_persister.read_batch_size

integer

default:1

The number of events the event persister will attempt to read from the message broker in one batch.

server.services.event_persister.flush_interval

number

default:5

The maximum number of seconds between flushes of the event persister.

server.services.event_persister.batch_size_delete

integer

default:10000

The number of expired events and event resources the event persister will attempt to delete in one batch.

server.services.event_persister.queue_max_size

integer

default:50000

The maximum number of events that can be queued in memory for persistence. When the queue is full, new events will be dropped.

server.services.event_persister.max_flush_retries

integer

default:5

The maximum number of consecutive flush failures before events are dropped instead of being re-queued.

server.services.event_logger

ServerServicesEventLoggerSettings · object

Settings for controlling the event logger service

Show child attributes

server.services.event_logger.enabled

boolean

default:false

Whether or not to start the event logger service in the server application.

server.services.foreman

ServerServicesForemanSettings · object

Settings for controlling the foreman service

Show child attributes

server.services.foreman.enabled

boolean

default:true

Whether or not to start the foreman service in the server application.

server.services.foreman.loop_seconds

number

default:15

The foreman service will check for offline workers this often. Defaults to 15.

server.services.foreman.inactivity_heartbeat_multiple

integer

default:3

The number of heartbeats that must be missed before a worker is marked as offline. Defaults to `3`.

server.services.foreman.fallback_heartbeat_interval_seconds

integer

default:30

The number of seconds to use for online/offline evaluation if a worker's heartbeat
    interval is not set. Defaults to `30`.

server.services.foreman.deployment_last_polled_timeout_seconds

integer

default:60

The number of seconds before a deployment is marked as not ready if it has not been
    polled. Defaults to `60`.

server.services.foreman.work_queue_last_polled_timeout_seconds

integer

default:60

The number of seconds before a work queue is marked as not ready if it has not been
    polled. Defaults to `60`.

server.services.late_runs

ServerServicesLateRunsSettings · object

Settings for controlling the late runs service

Show child attributes

server.services.late_runs.enabled

boolean

default:true

Whether or not to start the late runs service in the server application.

server.services.late_runs.loop_seconds

number

default:5

The late runs service will look for runs to mark as late this often. Defaults to `5`.

server.services.late_runs.after_seconds

string<duration>

default:PT15S

The late runs service will mark runs as late after they have exceeded their scheduled start time by this many seconds. Defaults to `5` seconds.

server.services.scheduler

ServerServicesSchedulerSettings · object

Settings for controlling the scheduler service

Show child attributes

server.services.scheduler.enabled

boolean

default:true

Whether or not to start the scheduler service in the server application.

server.services.scheduler.loop_seconds

number

default:60

The scheduler loop interval, in seconds. This determines
    how often the scheduler will attempt to schedule new flow runs, but has no
    impact on how quickly either flow runs or task runs are actually executed.
    Defaults to `60`.

server.services.scheduler.deployment_batch_size

integer

default:100

The number of deployments the scheduler will attempt to
    schedule in a single batch. If there are more deployments than the batch
    size, the scheduler immediately attempts to schedule the next batch; it
    does not sleep for `scheduler_loop_seconds` until it has visited every
    deployment once. Defaults to `100`.

server.services.scheduler.max_runs

integer

default:100

The scheduler will attempt to schedule up to this many
    auto-scheduled runs in the future. Note that runs may have fewer than
    this many scheduled runs, depending on the value of
    `scheduler_max_scheduled_time`.  Defaults to `100`.

server.services.scheduler.min_runs

integer

default:3

The scheduler will attempt to schedule at least this many
    auto-scheduled runs in the future. Note that runs may have more than
    this many scheduled runs, depending on the value of
    `scheduler_min_scheduled_time`.  Defaults to `3`.

server.services.scheduler.max_scheduled_time

string<duration>

default:P100D

The scheduler will create new runs up to this far in the
    future. Note that this setting will take precedence over
    `scheduler_max_runs`: if a flow runs once a month and
    `scheduler_max_scheduled_time` is three months, then only three runs will be
    scheduled. Defaults to 100 days (`8640000` seconds).

server.services.scheduler.min_scheduled_time

string<duration>

default:PT1H

The scheduler will create new runs at least this far in the
    future. Note that this setting will take precedence over `scheduler_min_runs`:
    if a flow runs every hour and `scheduler_min_scheduled_time` is three hours,
    then three runs will be scheduled even if `scheduler_min_runs` is 1. Defaults to

server.services.scheduler.insert_batch_size

integer

default:500

The number of runs the scheduler will attempt to insert in a single batch.
    Defaults to `500`.

server.services.scheduler.recent_deployments_loop_seconds

number

default:5

The number of seconds the recent deployments scheduler will wait between checking for recently updated deployments. Defaults to `5`.

server.services.pause_expirations

ServerServicesPauseExpirationsSettings · object

Settings for controlling the pause expiration service

Show child attributes

server.services.pause_expirations.enabled

boolean

default:true

Whether or not to start the paused flow run expiration service in the server
    application. If disabled, paused flows that have timed out will remain in a Paused state
    until a resume attempt.

server.services.pause_expirations.loop_seconds

number

default:5

The pause expiration service will look for runs to mark as failed this often. Defaults to `5`.

server.services.repossessor

ServerServicesRepossessorSettings · object

Settings for controlling the repossessor service

Show child attributes

server.services.repossessor.enabled

boolean

default:true

Whether or not to start the repossessor service in the server application.

server.services.repossessor.loop_seconds

number

default:15

The repossessor service will look for expired leases this often. Defaults to 15.

server.services.task_run_recorder

ServerServicesTaskRunRecorderSettings · object

Settings for controlling the task run recorder service

Show child attributes

server.services.task_run_recorder.enabled

boolean

default:true

Whether or not to start the task run recorder service in the server application.

server.services.task_run_recorder.read_batch_size

integer

default:1

The number of task runs the task run recorder will attempt to read from the message broker in one batch.

server.services.triggers

ServerServicesTriggersSettings · object

Settings for controlling the triggers service

Show child attributes

server.services.triggers.enabled

boolean

default:true

Whether or not to start the triggers service in the server application.

server.services.triggers.read_batch_size

integer

default:1

The number of events the triggers service will attempt to read from the message broker in one batch.

server.services.triggers.pg_notify_reconnect_interval_seconds

integer

default:10

The number of seconds to wait before reconnecting to the PostgreSQL NOTIFY/LISTEN 
    connection after an error. Only used when using PostgreSQL as the database.
    Defaults to `10`.

server.services.triggers.pg_notify_heartbeat_interval_seconds

integer

default:5

The number of seconds between heartbeat checks for the PostgreSQL NOTIFY/LISTEN 
    connection to ensure it's still alive. Only used when using PostgreSQL as the database.
    Defaults to `5`.

server.tasks

ServerTasksSettings · object

Settings for controlling server tasks behavior

Show child attributes

server.tasks.tag_concurrency_slot_wait_seconds

number

default:30

The number of seconds to wait before retrying when a task run cannot secure a concurrency slot from the server.

Required range: x >= 0

server.tasks.max_cache_key_length

integer

default:2000

The maximum number of characters allowed for a task run cache key.

server.tasks.scheduling

ServerTasksSchedulingSettings · object

Settings for controlling server-side behavior related to task scheduling

Show child attributes

server.tasks.scheduling.max_scheduled_queue_size

integer

default:1000

The maximum number of scheduled tasks to queue for submission.

server.tasks.scheduling.max_retry_queue_size

integer

default:100

The maximum number of retries to queue for submission.

server.tasks.scheduling.pending_task_timeout

string<duration>

default:PT0S

How long before a PENDING task are made available to another task worker.

server.ui

ServerUISettings · object

Settings for controlling server UI behavior

Show child attributes

server.ui.enabled

boolean

default:true

Whether or not to serve the Prefect UI.

server.ui.api_url

string | null

The connection url for communication from the UI to the API. Defaults to PREFECT_API_URL if set. Otherwise, the default URL is generated from PREFECT_SERVER_API_HOST and PREFECT_SERVER_API_PORT.

server.ui.serve_base

string

default:/

The base URL path to serve the Prefect UI from.

server.ui.static_directory

string | null

The directory to serve static files from. This should be used when running into permissions issues when attempting to serve the UI from the default directory (for example when running in a Docker container).

server.ui.show_promotional_content

boolean

default:true

Whether or not to display promotional content in the UI, including upgrade prompts and marketing banners.

tasks

TasksSettings · object

Settings for controlling task behavior

Show child attributes

tasks.refresh_cache

boolean

default:false

If True, enables a refresh of cached results: re-executing the task will refresh the cached results.

tasks.default_no_cache

boolean

default:false

If True, sets the default cache policy on all tasks to NO_CACHE.

tasks.disable_caching

boolean

default:false

If True, disables caching on all tasks regardless of cache policy.

tasks.default_retries

integer

default:0

This value sets the default number of retries for all tasks.

Required range: x >= 0

tasks.default_retry_delay_seconds

default:0

This value sets the default retry delay seconds for all tasks.

tasks.default_persist_result

boolean | null

If True, results will be persisted by default for all tasks. Set to False to disable persistence by default. Note that setting to False will override the behavior set by a parent flow or task.

tasks.runner

TasksRunnerSettings · object

Settings for controlling task runner behavior

Show child attributes

tasks.runner.thread_pool_max_workers

integer | null

The maximum number of workers for ThreadPoolTaskRunner.

Required range: x > 0

tasks.runner.process_pool_max_workers

integer | null

The maximum number of workers for ProcessPoolTaskRunner.

Required range: x > 0

tasks.scheduling

TasksSchedulingSettings · object

Settings for controlling client-side task scheduling behavior

Show child attributes

tasks.scheduling.default_storage_block

string | null

The block-type/block-document slug of a block to use as the default storage for autonomous tasks.

tasks.scheduling.delete_failed_submissions

boolean

default:true

Whether or not to delete failed task submissions from the database.

testing

TestingSettings · object

Settings used during testing

Show child attributes

testing.test_mode

boolean

default:false

If True, places the API in test mode. This may modify behavior to facilitate testing.

testing.unit_test_mode

boolean

default:false

This setting only exists to facilitate unit testing. If True, code is executing in a unit test context. Defaults to False.

testing.unit_test_loop_debug

boolean

default:true

If True turns on debug mode for the unit testing event loop.

testing.test_setting

any | null

default:FOO

This setting only exists to facilitate unit testing. If in test mode, this setting will return its value. Otherwise, it returns None.

worker

WorkerSettings · object

Settings for controlling worker behavior

Show child attributes

worker.heartbeat_seconds

number

default:30

Number of seconds a worker should wait between sending a heartbeat.

worker.query_seconds

number

default:10

Number of seconds a worker should wait between queries for scheduled work.

worker.prefetch_seconds

number

default:10

The number of seconds into the future a worker should query for scheduled work.

worker.webserver

WorkerWebserverSettings · object

Settings for a worker's webserver

Show child attributes

worker.webserver.host

string

default:0.0.0.0

The host address the worker's webserver should bind to.

worker.webserver.port

integer

default:8080

The port the worker's webserver should bind to.

ui_url

string | null

The URL of the Prefect UI. If not set, the client will attempt to infer it.

silence_api_url_misconfiguration

boolean

default:false

If `True`, disable the warning when a user accidentally misconfigure its `PREFECT_API_URL`
    Sometimes when a user manually set `PREFECT_API_URL` to a custom url,reverse-proxy for example,
    we would like to silence this warning so we will set it to `FALSE`.

API Reference

Headers

Response