Set Up the Kestra Python SDK and Execute Workflows
For the complete documentation index, see llms.txt. For a full content snapshot, see llms-full.txt. Append.mdto anykestra.io/docs/*URL for plain Markdown.
Use the Kestra Python SDK (kestrapy) to interact with the Kestra API from Python applications.
Install the Python SDK
Before starting, make sure your Kestra instance is running. Store credentials in an .env file:
bashKESTRA_HOST=http://localhost:8080
KESTRA_USERNAME=root@root.com
KESTRA_PASSWORD=Root!1234Create a virtual environment and install the Kestra Python SDK.
shelluv venv
source .venv/bin/activate
uv pip install kestrapy
uv pip install python-dotenv # optional: loads .env automaticallyConfigure the client
Import and initialize the client with your Kestra credentials. Construct KestraClient once and reuse it throughout your application.
pythonfrom kestrapy import Configuration, KestraClient
configuration = Configuration(
host="http://localhost:8080",
username="root@root.com",
password="Root!1234"
)
kestra_client = KestraClient(configuration)Use environment variables rather than hardcoding credentials. You can also use token-based authentication by setting access_token on the Configuration object instead of username/password.
Create a flow
Pass the flow definition as a YAML string to create_flow.
pythondef create_flow():
tenant = "main"
body = """
id: my_flow
namespace: my_namespace
tasks:
- id: hello
type: io.kestra.plugin.core.log.Log
message: "Hello World!"
"""
created = kestra_client.flows.create_flow(tenant=tenant, body=body)
print(f"Flow created: {created.id}")body must be valid YAML. If a flow with the same id, namespace, and tenant already exists, use update_flow instead.
Update a flow
Send the full YAML — including the same id and namespace — to replace an existing flow.
pythondef update_flow():
tenant = "main"
body = """
id: my_flow
namespace: my_namespace
tasks:
- id: hello
type: io.kestra.plugin.core.log.Log
message: "Updated message!"
"""
updated = kestra_client.flows.update_flow(
id="my_flow",
namespace="my_namespace",
tenant=tenant,
body=body
)
print(f"Flow updated: {updated.id}")Delete a flow
Remove a flow by its namespace, id, and tenant.
pythondef delete_flow():
tenant = "main"
kestra_client.flows.delete_flow(
namespace="my_namespace",
id="my_flow",
tenant=tenant
)
print("Flow deleted")Deleting a flow removes its definition. Execution history is retained unless you delete executions separately.
Execute a flow
Trigger an execution using create_execution.
The first three positional arguments are namespace, id (the flow ID), and wait.
pythondef create_execution():
tenant = "main"
execution = kestra_client.executions.create_execution(
namespace="my_namespace",
id="my_flow",
wait=True,
tenant=tenant
)
print(f"Execution started: {execution.id}")To pass inputs, use additional_form_datas with a dictionary keyed by input ID:
pythondef create_execution_with_inputs():
tenant = "main"
execution = kestra_client.executions.create_execution(
namespace="my_namespace",
id="my_flow",
wait=True,
tenant=tenant,
additional_form_datas={"input_id": "value"}
)
print(f"Execution started: {execution.id}")wait=True blocks until the execution completes. Use wait=False for non-blocking calls. The additional_form_datas keys must match the flow's defined input IDs.
Follow an execution
Stream live execution updates using follow_execution.
pythondef follow_execution():
tenant = "main"
execution = kestra_client.executions.create_execution(
namespace="my_namespace",
id="my_flow",
wait=False,
tenant=tenant
)
for event in kestra_client.executions.follow_execution(
execution_id=execution.id,
tenant=tenant
):
if event.state is None:
continue # keepalive frame
print(event.state.current)The first SSE payload is an empty keepalive — skip it before processing subsequent events. Use follow_execution for CI/CD pipelines or real-time dashboards.
KV Store
The KV Store lets you read and write key-value pairs scoped to a namespace.
List keys
Use list_all_keys to get a paged list of keys across the tenant:
pythondef list_kv_keys():
tenant = "main"
result = kestra_client.kv.list_all_keys(
page=1,
size=50,
tenant=tenant
)
for entry in result.results:
print(f"Key: {entry.key}")Get a value
pythondef get_kv_value():
tenant = "main"
result = kestra_client.kv.key_value(
namespace="my_namespace",
key="my_key",
tenant=tenant
)
print(f"Value: {result.value}")Set a value
pythondef set_kv_value():
tenant = "main"
kestra_client.kv.set_key_value(
namespace="my_namespace",
key="my_key",
tenant=tenant,
body="my_value"
)
print("Key set")Delete a key
pythondef delete_kv_key():
tenant = "main"
kestra_client.kv.delete_key_value(
namespace="my_namespace",
key="my_key",
tenant=tenant
)
print("Key deleted")Manage triggers
Search, enable or disable, unlock, and restart triggers for flows.
Search triggers
search_triggers is paginated and requires page and size:
pythondef search_triggers():
tenant = "main"
result = kestra_client.triggers.search_triggers(
page=1,
size=50,
tenant=tenant
)
for t in result.results:
print(f"{t.trigger_context.trigger_id}: disabled={t.trigger_context.disabled}")Disable or enable a trigger
pythonimport datetime
from kestrapy.models import TriggerControllerSetDisabledRequest, Trigger
def disable_trigger():
tenant = "main"
request = TriggerControllerSetDisabledRequest(
triggers=[
Trigger(
namespace="my_namespace",
flow_id="my_flow",
trigger_id="my_schedule",
var_date=datetime.datetime.now(datetime.timezone.utc)
)
],
disabled=True # pass False to re-enable
)
kestra_client.triggers.disabled_triggers_by_ids(
tenant=tenant,
trigger_controller_set_disabled_request=request
)
print("Trigger disabled")Unlock a trigger
Use unlock_trigger to unlock a trigger that is stuck in a locked state:
pythondef unlock_trigger():
tenant = "main"
kestra_client.triggers.unlock_trigger(
namespace="my_namespace",
flow_id="my_flow",
trigger_id="my_schedule",
tenant=tenant
)
print("Trigger unlocked")Restart a trigger
pythondef restart_trigger():
tenant = "main"
kestra_client.triggers.restart_trigger(
namespace="my_namespace",
flow_id="my_flow",
trigger_id="my_schedule",
tenant=tenant
)
print("Trigger restarted")Dashboards
Create, search, and delete dashboards.
Create a dashboard
pythondef create_dashboard():
tenant = "main"
body = """
id: my_dashboard
title: My Dashboard
"""
dashboard = kestra_client.dashboards.create_dashboard(tenant=tenant, yaml_body=body)
print(f"Dashboard created: {dashboard.get('id')}")Search dashboards
pythondef search_dashboards():
tenant = "main"
result = kestra_client.dashboards.search_dashboards(tenant=tenant)
for d in result.get('results', []):
print(d.get('id'))Delete a dashboard
pythondef delete_dashboard():
tenant = "main"
kestra_client.dashboards.delete_dashboard(id="my_dashboard_id", tenant=tenant)
print("Dashboard deleted")Namespace files
List, read, and delete files stored in a namespace.
List files
pythondef list_files():
tenant = "main"
files = kestra_client.files.list_namespace_directory_files(
namespace="my_namespace",
tenant=tenant,
path="/"
)
for f in files:
print(f.file_name)Read file content
pythondef read_file():
tenant = "main"
content = kestra_client.files.file_content(
namespace="my_namespace",
path="/scripts/main.py",
tenant=tenant,
revision=None
)
print(f"Downloaded {len(content)} bytes")Delete a file
pythondef delete_file():
tenant = "main"
kestra_client.files.delete_file_directory(
namespace="my_namespace",
path="/scripts/main.py",
tenant=tenant
)
print("File deleted")Test suites
Test suites require Kestra Enterprise Edition.
Create, run, and fetch results for unit test suites.
Create a test suite
pythondef create_test_suite():
tenant = "main"
body = """
id: my_tests
namespace: my_namespace
flows:
- flowId: my_flow
"""
suite = kestra_client.test_suites.create_test_suite(tenant=tenant, yaml_body=body)
print(f"Test suite created: {suite.id}")Run a test suite
pythondef run_test_suite():
tenant = "main"
result = kestra_client.test_suites.run_test_suite(
namespace="my_namespace",
id="my_tests",
tenant=tenant
)
print(f"State: {result.state}")Get test results
pythondef get_test_result():
tenant = "main"
result = kestra_client.test_suites.test_result(id="run-id", tenant=tenant)
print(f"State: {result.state}")Apps
Apps require Kestra Enterprise Edition.
Create, enable, disable, and delete apps.
Create an app
pythondef create_app():
tenant = "main"
body = """
id: my_app
title: My App
"""
app = kestra_client.apps.create_app(tenant=tenant, yaml_body=body)
print(f"App created: {app.uid}")Enable or disable an app
pythondef enable_app():
tenant = "main"
kestra_client.apps.enable_app(uid="app-uid", tenant=tenant)
print("App enabled")
def disable_app():
tenant = "main"
kestra_client.apps.disable_app(uid="app-uid", tenant=tenant)
print("App disabled")Delete an app
pythondef delete_app():
tenant = "main"
kestra_client.apps.delete_app(uid="app-uid", tenant=tenant)
print("App deleted")Best practices
- Reuse your client: construct one
KestraClientper application and share it. - Avoid hardcoding credentials: use environment variables or a secrets manager.
- Validate YAML before submission: invalid syntax causes
422responses. - Combine
create_flowandcreate_executionfor end-to-end CI/CD automation.