Trigger ad-hoc deployment runs

prefect deployment run my-flow/my-deployment

# Pass parameters
prefect deployment run my-flow/my-deployment \
  --param my_param=42 \
  --param another_param="hello"

# Schedule for later
prefect deployment run my-flow/my-deployment --start-in "2 hours"

# Watch the run until completion
prefect deployment run my-flow/my-deployment --watch

# Watch an existing flow run by its ID
prefect flow-run watch <flow-run-id>

# Set custom run name
Use `--flow-run-name` to set a static or templated name for the flow run.

prefect deployment run my-flow/my-deployment --flow-run-name "custom-run-name"

# Set a custom flow run name using templating
prefect deployment run my-flow/my-deployment \
  --param customer_id=1234 \
  --param run_date="2025-07-14" \
  --flow-run-name "customer-{customer_id}-run-{run_date}"

> Note: You can use `{parameter}` syntax to template the flow run name.
> The values will be substituted from the `--param` values.

# Add tags to the run
prefect deployment run my-flow/my-deployment --tag production --tag critical

from prefect.deployments import run_deployment

# Basic usage
flow_run = run_deployment(
    name="my-flow/my-deployment"
)

# With parameters
flow_run = run_deployment(
    name="my-flow/my-deployment",
    parameters={
        "my_param": 42,
        "another_param": "hello"
    }
)

# With job variables (environment variables, etc.)
flow_run = run_deployment(
    name="my-flow/my-deployment",
    parameters={"my_param": 42},
    job_variables={"env": {"MY_ENV_VAR": "production"}}
)

# Don't wait for completion
flow_run = run_deployment(
    name="my-flow/my-deployment",
    timeout=0  # returns immediately
)

# Wait with custom timeout (seconds)
flow_run = run_deployment(
    name="my-flow/my-deployment",
    timeout=300  # wait up to 5 minutes
)

# Schedule for later
from datetime import datetime, timedelta

flow_run = run_deployment(
    name="my-flow/my-deployment",
    scheduled_time=datetime.now() + timedelta(hours=2)
)

# With custom tags
flow_run = run_deployment(
    name="my-flow/my-deployment",
    tags=["production", "critical"]
)

import asyncio
from prefect.deployments import run_deployment

async def trigger_deployment():
    flow_run = await run_deployment(
        name="my-flow/my-deployment",
        parameters={"my_param": 42}
    )
    return flow_run

# Run it
flow_run = asyncio.run(trigger_deployment())