# Concepts (/en/docs/developers/automation/concepts)



Scripts and workflows define the work. A run records one execution, a trigger determines when it starts, and an action provides a reusable capability during execution.

## Definitions, versions and tags [#definitions-versions-and-tags]

Scripts and workflows share `namespace/name`; a name belongs to only one kind. Drafts are editable. Published versions are immutable and version numbers cannot be reused. Publishing identical content under the same version returns that version. Deprecation preserves history rather than deleting it.

References follow npm version and dist-tag conventions: `docs-samples/hello@1.0.0` pins a version; `@^1.2.0`, `@~1.2` and `@1.x` select ranges; `@latest` follows a tag. Omitting `@` means `@latest`. Each run records the version it actually resolved.

Stable releases update `latest` according to version selection rules; publishing an older release does not automatically move it backwards. A prerelease requires an explicit tag such as `beta`. Tags such as `stable` and `beta` can move. A tag cannot be a version or range, and `latest` cannot be deleted. Moving a tag affects subsequent resolution without modifying published content.

[Publish a version](/en/docs/api/native/automation/publishScriptVersion) to preserve content and [set a tag](/en/docs/api/native/automation/setScriptTag) to point to an existing version. Tag writes do not require `If-Match`. Draft updates require the current ETag; publishing a draft requires `expected_draft_revision`.

Actions have revisions rather than semantic versions. Compatible changes take effect immediately; call records identify the revision used. Use a new action name for an incompatible schema. Published workflows lock script and child-workflow dependencies to exact versions; actions are not locked.

## Run lifecycle [#run-lifecycle]

| Status      | Meaning                                                 |
| ----------- | ------------------------------------------------------- |
| `pending`   | Accepted and waiting to start.                          |
| `running`   | Executing.                                              |
| `waiting`   | A workflow is waiting for an event, timer or child run. |
| `suspended` | A workflow has been suspended.                          |
| `completed` | Succeeded; read `output`.                               |
| `faulted`   | Failed; read `error`.                                   |
| `cancelled` | Cancellation completed.                                 |

Scripts do not enter `waiting` or `suspended`. During cancellation, a run may remain `running` with `cancel_requested_at` set. A timeout is `faulted` with error type `timeout`, not a separate status. Terminal runs cannot resume. [Rerun](/en/docs/api/native/automation/rerunRun) creates a new root run whose `rerun_of` points to the original.

HTTP success means the request was handled, not that execution succeeded. Check `status`, `output` and `error`. Inspect script [calls](/en/docs/api/native/automation/listRunCalls) and [logs](/en/docs/api/native/automation/listRunLogs), or workflow [tasks](/en/docs/api/native/automation/listRunTasks) and [waits](/en/docs/api/native/automation/listRunWaits).

## Child runs and origin [#child-runs-and-origin]

A script can start a child through `praxis.automation.runs.create`. The child's `initiator` remains the original human, API Key or trigger. `parent_run_id` expresses the parent relationship. Filter by `channel=run` for runs started by another run, or by `parent_run_id` for a particular parent's children. Public run details expose a `parent` summary and `root_run_id`.

Cancellation cascades to children; normal parent completion allows children to continue. A child's deadline cannot exceed the parent's remaining time. Repeating a target in the call chain is rejected as a cycle. See [limits](/en/docs/developers/automation/limits-and-errors) for depth and fan-out bounds.

## Idempotency and retries [#idempotency-and-retries]

[Create a run](/en/docs/api/native/automation/createRun) accepts `Idempotency-Key`, scoped to the owner, HTTP method, path and key for 24 hours. The request fingerprint excludes `wait`. Reuse the key and body when retrying a network request. A replay returns the current run with `Idempotent-Replayed: true`. Use a fresh key when deliberately starting another execution.

A different request with the same key returns `IDEMPOTENCY_KEY_MISMATCH`; a request still in progress returns `IDEMPOTENCY_IN_FLIGHT`. See the create-run error table. Idempotency does not roll back effects from calls completed before a failure.

## Cost attribution [#cost-attribution]

Runs do not carry a separate execution charge. Model, search and other capabilities called during a run are charged at their regular prices and attributed to the run and trigger. A calculation that calls no such capability incurs no model or search charge.

[API reference →](/en/docs/api/native/automation) · [Cookbook →](/en/docs/cookbook)