Run & simulate
curl -X POST https://api.tapeapp.com/v1/automation/4021/manual-run \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{ "record_id": 5001 }'
{ "message": "Use the automation-run API to poll the run. Based on queueing and limitations, this may be delayed." }
curl -X POST https://api.tapeapp.com/v1/automation/4021/simulate \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{ "record_id": 5001 }'
curl https://api.tapeapp.com/v1/automation/4021/validate \
-H "Authorization: Bearer $TAPE_TOKEN"
{
"valid": false,
"errors": [
{ "code": "action_app_missing", "message": "An action references an app that no longer exists.", "action_id": "a1b2c3", "app_id": 42, "deactivated": false }
]
}
Use these endpoints to run an automation for real, simulate it without side effects, and validate its definition.
Run and simulate need Run automations (automations:run), validate needs Read automations (automations:read). All three need the Admin role in the app's workspace and work with a personal access token, an OAuth access token or a user API key. See Capabilities.
The run body is trigger-aware
Manual run and simulate share one body. Send the payload that the automation's trigger expects. The automation in the path already fixes the trigger, so you don't name it again.
Record-based (record_created, record_updated, record_deleted, date_field_arrived, record_comment_or_reply_created, automation_called, weblink_clicked)
{ "record_id": <id> }
webhook_received
{ "webhook_payload": <object or string> } or { "use_last_received_webhook_payload": true }
periodic, or no trigger
{}
| Trigger | Body |
|---|---|
Record-based (record_created, record_updated, record_deleted, date_field_arrived, record_comment_or_reply_created, automation_called, weblink_clicked) | { "record_id": <id> } |
webhook_received | { "webhook_payload": <object or string> } or { "use_last_received_webhook_payload": true } |
periodic, or no trigger | {} |
A well-formed body that doesn't match the automation's actual trigger returns 400.
Yes. Manual run and simulate use the automation's stored definition, whether it's paused or not, so you can test without setting it live. Only a broken definition returns 409.
The call automation endpoint works differently: it creates no run for a paused target and reports no error.
Both endpoints queue the work for a background worker and answer 202 with a fixed message. A manual run creates its run only after the record passes the filter. A simulation skips the filter. To see the result, poll List runs for an automation and match triggered_on_record_id to your record. type tells real and simulation runs apart (manual or simulation).
A run's per-action logs arrive after the run reaches a final status (completed or failed). The trigger and filter steps are there from the start.
- Poll for the specific log entry you need. Don't wait for
logs.length > 0, which can return before an action's entry is in. - Some successful steps write no per-action
successentry: the control-flow containers (conditional,for_loop),collected_records_collect_referenced_recordsandcreate_pdf. For those, a finalcompletedwithout a setup failure is the success signal. - An action with
deactivate: truewrites no entry. Tape removes it before the run starts, so it's missing from the log, not listed asskipped. See Automation run for how the two differ and whenskippedappears.
Run an automation
Use this endpoint to run an automation on a record, with real side effects.
/v1/automation/{automation_id}/manual-runapi.tapeapp.comcurl -X POST https://api.tapeapp.com/v1/automation/4021/manual-run \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{ "record_id": 5001 }'
{ "message": "Use the automation-run API to poll the run. Based on queueing and limitations, this may be delayed." }
To find automation_id, see List automations. In the automation editor, it's the number after /edit-workflow/ in the address.
To check the run, follow step 3 of Run an existing automation.
General behavior
- This is the API version of Manual run in the automation editor, for one record. See Execution types.
- Tape queues the run with at-least-once delivery. One request can run the automation more than once.
- Tape applies the filter. A record that doesn't match creates no run.
- Each request costs
1xbase credits. A real run also uses automation action credits, reported asnum_consumed_actions. record_idmust point to a live record in the automation's app. A deleted record, a record in another database app or an unknown ID returns404before Tape schedules the run.- To test
current_record_restore, delete the record within the run: put acurrent_record_deletestep before it.
For a record_comment_or_reply_created automation, a manual run uses the record's most recent comment or reply as the current comment. A record without comments or replies creates no run. The endpoint still answers 202.
Requirements: automations:run, and the Admin role in the app's workspace. Works with a personal access token, an OAuth access token or a user API key.
Errors
- An automation ID that isn't an integer, or a body that doesn't match the trigger, returns
400. - A credential that doesn't act on behalf of a user returns
401. - A token without
automations:runreturns403. - An automation or record that isn't available to you returns
404. - A broken automation returns
409.
Simulate an automation
Use this endpoint to run the automation's stored definition as a dry run, with no side effects.
/v1/automation/{automation_id}/simulateapi.tapeapp.comcurl -X POST https://api.tapeapp.com/v1/automation/4021/simulate \
-H "Authorization: Bearer $TAPE_TOKEN" \
-H "Content-Type: application/json" \
--data '{ "record_id": 5001 }'
The response is the same 202 with { "message": … } as for Run, with no run ID.
General behavior
- A simulation creates a simulation run every time. Most run lists leave it out. List runs for an automation shows it, and you can retrieve it by ID.
- The body is the same as for Run. Each request costs
1xbase credits. - You also need view access to the target record.
Requirements: automations:run, and the Admin role in the app's workspace. Works with a personal access token, an OAuth access token or a user API key.
Errors
The same causes as for Run return 400, 401, 403, 404 and 409.
Validate an automation
Use this endpoint to check whether the current definition can run.
/v1/automation/{automation_id}/validateapi.tapeapp.comcurl https://api.tapeapp.com/v1/automation/4021/validate \
-H "Authorization: Bearer $TAPE_TOKEN"
{
"valid": false,
"errors": [
{ "code": "action_app_missing", "message": "An action references an app that no longer exists.", "action_id": "a1b2c3", "app_id": 42, "deactivated": false }
]
}
Key fields
valid:truewhen no error sits in an active part of the automation. An entry withdeactivated: truedoesn't count.errors: one entry per fault. Each entry has the same shape and the same broken-reason codes asbroken_reasonon the automation object.
General behavior
- No request body.
- Tape computes a fresh verdict. It can differ from the stored
brokenflag, because create and update don't store a new verdict.
validate check?validate checks meaning, not syntax: whether a stored definition still points to things that exist and can be reached. Typical faults are a deleted field or app, a removed connection, or an action that uses a collection no earlier action creates. These faults can appear after a successful save, without any change to the definition.
Payload format is checked earlier. Create and update reject a malformed body with 400, for example an unknown enum value, a broken dynamic-value reference or a tree nested too deep.
valid: true mean the run succeeds?Not necessarily. validate checks the listed faults, and some references only for presence. For example, Tape only checks that the app_view_id of a collect_app_view_records action isn't empty, so a wrong view ID fails only when the automation runs.
Requirements: automations:read, and the Admin role in the app's workspace. Works with a personal access token, an OAuth access token or a user API key.
Errors
- An automation ID that isn't an integer returns
400. - A credential that doesn't act on behalf of a user returns
401. - A token without
automations:readreturns403. - An automation that isn't available to you returns
404.