Scenarios
Save repeatable Python workflows with explicit inputs, outputs and run status.
A scenario is Python code saved with requirements, environment variables, a timeout and workspace files. Use it for repeatable generation, preparation, delivery and reporting.
Create or save a scenario
Create one in Scenarios, or ask the agent to save a completed workflow as a scenario. Review the code before running it: check targets, data volume, credentials, output paths and error handling.
A minimal scenario can write a result without contacting an external system:
import json
import os
from pathlib import Path
output_dir = Path(os.environ["DATAMAKER_WORKSPACE_OUTPUTS"])
output_dir.mkdir(parents=True, exist_ok=True)
(output_dir / "example.json").write_text(
json.dumps([{"id": 1, "status": "ready"}], indent=2),
encoding="utf-8",
)
print("Wrote 1 example row")For generated data, use the Python SDK and convert its live_data columns to row objects before writing JSON or CSV.
Run and inspect
Run from the editor or chat. Review environment variables when prompted. Watch the log, then inspect the result files and any target-side writes. Let unrecoverable exceptions fail the script; printing an error and exiting normally can make a broken workflow look successful.
A re-run starts the script from the beginning. Use stable identifiers, target lookups or supported key-map workflows to avoid creating duplicates after a partial failure.
Trigger through the API
Use POST /scenarios/execute with projectId, scenarioId, optional environmentVariables and async: true for hosted asynchronous execution. Poll the returned job ID until completed or failed. See REST API and CI/CD for complete examples.
The runner's injected scenario credential cannot start another scenario run. Use separately authorized orchestration for chained runs rather than assuming the run credential is a general scheduler key.