Settings reference

​

Root Settings

​

home

The path to the Prefect home directory. Defaults to ~/.prefect Type: string Default: ~/.prefect TOML dotted key path: home Supported environment variables: PREFECT_HOME

​

profiles_path

The path to a profiles configuration file. Supports $PREFECT_HOME templating. Defaults to$PREFECT_HOME/profiles.toml. Type: string TOML dotted key path: profiles_path Supported environment variables: PREFECT_PROFILES_PATH

​

debug_mode

If True, enables debug mode which may provide additional logging and debugging features. Type: boolean Default: False TOML dotted key path: debug_mode Supported environment variables: PREFECT_DEBUG_MODE

​

api

Type: APISettings TOML dotted key path: api

​

cli

Type: CLISettings TOML dotted key path: cli

​

client

Type: ClientSettings TOML dotted key path: client

​

cloud

Type: CloudSettings TOML dotted key path: cloud

​

deployments

Type: DeploymentsSettings TOML dotted key path: deployments

​

experiments

Settings for controlling experimental features Type: ExperimentsSettings TOML dotted key path: experiments

​

flows

Type: FlowsSettings TOML dotted key path: flows

​

internal

Settings for internal Prefect machinery Type: InternalSettings TOML dotted key path: internal

​

logging

Type: LoggingSettings TOML dotted key path: logging

​

results

Type: ResultsSettings TOML dotted key path: results

​

runner

Type: RunnerSettings TOML dotted key path: runner

​

server

Type: ServerSettings TOML dotted key path: server

​

tasks

Settings for controlling task behavior Type: TasksSettings TOML dotted key path: tasks

​

testing

Settings used during testing Type: TestingSettings TOML dotted key path: testing

​

worker

Settings for controlling worker behavior Type: WorkerSettings TOML dotted key path: worker

​

ui_url

The URL of the Prefect UI. If not set, the client will attempt to infer it. Type: string | None Default: None TOML dotted key path: ui_url Supported environment variables: PREFECT_UI_URL

​

silence_api_url_misconfiguration

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. Type: boolean Default: False TOML dotted key path: silence_api_url_misconfiguration Supported environment variables: PREFECT_SILENCE_API_URL_MISCONFIGURATION

---

​

APISettings

Settings for interacting with the Prefect API

​

url

The URL of the Prefect API. If not set, the client will attempt to infer it. Type: string | None Default: None TOML dotted key path: api.url Supported environment variables: PREFECT_API_URL

​

auth_string

The auth string used for basic authentication with a self-hosted Prefect API. Should be kept secret. Type: string | None Default: None TOML dotted key path: api.auth_string Supported environment variables: PREFECT_API_AUTH_STRING

​

key

The API key used for authentication with the Prefect API. Should be kept secret. Type: string | None Default: None TOML dotted key path: api.key Supported environment variables: PREFECT_API_KEY

​

tls_insecure_skip_verify

If True, disables SSL checking to allow insecure requests. Setting to False is recommended only during development. For example, when using self-signed certificates. Type: boolean Default: False TOML dotted key path: api.tls_insecure_skip_verify Supported environment variables: PREFECT_API_TLS_INSECURE_SKIP_VERIFY

​

ssl_cert_file

This configuration settings option specifies the path to an SSL certificate file. Type: string | None Default: None TOML dotted key path: api.ssl_cert_file Supported environment variables: PREFECT_API_SSL_CERT_FILE

​

enable_http2

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. Type: boolean Default: False TOML dotted key path: api.enable_http2 Supported environment variables: PREFECT_API_ENABLE_HTTP2

​

request_timeout

The default timeout for requests to the API Type: number Default: 60.0 TOML dotted key path: api.request_timeout Supported environment variables: PREFECT_API_REQUEST_TIMEOUT

---

​

CLISettings

Settings for controlling CLI behavior

​

colors

If True, use colors in CLI output. If False, output will not include colors codes. Type: boolean Default: True TOML dotted key path: cli.colors Supported environment variables: PREFECT_CLI_COLORS

​

prompt

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. Type: boolean | None Default: None TOML dotted key path: cli.prompt Supported environment variables: PREFECT_CLI_PROMPT

​

wrap_lines

If True, wrap text by inserting new lines in long lines in CLI output. If False, output will not be wrapped. Type: boolean Default: True TOML dotted key path: cli.wrap_lines Supported environment variables: PREFECT_CLI_WRAP_LINES

---

​

ClientMetricsSettings

Settings for controlling metrics reporting from the client

​

enabled

Whether or not to enable Prometheus metrics in the client. Type: boolean Default: False TOML dotted key path: client.metrics.enabled Supported environment variables: PREFECT_CLIENT_METRICS_ENABLED, PREFECT_CLIENT_ENABLE_METRICS

​

port

The port to expose the client Prometheus metrics on. Type: integer Default: 4201 TOML dotted key path: client.metrics.port Supported environment variables: PREFECT_CLIENT_METRICS_PORT

---

​

ClientSettings

Settings for controlling API client behavior

​

max_retries

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. Type: integer Default: 5 Constraints:

• Minimum: 0

TOML dotted key path: client.max_retries Supported environment variables: PREFECT_CLIENT_MAX_RETRIES

​

retry_jitter_factor

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. Type: number Default: 0.2 Constraints:

• Minimum: 0.0

TOML dotted key path: client.retry_jitter_factor Supported environment variables: PREFECT_CLIENT_RETRY_JITTER_FACTOR

​

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. Type: string | integer | array | None Examples:

• "404,429,503"
• "429"
• [404, 429, 503]

TOML dotted key path: client.retry_extra_codes Supported environment variables: PREFECT_CLIENT_RETRY_EXTRA_CODES

​

csrf_support_enabled

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 Type: boolean Default: True TOML dotted key path: client.csrf_support_enabled Supported environment variables: PREFECT_CLIENT_CSRF_SUPPORT_ENABLED

​

custom_headers

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. Type: object Examples:

• {'X-Custom-Header': 'value'}
• {'Authorization': 'Bearer token'}

TOML dotted key path: client.custom_headers Supported environment variables: PREFECT_CLIENT_CUSTOM_HEADERS

​

metrics

Type: ClientMetricsSettings TOML dotted key path: client.metrics

---

​

CloudSettings

Settings for interacting with Prefect Cloud

​

api_url

API URL for Prefect Cloud. Used for authentication with Prefect Cloud. Type: string Default: https://api.prefect.cloud/api TOML dotted key path: cloud.api_url Supported environment variables: PREFECT_CLOUD_API_URL

​

enable_orchestration_telemetry

Whether or not to enable orchestration telemetry. Type: boolean Default: True TOML dotted key path: cloud.enable_orchestration_telemetry Supported environment variables: PREFECT_CLOUD_ENABLE_ORCHESTRATION_TELEMETRY

​

ui_url

The URL of the Prefect Cloud UI. If not set, the client will attempt to infer it. Type: string | None Default: None TOML dotted key path: cloud.ui_url Supported environment variables: PREFECT_CLOUD_UI_URL

---

​

DeploymentsSettings

Settings for configuring deployments defaults

​

default_work_pool_name

The default work pool to use when creating deployments. Type: string | None Default: None TOML dotted key path: deployments.default_work_pool_name Supported environment variables: PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME, PREFECT_DEFAULT_WORK_POOL_NAME

​

default_docker_build_namespace

The default Docker namespace to use when building images. Type: string | None Default: None Examples:

• "my-dockerhub-registry"
• "4999999999999.dkr.ecr.us-east-2.amazonaws.com/my-ecr-repo"

TOML dotted key path: deployments.default_docker_build_namespace Supported environment variables: PREFECT_DEPLOYMENTS_DEFAULT_DOCKER_BUILD_NAMESPACE, PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE

---

​

ExperimentsSettings

Settings for configuring experimental features

​

warn

If True, warn on usage of experimental features. Type: boolean Default: True TOML dotted key path: experiments.warn Supported environment variables: PREFECT_EXPERIMENTS_WARN, PREFECT_EXPERIMENTAL_WARN

​

lineage_events_enabled

If True, enables emitting lineage events. Set to False to disable lineage event emission. Type: boolean Default: False TOML dotted key path: experiments.lineage_events_enabled Supported environment variables: PREFECT_EXPERIMENTS_LINEAGE_EVENTS_ENABLED

---

​

FlowsSettings

Settings for controlling flow behavior

​

default_retries

This value sets the default number of retries for all flows. Type: integer Default: 0 Constraints:

• Minimum: 0

TOML dotted key path: flows.default_retries Supported environment variables: PREFECT_FLOWS_DEFAULT_RETRIES, PREFECT_FLOW_DEFAULT_RETRIES

​

default_retry_delay_seconds

This value sets the default retry delay seconds for all flows. Type: integer | number | array Default: 0 TOML dotted key path: flows.default_retry_delay_seconds Supported environment variables: PREFECT_FLOWS_DEFAULT_RETRY_DELAY_SECONDS, PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS

---

​

InternalSettings

​

logging_level

The default logging level for Prefect’s internal machinery loggers. Type: string Default: ERROR Constraints:

• Allowed values: ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’

TOML dotted key path: internal.logging_level Supported environment variables: PREFECT_INTERNAL_LOGGING_LEVEL, PREFECT_LOGGING_INTERNAL_LEVEL

---

​

LoggingSettings

Settings for controlling logging behavior

​

level

The default logging level for Prefect loggers. Type: string Default: INFO Constraints:

• Allowed values: ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’

TOML dotted key path: logging.level Supported environment variables: PREFECT_LOGGING_LEVEL

​

config_path

A path to a logging configuration file. Defaults to $PREFECT_HOME/logging.yml Type: string TOML dotted key path: logging.config_path Supported environment variables: PREFECT_LOGGING_CONFIG_PATH, PREFECT_LOGGING_SETTINGS_PATH

​

extra_loggers

Additional loggers to attach to Prefect logging at runtime. Type: string | array | None Default: None TOML dotted key path: logging.extra_loggers Supported environment variables: PREFECT_LOGGING_EXTRA_LOGGERS

​

log_prints

If True, print statements in flows and tasks will be redirected to the Prefect logger for the given run. Type: boolean Default: False TOML dotted key path: logging.log_prints Supported environment variables: PREFECT_LOGGING_LOG_PRINTS

​

colors

If True, use colors in CLI output. If False, output will not include colors codes. Type: boolean Default: True TOML dotted key path: logging.colors Supported environment variables: PREFECT_LOGGING_COLORS

​

markup

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]. Type: boolean Default: False TOML dotted key path: logging.markup Supported environment variables: PREFECT_LOGGING_MARKUP

​

to_api

Type: LoggingToAPISettings TOML dotted key path: logging.to_api

---

​

LoggingToAPISettings

Settings for controlling logging to the API

​

enabled

If True, logs will be sent to the API. Type: boolean Default: True TOML dotted key path: logging.to_api.enabled Supported environment variables: PREFECT_LOGGING_TO_API_ENABLED

​

batch_interval

The number of seconds between batched writes of logs to the API. Type: number Default: 2.0 TOML dotted key path: logging.to_api.batch_interval Supported environment variables: PREFECT_LOGGING_TO_API_BATCH_INTERVAL

​

batch_size

The number of logs to batch before sending to the API. Type: integer Default: 4000000 TOML dotted key path: logging.to_api.batch_size Supported environment variables: PREFECT_LOGGING_TO_API_BATCH_SIZE

​

max_log_size

The maximum size in bytes for a single log. Type: integer Default: 1000000 TOML dotted key path: logging.to_api.max_log_size Supported environment variables: PREFECT_LOGGING_TO_API_MAX_LOG_SIZE

​

when_missing_flow

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.

Type: string Default: warn Constraints:

• Allowed values: ‘warn’, ‘error’, ‘ignore’

TOML dotted key path: logging.to_api.when_missing_flow Supported environment variables: PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW

---

​

ResultsSettings

Settings for controlling result storage behavior

​

default_serializer

The default serializer to use when not otherwise specified. Type: string Default: pickle TOML dotted key path: results.default_serializer Supported environment variables: PREFECT_RESULTS_DEFAULT_SERIALIZER

​

persist_by_default

The default setting for persisting results when not otherwise specified. Type: boolean Default: False TOML dotted key path: results.persist_by_default Supported environment variables: PREFECT_RESULTS_PERSIST_BY_DEFAULT

​

default_storage_block

The block-type/block-document slug of a block to use as the default result storage. Type: string | None Default: None TOML dotted key path: results.default_storage_block Supported environment variables: PREFECT_RESULTS_DEFAULT_STORAGE_BLOCK, PREFECT_DEFAULT_RESULT_STORAGE_BLOCK

​

local_storage_path

The default location for locally persisted results. Defaults to $PREFECT_HOME/storage. Type: string TOML dotted key path: results.local_storage_path Supported environment variables: PREFECT_RESULTS_LOCAL_STORAGE_PATH, PREFECT_LOCAL_STORAGE_PATH

---

​

RunnerServerSettings

Settings for controlling runner server behavior

​

enable

Whether or not to enable the runner’s webserver. Type: boolean Default: False TOML dotted key path: runner.server.enable Supported environment variables: PREFECT_RUNNER_SERVER_ENABLE

​

host

The host address the runner’s webserver should bind to. Type: string Default: localhost TOML dotted key path: runner.server.host Supported environment variables: PREFECT_RUNNER_SERVER_HOST

​

port

The port the runner’s webserver should bind to. Type: integer Default: 8080 TOML dotted key path: runner.server.port Supported environment variables: PREFECT_RUNNER_SERVER_PORT

​

log_level

The log level of the runner’s webserver. Type: string Default: ERROR Constraints:

• Allowed values: ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’

TOML dotted key path: runner.server.log_level Supported environment variables: PREFECT_RUNNER_SERVER_LOG_LEVEL

​

missed_polls_tolerance

Number of missed polls before a runner is considered unhealthy by its webserver. Type: integer Default: 2 TOML dotted key path: runner.server.missed_polls_tolerance Supported environment variables: PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE

---

​

RunnerSettings

Settings for controlling runner behavior

​

process_limit

Maximum number of processes a runner will execute in parallel. Type: integer Default: 5 TOML dotted key path: runner.process_limit Supported environment variables: PREFECT_RUNNER_PROCESS_LIMIT

​

poll_frequency

Number of seconds a runner should wait between queries for scheduled work. Type: integer Default: 10 TOML dotted key path: runner.poll_frequency Supported environment variables: PREFECT_RUNNER_POLL_FREQUENCY

​

heartbeat_frequency

Number of seconds a runner should wait between heartbeats for flow runs. Type: integer | None Default: None TOML dotted key path: runner.heartbeat_frequency Supported environment variables: PREFECT_RUNNER_HEARTBEAT_FREQUENCY

​

server

Type: RunnerServerSettings TOML dotted key path: runner.server

---

​

SQLAlchemyConnectArgsSettings

Settings for controlling SQLAlchemy connection behavior; note that these settings only take effect when using a PostgreSQL database.

​

application_name

Controls the application_name field for connections opened from the connection pool when using a PostgreSQL database with the Prefect backend. Type: string | None Default: None TOML dotted key path: server.database.sqlalchemy.connect_args.application_name Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_APPLICATION_NAME

​

statement_cache_size

Controls statement cache size for PostgreSQL connections. Setting this to 0 is required when using PgBouncer in transaction mode. Defaults to None. Type: integer | None Default: None TOML dotted key path: server.database.sqlalchemy.connect_args.statement_cache_size Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_STATEMENT_CACHE_SIZE

​

prepared_statement_cache_size

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. Type: integer | None Default: None TOML dotted key path: server.database.sqlalchemy.connect_args.prepared_statement_cache_size Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_PREPARED_STATEMENT_CACHE_SIZE

​

tls

Settings for controlling SQLAlchemy mTLS behavior Type: SQLAlchemyTLSSettings TOML dotted key path: server.database.sqlalchemy.connect_args.tls

---

​

SQLAlchemySettings

Settings for controlling SQLAlchemy behavior; note that these settings only take effect when using a PostgreSQL database.

​

connect_args

Settings for controlling SQLAlchemy connection behavior Type: SQLAlchemyConnectArgsSettings TOML dotted key path: server.database.sqlalchemy.connect_args

​

pool_size

Controls connection pool size of database connection pools from the Prefect backend. Type: integer Default: 5 TOML dotted key path: server.database.sqlalchemy.pool_size Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_SIZE, PREFECT_SQLALCHEMY_POOL_SIZE

​

pool_recycle

This setting causes the pool to recycle connections after the given number of seconds has passed; set it to -1 to avoid recycling entirely. Type: integer Default: 3600 TOML dotted key path: server.database.sqlalchemy.pool_recycle Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_RECYCLE

​

pool_timeout

Number of seconds to wait before giving up on getting a connection from the pool. Defaults to 30 seconds. Type: number | None Default: 30.0 TOML dotted key path: server.database.sqlalchemy.pool_timeout Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_TIMEOUT

​

max_overflow

Controls maximum overflow of the connection pool. To prevent overflow, set to -1. Type: integer Default: 10 TOML dotted key path: server.database.sqlalchemy.max_overflow Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_MAX_OVERFLOW, PREFECT_SQLALCHEMY_MAX_OVERFLOW

---

​

SQLAlchemyTLSSettings

Settings for controlling SQLAlchemy mTLS context when using a PostgreSQL database.

​

enabled

Controls whether connected to mTLS enabled PostgreSQL when using a PostgreSQL database with the Prefect backend. Type: boolean Default: False TOML dotted key path: server.database.sqlalchemy.connect_args.tls.enabled Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_ENABLED

​

ca_file

This configuration settings option specifies the path to PostgreSQL client certificate authority file. Type: string | None Default: None TOML dotted key path: server.database.sqlalchemy.connect_args.tls.ca_file Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_CA_FILE

​

cert_file

This configuration settings option specifies the path to PostgreSQL client certificate file. Type: string | None Default: None TOML dotted key path: server.database.sqlalchemy.connect_args.tls.cert_file Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_CERT_FILE

​

key_file

This configuration settings option specifies the path to PostgreSQL client key file. Type: string | None Default: None TOML dotted key path: server.database.sqlalchemy.connect_args.tls.key_file Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_KEY_FILE

​

check_hostname

This configuration settings option specifies whether to verify PostgreSQL server hostname. Type: boolean Default: True TOML dotted key path: server.database.sqlalchemy.connect_args.tls.check_hostname Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_CHECK_HOSTNAME

---

​

ServerAPISettings

Settings for controlling API server behavior

​

auth_string

A string to use for basic authentication with the API in the form ‘user:password’. Type: string | None Default: None TOML dotted key path: server.api.auth_string Supported environment variables: PREFECT_SERVER_API_AUTH_STRING

​

host

The API’s host address (defaults to 127.0.0.1). Type: string Default: 127.0.0.1 TOML dotted key path: server.api.host Supported environment variables: PREFECT_SERVER_API_HOST

​

port

The API’s port address (defaults to 4200). Type: integer Default: 4200 TOML dotted key path: server.api.port Supported environment variables: PREFECT_SERVER_API_PORT

​

base_path

The base URL path to serve the API under. Type: string | None Default: None Examples:

• "/v2/api"

TOML dotted key path: server.api.base_path Supported environment variables: PREFECT_SERVER_API_BASE_PATH

​

default_limit

The default limit applied to queries that can return multiple objects, such as POST /flow_runs/filter. Type: integer Default: 200 TOML dotted key path: server.api.default_limit Supported environment variables: PREFECT_SERVER_API_DEFAULT_LIMIT, PREFECT_API_DEFAULT_LIMIT

​

keepalive_timeout

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. Type: integer Default: 5 TOML dotted key path: server.api.keepalive_timeout Supported environment variables: PREFECT_SERVER_API_KEEPALIVE_TIMEOUT

​

csrf_protection_enabled

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. Type: boolean Default: False TOML dotted key path: server.api.csrf_protection_enabled Supported environment variables: PREFECT_SERVER_API_CSRF_PROTECTION_ENABLED, PREFECT_SERVER_CSRF_PROTECTION_ENABLED

​

csrf_token_expiration

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. Type: string Default: PT1H TOML dotted key path: server.api.csrf_token_expiration Supported environment variables: PREFECT_SERVER_API_CSRF_TOKEN_EXPIRATION, PREFECT_SERVER_CSRF_TOKEN_EXPIRATION

​

cors_allowed_origins

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. Type: string Default: * TOML dotted key path: server.api.cors_allowed_origins Supported environment variables: PREFECT_SERVER_API_CORS_ALLOWED_ORIGINS, PREFECT_SERVER_CORS_ALLOWED_ORIGINS

​

cors_allowed_methods

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. Type: string Default: * TOML dotted key path: server.api.cors_allowed_methods Supported environment variables: PREFECT_SERVER_API_CORS_ALLOWED_METHODS, PREFECT_SERVER_CORS_ALLOWED_METHODS

​

cors_allowed_headers

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. Type: string Default: * TOML dotted key path: server.api.cors_allowed_headers Supported environment variables: PREFECT_SERVER_API_CORS_ALLOWED_HEADERS, PREFECT_SERVER_CORS_ALLOWED_HEADERS

---

​

ServerConcurrencySettings

​

lease_storage

The module to use for storing concurrency limit leases. Type: string Default: prefect.server.concurrency.lease_storage.memory TOML dotted key path: server.concurrency.lease_storage Supported environment variables: PREFECT_SERVER_CONCURRENCY_LEASE_STORAGE

---

​

ServerDatabaseSettings

Settings for controlling server database behavior

​

sqlalchemy

Settings for controlling SQLAlchemy behavior Type: SQLAlchemySettings TOML dotted key path: server.database.sqlalchemy

​

connection_url

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. Type: string | None Default: None TOML dotted key path: server.database.connection_url Supported environment variables: PREFECT_SERVER_DATABASE_CONNECTION_URL, PREFECT_API_DATABASE_CONNECTION_URL

​

driver

The database driver to use when connecting to the database. If not set, the driver will be inferred from the connection URL. Type: string | None Default: None TOML dotted key path: server.database.driver Supported environment variables: PREFECT_SERVER_DATABASE_DRIVER, PREFECT_API_DATABASE_DRIVER

​

host

The database server host. Type: string | None Default: None TOML dotted key path: server.database.host Supported environment variables: PREFECT_SERVER_DATABASE_HOST, PREFECT_API_DATABASE_HOST

​

port

The database server port. Type: integer | None Default: None TOML dotted key path: server.database.port Supported environment variables: PREFECT_SERVER_DATABASE_PORT, PREFECT_API_DATABASE_PORT

​

user

The user to use when connecting to the database. Type: string | None Default: None TOML dotted key path: server.database.user Supported environment variables: PREFECT_SERVER_DATABASE_USER, PREFECT_API_DATABASE_USER

​

name

The name of the Prefect database on the remote server, or the path to the database file for SQLite. Type: string | None Default: None TOML dotted key path: server.database.name Supported environment variables: PREFECT_SERVER_DATABASE_NAME, PREFECT_API_DATABASE_NAME

​

password

The password to use when connecting to the database. Should be kept secret. Type: string | None Default: None TOML dotted key path: server.database.password Supported environment variables: PREFECT_SERVER_DATABASE_PASSWORD, PREFECT_API_DATABASE_PASSWORD

​

echo

If True, SQLAlchemy will log all SQL issued to the database. Defaults to False. Type: boolean Default: False TOML dotted key path: server.database.echo Supported environment variables: PREFECT_SERVER_DATABASE_ECHO, PREFECT_API_DATABASE_ECHO

​

migrate_on_start

If True, the database will be migrated on application startup. Type: boolean Default: True TOML dotted key path: server.database.migrate_on_start Supported environment variables: PREFECT_SERVER_DATABASE_MIGRATE_ON_START, PREFECT_API_DATABASE_MIGRATE_ON_START

​

timeout

A statement timeout, in seconds, applied to all database interactions made by the Prefect backend. Defaults to 10 seconds. Type: number | None Default: 10.0 TOML dotted key path: server.database.timeout Supported environment variables: PREFECT_SERVER_DATABASE_TIMEOUT, PREFECT_API_DATABASE_TIMEOUT

​

connection_timeout

A connection timeout, in seconds, applied to database connections. Defaults to 5. Type: number | None Default: 5.0 TOML dotted key path: server.database.connection_timeout Supported environment variables: PREFECT_SERVER_DATABASE_CONNECTION_TIMEOUT, PREFECT_API_DATABASE_CONNECTION_TIMEOUT

---

​

ServerDeploymentsSettings

​

concurrency_slot_wait_seconds

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

• Minimum: 0.0

TOML dotted key path: server.deployments.concurrency_slot_wait_seconds Supported environment variables: PREFECT_SERVER_DEPLOYMENTS_CONCURRENCY_SLOT_WAIT_SECONDS, PREFECT_DEPLOYMENT_CONCURRENCY_SLOT_WAIT_SECONDS

---

​

ServerEphemeralSettings

Settings for controlling ephemeral server behavior

​

enabled

Controls whether or not a subprocess server can be started when no API URL is provided. Type: boolean Default: False TOML dotted key path: server.ephemeral.enabled Supported environment variables: PREFECT_SERVER_EPHEMERAL_ENABLED, PREFECT_SERVER_ALLOW_EPHEMERAL_MODE

​

startup_timeout_seconds

The number of seconds to wait for the server to start when ephemeral mode is enabled. Defaults to 20. Type: integer Default: 20 TOML dotted key path: server.ephemeral.startup_timeout_seconds Supported environment variables: PREFECT_SERVER_EPHEMERAL_STARTUP_TIMEOUT_SECONDS

---

​

ServerEventsSettings

Settings for controlling behavior of the events subsystem

​

stream_out_enabled

Whether or not to stream events out to the API via websockets. Type: boolean Default: True TOML dotted key path: server.events.stream_out_enabled Supported environment variables: PREFECT_SERVER_EVENTS_STREAM_OUT_ENABLED, PREFECT_API_EVENTS_STREAM_OUT_ENABLED

​

related_resource_cache_ttl

The number of seconds to cache related resources for in the API. Type: string Default: PT5M TOML dotted key path: server.events.related_resource_cache_ttl Supported environment variables: PREFECT_SERVER_EVENTS_RELATED_RESOURCE_CACHE_TTL, PREFECT_API_EVENTS_RELATED_RESOURCE_CACHE_TTL

​

maximum_labels_per_resource

The maximum number of labels a resource may have. Type: integer Default: 500 TOML dotted key path: server.events.maximum_labels_per_resource Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_LABELS_PER_RESOURCE, PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE

​

maximum_related_resources

The maximum number of related resources an Event may have. Type: integer Default: 100 TOML dotted key path: server.events.maximum_related_resources Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_RELATED_RESOURCES, PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES

​

maximum_size_bytes

The maximum size of an Event when serialized to JSON Type: integer Default: 1500000 TOML dotted key path: server.events.maximum_size_bytes Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_SIZE_BYTES, PREFECT_EVENTS_MAXIMUM_SIZE_BYTES

​

expired_bucket_buffer

The amount of time to retain expired automation buckets Type: string Default: PT1M TOML dotted key path: server.events.expired_bucket_buffer Supported environment variables: PREFECT_SERVER_EVENTS_EXPIRED_BUCKET_BUFFER, PREFECT_EVENTS_EXPIRED_BUCKET_BUFFER

​

proactive_granularity

How frequently proactive automations are evaluated Type: string Default: PT5S TOML dotted key path: server.events.proactive_granularity Supported environment variables: PREFECT_SERVER_EVENTS_PROACTIVE_GRANULARITY, PREFECT_EVENTS_PROACTIVE_GRANULARITY

​

retention_period

The amount of time to retain events in the database. Type: string Default: P7D TOML dotted key path: server.events.retention_period Supported environment variables: PREFECT_SERVER_EVENTS_RETENTION_PERIOD, PREFECT_EVENTS_RETENTION_PERIOD

​

maximum_websocket_backfill

The maximum range to look back for backfilling events for a websocket subscriber. Type: string Default: PT15M TOML dotted key path: server.events.maximum_websocket_backfill Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_WEBSOCKET_BACKFILL, PREFECT_EVENTS_MAXIMUM_WEBSOCKET_BACKFILL

​

websocket_backfill_page_size

The page size for the queries to backfill events for websocket subscribers. Type: integer Default: 250 TOML dotted key path: server.events.websocket_backfill_page_size Supported environment variables: PREFECT_SERVER_EVENTS_WEBSOCKET_BACKFILL_PAGE_SIZE, PREFECT_EVENTS_WEBSOCKET_BACKFILL_PAGE_SIZE

​

messaging_broker

Which message broker implementation to use for the messaging system, should point to a module that exports a Publisher and Consumer class. Type: string Default: prefect.server.utilities.messaging.memory TOML dotted key path: server.events.messaging_broker Supported environment variables: PREFECT_SERVER_EVENTS_MESSAGING_BROKER, PREFECT_MESSAGING_BROKER

​

messaging_cache

Which cache implementation to use for the events system. Should point to a module that exports a Cache class. Type: string Default: prefect.server.utilities.messaging.memory TOML dotted key path: server.events.messaging_cache Supported environment variables: PREFECT_SERVER_EVENTS_MESSAGING_CACHE, PREFECT_MESSAGING_CACHE

​

maximum_event_name_length

The maximum length of an event name. Type: integer Default: 1024 TOML dotted key path: server.events.maximum_event_name_length Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_EVENT_NAME_LENGTH

---

​

ServerFlowRunGraphSettings

Settings for controlling behavior of the flow run graph

​

max_nodes

The maximum size of a flow run graph on the v2 API Type: integer Default: 10000 TOML dotted key path: server.flow_run_graph.max_nodes Supported environment variables: PREFECT_SERVER_FLOW_RUN_GRAPH_MAX_NODES, PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES

​

max_artifacts

The maximum number of artifacts to show on a flow run graph on the v2 API Type: integer Default: 10000 TOML dotted key path: server.flow_run_graph.max_artifacts Supported environment variables: PREFECT_SERVER_FLOW_RUN_GRAPH_MAX_ARTIFACTS, PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS

---

​

ServerLogsSettings

Settings for controlling behavior of the logs subsystem

​

stream_out_enabled

Whether or not to stream logs out to the API via websockets. Type: boolean Default: False TOML dotted key path: server.logs.stream_out_enabled Supported environment variables: PREFECT_SERVER_LOGS_STREAM_OUT_ENABLED

​

stream_publishing_enabled

Whether or not to publish logs to the streaming system. Type: boolean Default: False TOML dotted key path: server.logs.stream_publishing_enabled Supported environment variables: PREFECT_SERVER_LOGS_STREAM_PUBLISHING_ENABLED

---

​

ServerServicesCancellationCleanupSettings

Settings for controlling the cancellation cleanup service

​

enabled

Whether or not to start the cancellation cleanup service in the server application. Type: boolean Default: True TOML dotted key path: server.services.cancellation_cleanup.enabled Supported environment variables: PREFECT_SERVER_SERVICES_CANCELLATION_CLEANUP_ENABLED, PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED

​

loop_seconds

The cancellation cleanup service will look for non-terminal tasks and subflows this often. Defaults to 20. Type: number Default: 20 TOML dotted key path: server.services.cancellation_cleanup.loop_seconds Supported environment variables: PREFECT_SERVER_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS, PREFECT_API_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS

---

​

ServerServicesEventLoggerSettings

Settings for controlling the event logger service

​

enabled

Whether or not to start the event logger service in the server application. Type: boolean Default: False TOML dotted key path: server.services.event_logger.enabled Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_LOGGER_ENABLED, PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED

---

​

ServerServicesEventPersisterSettings

Settings for controlling the event persister service

​

enabled

Whether or not to start the event persister service in the server application. Type: boolean Default: True TOML dotted key path: server.services.event_persister.enabled Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_ENABLED, PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED

​

batch_size

The number of events the event persister will attempt to insert in one batch. Type: integer Default: 20 TOML dotted key path: server.services.event_persister.batch_size Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_BATCH_SIZE, PREFECT_API_SERVICES_EVENT_PERSISTER_BATCH_SIZE

​

flush_interval

The maximum number of seconds between flushes of the event persister. Type: number Default: 5 TOML dotted key path: server.services.event_persister.flush_interval Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL, PREFECT_API_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL

​

batch_size_delete

The number of expired events and event resources the event persister will attempt to delete in one batch. Type: integer Default: 10000 TOML dotted key path: server.services.event_persister.batch_size_delete Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_BATCH_SIZE_DELETE

---

​

ServerServicesForemanSettings

Settings for controlling the foreman service

​

enabled

Whether or not to start the foreman service in the server application. Type: boolean Default: True TOML dotted key path: server.services.foreman.enabled Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_ENABLED, PREFECT_API_SERVICES_FOREMAN_ENABLED

​

loop_seconds

The foreman service will check for offline workers this often. Defaults to 15. Type: number Default: 15 TOML dotted key path: server.services.foreman.loop_seconds Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_LOOP_SECONDS, PREFECT_API_SERVICES_FOREMAN_LOOP_SECONDS

​

inactivity_heartbeat_multiple

The number of heartbeats that must be missed before a worker is marked as offline. Defaults to 3. Type: integer Default: 3 TOML dotted key path: server.services.foreman.inactivity_heartbeat_multiple Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE, PREFECT_API_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE

​

fallback_heartbeat_interval_seconds

The number of seconds to use for online/offline evaluation if a worker’s heartbeat interval is not set. Defaults to 30. Type: integer Default: 30 TOML dotted key path: server.services.foreman.fallback_heartbeat_interval_seconds Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS, PREFECT_API_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS

​

deployment_last_polled_timeout_seconds

The number of seconds before a deployment is marked as not ready if it has not been polled. Defaults to 60. Type: integer Default: 60 TOML dotted key path: server.services.foreman.deployment_last_polled_timeout_seconds Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS, PREFECT_API_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS

​

work_queue_last_polled_timeout_seconds

The number of seconds before a work queue is marked as not ready if it has not been polled. Defaults to 60. Type: integer Default: 60 TOML dotted key path: server.services.foreman.work_queue_last_polled_timeout_seconds Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS, PREFECT_API_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS

---

​

ServerServicesLateRunsSettings

Settings for controlling the late runs service

​

enabled

Whether or not to start the late runs service in the server application. Type: boolean Default: True TOML dotted key path: server.services.late_runs.enabled Supported environment variables: PREFECT_SERVER_SERVICES_LATE_RUNS_ENABLED, PREFECT_API_SERVICES_LATE_RUNS_ENABLED

​

loop_seconds

The late runs service will look for runs to mark as late this often. Defaults to 5. Type: number Default: 5 TOML dotted key path: server.services.late_runs.loop_seconds Supported environment variables: PREFECT_SERVER_SERVICES_LATE_RUNS_LOOP_SECONDS, PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS

​

after_seconds

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. Type: string Default: PT15S TOML dotted key path: server.services.late_runs.after_seconds Supported environment variables: PREFECT_SERVER_SERVICES_LATE_RUNS_AFTER_SECONDS, PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS

---

​

ServerServicesPauseExpirationsSettings

Settings for controlling the pause expiration service

​

enabled

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. Type: boolean Default: True TOML dotted key path: server.services.pause_expirations.enabled Supported environment variables: PREFECT_SERVER_SERVICES_PAUSE_EXPIRATIONS_ENABLED, PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED

​

loop_seconds

The pause expiration service will look for runs to mark as failed this often. Defaults to 5. Type: number Default: 5 TOML dotted key path: server.services.pause_expirations.loop_seconds Supported environment variables: PREFECT_SERVER_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS, PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS

---

​

ServerServicesRepossessorSettings

Settings for controlling the repossessor service

​

enabled

Whether or not to start the repossessor service in the server application. Type: boolean Default: True TOML dotted key path: server.services.repossessor.enabled Supported environment variables: PREFECT_SERVER_SERVICES_REPOSSESSOR_ENABLED

​

loop_seconds

The repossessor service will look for expired leases this often. Defaults to 15. Type: number Default: 15 TOML dotted key path: server.services.repossessor.loop_seconds Supported environment variables: PREFECT_SERVER_SERVICES_REPOSSESSOR_LOOP_SECONDS

---

​

ServerServicesSchedulerSettings

Settings for controlling the scheduler service

​

enabled

Whether or not to start the scheduler service in the server application. Type: boolean Default: True TOML dotted key path: server.services.scheduler.enabled Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_ENABLED, PREFECT_API_SERVICES_SCHEDULER_ENABLED

​

loop_seconds

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. Type: number Default: 60 TOML dotted key path: server.services.scheduler.loop_seconds Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_LOOP_SECONDS, PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS

​

deployment_batch_size

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. Type: integer Default: 100 TOML dotted key path: server.services.scheduler.deployment_batch_size Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE, PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE

​

max_runs

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. Type: integer Default: 100 TOML dotted key path: server.services.scheduler.max_runs Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MAX_RUNS, PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS

​

min_runs

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. Type: integer Default: 3 TOML dotted key path: server.services.scheduler.min_runs Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MIN_RUNS, PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS

​

max_scheduled_time

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). Type: string Default: P100D TOML dotted key path: server.services.scheduler.max_scheduled_time Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME, PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME

​

min_scheduled_time

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 Type: string Default: PT1H TOML dotted key path: server.services.scheduler.min_scheduled_time Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME, PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME

​

insert_batch_size

The number of runs the scheduler will attempt to insert in a single batch. Defaults to 500. Type: integer Default: 500 TOML dotted key path: server.services.scheduler.insert_batch_size Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_INSERT_BATCH_SIZE, PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE

​

recent_deployments_loop_seconds

The number of seconds the recent deployments scheduler will wait between checking for recently updated deployments. Defaults to 5. Type: number Default: 5 TOML dotted key path: server.services.scheduler.recent_deployments_loop_seconds Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_RECENT_DEPLOYMENTS_LOOP_SECONDS

---

​

ServerServicesSettings

Settings for controlling server services

​

cancellation_cleanup

Type: ServerServicesCancellationCleanupSettings TOML dotted key path: server.services.cancellation_cleanup

​

event_persister

Type: ServerServicesEventPersisterSettings TOML dotted key path: server.services.event_persister

​

event_logger

Type: ServerServicesEventLoggerSettings TOML dotted key path: server.services.event_logger

​

foreman

Type: ServerServicesForemanSettings TOML dotted key path: server.services.foreman

​

late_runs

Type: ServerServicesLateRunsSettings TOML dotted key path: server.services.late_runs

​

scheduler

Type: ServerServicesSchedulerSettings TOML dotted key path: server.services.scheduler

​

pause_expirations

Type: ServerServicesPauseExpirationsSettings TOML dotted key path: server.services.pause_expirations

​

repossessor

Type: ServerServicesRepossessorSettings TOML dotted key path: server.services.repossessor

​

task_run_recorder

Type: ServerServicesTaskRunRecorderSettings TOML dotted key path: server.services.task_run_recorder

​

triggers

Type: ServerServicesTriggersSettings TOML dotted key path: server.services.triggers

---

​

ServerServicesTaskRunRecorderSettings

Settings for controlling the task run recorder service

​

enabled

Whether or not to start the task run recorder service in the server application. Type: boolean Default: True TOML dotted key path: server.services.task_run_recorder.enabled Supported environment variables: PREFECT_SERVER_SERVICES_TASK_RUN_RECORDER_ENABLED, PREFECT_API_SERVICES_TASK_RUN_RECORDER_ENABLED

---

​

ServerServicesTriggersSettings

Settings for controlling the triggers service

​

enabled

Whether or not to start the triggers service in the server application. Type: boolean Default: True TOML dotted key path: server.services.triggers.enabled Supported environment variables: PREFECT_SERVER_SERVICES_TRIGGERS_ENABLED, PREFECT_API_SERVICES_TRIGGERS_ENABLED

​

pg_notify_reconnect_interval_seconds

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. Type: integer Default: 10 TOML dotted key path: server.services.triggers.pg_notify_reconnect_interval_seconds Supported environment variables: PREFECT_SERVER_SERVICES_TRIGGERS_PG_NOTIFY_RECONNECT_INTERVAL_SECONDS

​

pg_notify_heartbeat_interval_seconds

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. Type: integer Default: 5 TOML dotted key path: server.services.triggers.pg_notify_heartbeat_interval_seconds Supported environment variables: PREFECT_SERVER_SERVICES_TRIGGERS_PG_NOTIFY_HEARTBEAT_INTERVAL_SECONDS

---

​

ServerSettings

Settings for controlling server behavior

​

logging_level

The default logging level for the Prefect API server. Type: string Default: WARNING Constraints:

• Allowed values: ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’

TOML dotted key path: server.logging_level Supported environment variables: PREFECT_SERVER_LOGGING_LEVEL, PREFECT_LOGGING_SERVER_LEVEL

​

analytics_enabled

When enabled, Prefect sends anonymous data (e.g. count of flow runs, package version) on server startup to help us improve our product. Type: boolean Default: True TOML dotted key path: server.analytics_enabled Supported environment variables: PREFECT_SERVER_ANALYTICS_ENABLED

​

metrics_enabled

Whether or not to enable Prometheus metrics in the API. Type: boolean Default: False TOML dotted key path: server.metrics_enabled Supported environment variables: PREFECT_SERVER_METRICS_ENABLED, PREFECT_API_ENABLE_METRICS

​

log_retryable_errors

If True, log retryable errors in the API and it’s services. Type: boolean Default: False TOML dotted key path: server.log_retryable_errors Supported environment variables: PREFECT_SERVER_LOG_RETRYABLE_ERRORS, PREFECT_API_LOG_RETRYABLE_ERRORS

​

register_blocks_on_start

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. Type: boolean Default: True TOML dotted key path: server.register_blocks_on_start Supported environment variables: PREFECT_SERVER_REGISTER_BLOCKS_ON_START, PREFECT_API_BLOCKS_REGISTER_ON_START

​

memoize_block_auto_registration

Controls whether or not block auto-registration on start Type: boolean Default: True TOML dotted key path: server.memoize_block_auto_registration Supported environment variables: PREFECT_SERVER_MEMOIZE_BLOCK_AUTO_REGISTRATION, PREFECT_MEMOIZE_BLOCK_AUTO_REGISTRATION

​

memo_store_path

Path to the memo store file. Defaults to $PREFECT_HOME/memo_store.toml Type: string TOML dotted key path: server.memo_store_path Supported environment variables: PREFECT_SERVER_MEMO_STORE_PATH, PREFECT_MEMO_STORE_PATH

​

deployment_schedule_max_scheduled_runs

The maximum number of scheduled runs to create for a deployment. Type: integer Default: 50 TOML dotted key path: server.deployment_schedule_max_scheduled_runs Supported environment variables: PREFECT_SERVER_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS, PREFECT_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS

​

api

Type: ServerAPISettings TOML dotted key path: server.api

​

concurrency

Settings for controlling server-side concurrency limit handling Type: ServerConcurrencySettings TOML dotted key path: server.concurrency

​

database

Type: ServerDatabaseSettings TOML dotted key path: server.database

​

deployments

Settings for controlling server deployments behavior Type: ServerDeploymentsSettings TOML dotted key path: server.deployments

​

ephemeral

Type: ServerEphemeralSettings TOML dotted key path: server.ephemeral

​

events

Settings for controlling server events behavior Type: ServerEventsSettings TOML dotted key path: server.events

​

flow_run_graph

Settings for controlling flow run graph behavior Type: ServerFlowRunGraphSettings TOML dotted key path: server.flow_run_graph

​

logs

Settings for controlling server logs behavior Type: ServerLogsSettings TOML dotted key path: server.logs

​

services

Settings for controlling server services behavior Type: ServerServicesSettings TOML dotted key path: server.services

​

tasks

Settings for controlling server tasks behavior Type: ServerTasksSettings TOML dotted key path: server.tasks

​

ui

Settings for controlling server UI behavior Type: ServerUISettings TOML dotted key path: server.ui

---

​

ServerTasksSchedulingSettings

Settings for controlling server-side behavior related to task scheduling

​

max_scheduled_queue_size

The maximum number of scheduled tasks to queue for submission. Type: integer Default: 1000 TOML dotted key path: server.tasks.scheduling.max_scheduled_queue_size Supported environment variables: PREFECT_SERVER_TASKS_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE, PREFECT_TASK_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE

​

max_retry_queue_size

The maximum number of retries to queue for submission. Type: integer Default: 100 TOML dotted key path: server.tasks.scheduling.max_retry_queue_size Supported environment variables: PREFECT_SERVER_TASKS_SCHEDULING_MAX_RETRY_QUEUE_SIZE, PREFECT_TASK_SCHEDULING_MAX_RETRY_QUEUE_SIZE

​

pending_task_timeout

How long before a PENDING task are made available to another task worker. Type: string Default: PT0S TOML dotted key path: server.tasks.scheduling.pending_task_timeout Supported environment variables: PREFECT_SERVER_TASKS_SCHEDULING_PENDING_TASK_TIMEOUT, PREFECT_TASK_SCHEDULING_PENDING_TASK_TIMEOUT

---

​

ServerTasksSettings

Settings for controlling server-side behavior related to tasks

​

tag_concurrency_slot_wait_seconds

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

• Minimum: 0

TOML dotted key path: server.tasks.tag_concurrency_slot_wait_seconds Supported environment variables: PREFECT_SERVER_TASKS_TAG_CONCURRENCY_SLOT_WAIT_SECONDS, PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS

​

max_cache_key_length

The maximum number of characters allowed for a task run cache key. Type: integer Default: 2000 TOML dotted key path: server.tasks.max_cache_key_length Supported environment variables: PREFECT_SERVER_TASKS_MAX_CACHE_KEY_LENGTH, PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH

​

scheduling

Type: ServerTasksSchedulingSettings TOML dotted key path: server.tasks.scheduling

---

​

ServerUISettings

​

enabled

Whether or not to serve the Prefect UI. Type: boolean Default: True TOML dotted key path: server.ui.enabled Supported environment variables: PREFECT_SERVER_UI_ENABLED, PREFECT_UI_ENABLED

​

api_url

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. Type: string | None Default: None TOML dotted key path: server.ui.api_url Supported environment variables: PREFECT_SERVER_UI_API_URL, PREFECT_UI_API_URL

​

serve_base

The base URL path to serve the Prefect UI from. Type: string Default: / TOML dotted key path: server.ui.serve_base Supported environment variables: PREFECT_SERVER_UI_SERVE_BASE, PREFECT_UI_SERVE_BASE

​

static_directory

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). Type: string | None Default: None TOML dotted key path: server.ui.static_directory Supported environment variables: PREFECT_SERVER_UI_STATIC_DIRECTORY, PREFECT_UI_STATIC_DIRECTORY

---

​

TasksRunnerSettings

​

thread_pool_max_workers

The maximum number of workers for ThreadPoolTaskRunner. Type: integer | None Default: None TOML dotted key path: tasks.runner.thread_pool_max_workers Supported environment variables: PREFECT_TASKS_RUNNER_THREAD_POOL_MAX_WORKERS, PREFECT_TASK_RUNNER_THREAD_POOL_MAX_WORKERS

---

​

TasksSchedulingSettings

​

default_storage_block

The block-type/block-document slug of a block to use as the default storage for autonomous tasks. Type: string | None Default: None TOML dotted key path: tasks.scheduling.default_storage_block Supported environment variables: PREFECT_TASKS_SCHEDULING_DEFAULT_STORAGE_BLOCK, PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK

​

delete_failed_submissions

Whether or not to delete failed task submissions from the database. Type: boolean Default: True TOML dotted key path: tasks.scheduling.delete_failed_submissions Supported environment variables: PREFECT_TASKS_SCHEDULING_DELETE_FAILED_SUBMISSIONS, PREFECT_TASK_SCHEDULING_DELETE_FAILED_SUBMISSIONS

---

​

TasksSettings

​

refresh_cache

If True, enables a refresh of cached results: re-executing the task will refresh the cached results. Type: boolean Default: False TOML dotted key path: tasks.refresh_cache Supported environment variables: PREFECT_TASKS_REFRESH_CACHE

​

default_no_cache

If True, sets the default cache policy on all tasks to NO_CACHE. Type: boolean Default: False TOML dotted key path: tasks.default_no_cache Supported environment variables: PREFECT_TASKS_DEFAULT_NO_CACHE

​

disable_caching

If True, disables caching on all tasks regardless of cache policy. Type: boolean Default: False TOML dotted key path: tasks.disable_caching Supported environment variables: PREFECT_TASKS_DISABLE_CACHING

​

default_retries

This value sets the default number of retries for all tasks. Type: integer Default: 0 Constraints:

• Minimum: 0

TOML dotted key path: tasks.default_retries Supported environment variables: PREFECT_TASKS_DEFAULT_RETRIES, PREFECT_TASK_DEFAULT_RETRIES

​

default_retry_delay_seconds

This value sets the default retry delay seconds for all tasks. Type: string | integer | number | array | None Default: 0 TOML dotted key path: tasks.default_retry_delay_seconds Supported environment variables: PREFECT_TASKS_DEFAULT_RETRY_DELAY_SECONDS, PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS

​

default_persist_result

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. Type: boolean | None Default: None TOML dotted key path: tasks.default_persist_result Supported environment variables: PREFECT_TASKS_DEFAULT_PERSIST_RESULT

​

runner

Settings for controlling task runner behavior Type: TasksRunnerSettings TOML dotted key path: tasks.runner

​

scheduling

Settings for controlling client-side task scheduling behavior Type: TasksSchedulingSettings TOML dotted key path: tasks.scheduling

---

​

TestingSettings

​

test_mode

If True, places the API in test mode. This may modify behavior to facilitate testing. Type: boolean Default: False TOML dotted key path: testing.test_mode Supported environment variables: PREFECT_TESTING_TEST_MODE, PREFECT_TEST_MODE

​

unit_test_mode

This setting only exists to facilitate unit testing. If True, code is executing in a unit test context. Defaults to False. Type: boolean Default: False TOML dotted key path: testing.unit_test_mode Supported environment variables: PREFECT_TESTING_UNIT_TEST_MODE, PREFECT_UNIT_TEST_MODE

​

unit_test_loop_debug

If True turns on debug mode for the unit testing event loop. Type: boolean Default: True TOML dotted key path: testing.unit_test_loop_debug Supported environment variables: PREFECT_TESTING_UNIT_TEST_LOOP_DEBUG, PREFECT_UNIT_TEST_LOOP_DEBUG

​

test_setting

This setting only exists to facilitate unit testing. If in test mode, this setting will return its value. Otherwise, it returns None. Type: None Default: FOO TOML dotted key path: testing.test_setting Supported environment variables: PREFECT_TESTING_TEST_SETTING, PREFECT_TEST_SETTING

---

​

WorkerSettings

​

heartbeat_seconds

Number of seconds a worker should wait between sending a heartbeat. Type: number Default: 30 TOML dotted key path: worker.heartbeat_seconds Supported environment variables: PREFECT_WORKER_HEARTBEAT_SECONDS

​

query_seconds

Number of seconds a worker should wait between queries for scheduled work. Type: number Default: 10 TOML dotted key path: worker.query_seconds Supported environment variables: PREFECT_WORKER_QUERY_SECONDS

​

prefetch_seconds

The number of seconds into the future a worker should query for scheduled work. Type: number Default: 10 TOML dotted key path: worker.prefetch_seconds Supported environment variables: PREFECT_WORKER_PREFETCH_SECONDS

​

webserver

Settings for a worker’s webserver Type: WorkerWebserverSettings TOML dotted key path: worker.webserver

---

​

WorkerWebserverSettings

​

host

The host address the worker’s webserver should bind to. Type: string Default: 0.0.0.0 TOML dotted key path: worker.webserver.host Supported environment variables: PREFECT_WORKER_WEBSERVER_HOST

​

port

The port the worker’s webserver should bind to. Type: integer Default: 8080 TOML dotted key path: worker.webserver.port Supported environment variables: PREFECT_WORKER_WEBSERVER_PORT

---