Python SDK

The official Python SDK is automators-com/datamaker-py. Its import name is datamaker.

Install

The SDK is published to PyPI as datamaker-py and needs Python 3.11 or later.

pip install "datamaker-py>=0.12.0"

Pin an exact version in your lockfile for a reproducible environment. Do not install the unrelated bare datamaker package from PyPI; the import name is datamaker, but the distribution name is datamaker-py.

Authenticate

DataMaker() reads DATAMAKER_API_KEY and DATAMAKER_API_URL. The default API URL is https://api.datamaker.automators.com. You can pass api_key and base_url explicitly. Use a project-scoped key, or pass scope headers when needed:

import os
from datamaker import DataMaker

dm = DataMaker(default_headers={
    "X-Project-Id": os.environ["DATAMAKER_PROJECT_ID"],
})

Keep API keys in your environment or secret manager. Inside a scenario, the runner injects the API credentials and run context; DataMaker() uses those settings.

Define a template and generate

from datamaker import DataMaker, Template

dm = DataMaker()
template = Template(name="Customer", quantity=3, fields=[
    {"name": "first_name", "type": "First Name"},
    {"name": "last_name", "type": "Last Name"},
    {"name": "email", "type": "Derived",
     "options": {"value": "{{first_name}}.{{last_name}}@example.com"}},
])
result = dm.generate(template)

For a saved template:

result = dm.generate_from_template_id("<template-id>", quantity=100)

Both methods return the parsed API object with live_data and dependencies. The rows are in live_data, not the object itself.

Read the rows

live_data is a list with one dictionary per row, keyed by field name:

rows = result["live_data"]
print(f"Generated {len(rows)} rows")
for row in rows:
    print(row)  # e.g. {"first_name": "Ada", "last_name": "Byron", "email": "Ada.Byron@example.com"}

Inspect the rows for generation errors before exporting. Successful HTTP status alone does not establish that every field contains usable data.

Work with resources

The Python client exposes flat methods such as get_templates(), get_connections(), get_endpoints() and get_projects(). Typed dictionaries describe responses; they remain ordinary Python dictionaries at runtime.

Consult the SDK source for exact method arguments, especially write payloads. Use the REST API for operations not wrapped by your installed SDK version.

Errors

from datamaker.error import DataMakerError

try:
    result = dm.generate_from_template_id("<template-id>", quantity=10)
except DataMakerError as error:
    raise RuntimeError("Data generation failed; inspect the API response") from error

Avoid printing exceptions containing sensitive upstream payloads in shared logs. For file outputs, use the scenario workspace directories.