For the complete documentation index, see llms.txt. Every page on this site is also served as Markdown: append `.md` to any URL, or send `Accept: text/markdown`.
Attensira Logo
Attensira

REST API endpoint

POST /v1/automations/{id}/runs — trigger a run now, without billing twice

Runs an automation immediately, outside its cadence, and returns a session handle rather than a finished result. Spends credits, and takes an idempotency key.

Karl-Gustav KallasmaaKarl-Gustav Kallasmaa, Founder & CEOLast updated
POST /v1/automations/{id}/runsNeeds write scopeSpends creditsMCP tool: run_automation

The request

Paste this and change the key. Every endpoint takes a bearer key and none takes a workspace id — the key names the workspace.

curl -X POST https://api.attensira.com/v1/automations/aut_71cd/runs \
  -H "Authorization: Bearer atn_live_<your key>" \
  -H "Idempotency-Key: 2026-09-02-monday-report"

Parameters

Every parameter the published reference documents, and nothing it does not.

NameInTypeDefaultNotes
id*pathstring—The automation to run now.
Idempotency-Keyheaderstring—Strongly recommended. A repeat call with the same key does not start — or bill — a second run.

The response (200)

Abbreviated, never invented — this is the shape the published reference documents.

{ "session_id": "ses_9d02", "status": "running" }

What goes wrong, and what it means

The condition on the left, the correct reading of it on the right.

A retry produced a second billed run
No idempotency key was sent. Without one, re-sending this request starts another run and charges for it, which makes a naive retry loop expensive.
The response says running and there is no answer
That is the success case. What comes back is a handle to work in progress, so the answer is polled from the sessions endpoint rather than returned here.
The status stays running for a long time
The run is still working. Fetch the session with its event trace to see which tools it has called rather than inferring a hang from the automation record.

What this endpoint cannot tell you

The limits are part of the answer, not a disclaimer under it.

  • It cannot return the run's answer. The response is a session id and a status, so anything that needs the output has to poll the sessions endpoint afterwards.
  • It cannot say in advance what the run will cost. The charge depends on what the instruction makes the agent do, and a manual trigger bills exactly like a scheduled execution of the same automation.

Most of the automation endpoints are free reads. This one spends money, and the single most useful thing to know about it is the header that stops it spending money twice.

Send an idempotency key

Without a key, this request does exactly what it says every time it arrives. Two identical calls are two runs, and two runs are two charges. That is the correct behaviour for an endpoint whose whole purpose is "do it again now" — but it is badly matched to how software actually calls APIs, because a timeout, a retry policy, a redeployed worker or a double-clicked button all produce a second identical request.

The Idempotency-Key header fixes that. A repeat call carrying the same key does not start a second run and does not bill for one. The documentation calls it strongly recommended; treat it as required in anything unattended.

A good key names the intent rather than the attempt. Something like the date plus the automation's purpose is ideal, because a retry naturally reconstructs the same string, which is precisely when you need the protection.

The response is a receipt, not a result

You get a session id and a status, and the status will usually be running. That is the success case. The endpoint answers 200 rather than 201 for exactly this reason: nothing has been created at a new URL, you have been handed a reference to work in progress.

From there the sessions endpoint is where the answer arrives. Poll it with the id; ask for the event trace if you want to see which tools the agent reached for and with what arguments. That trace is the difference between knowing an answer is wrong and knowing why.

Running now does not change the cadence

Triggering a run is orthogonal to the schedule. A weekly automation triggered on a Wednesday still runs on its Monday, and the manual run does not consume, delay or substitute for the scheduled one. If you want a one-off without a recurring cost, the right tool is an automation on a manual trigger, which never fires on a clock and exists precisely to be triggered.

What it costs

The same as a scheduled execution of the same automation, which is to say: it depends on what the instruction makes the agent do. There is no pre-flight estimate and this page does not quote a number, because the only correct source for what anything costs is the plan ladder rather than a paragraph in a reference page.

The practical discipline is the same as anywhere else with metered agent work. Run it by hand once, see what it consumed and whether the output was worth having, and let that inform whether it belongs on a daily cadence at all.

A useful pattern: dry run before you schedule

Because a manual trigger and a scheduled run are the same execution, this endpoint doubles as the test harness for automations. Create the automation with a manual trigger, run it here with a key, read the session's trace to check it is looking at the slice you meant, and only then change it to daily or weekly. That sequence catches the ambiguous-instruction problem before it becomes a recurring charge for answering the wrong question.

Its twin on the other surface

The run_automation MCP tool takes the id and an idempotency_key argument, which is mapped to the same header upstream. The documentation is emphatic that an assistant should pass one on every call, and the reason is worth repeating: an assistant that retries a tool call is much more likely than your own code to do so without being asked.

Questions people ask

Why does it answer 200 rather than 201?
Because what comes back is a handle to work in progress rather than a resource created at a new URL. The same convention applies to asking the agent.
What does the idempotency key protect against?
A duplicate billed run. A repeat call carrying the same key does not start a second run, which makes retries safe in a way they otherwise are not.
What should the key be?
Something stable that identifies the intent rather than the attempt — a date plus the automation's purpose works well, because a retry naturally reproduces it.
Does running an automation change its schedule?
No. It runs outside the cadence and the cadence continues unchanged.
How do I get the result?
Poll the sessions endpoint with the returned session id. Ask for events there if you want the step-by-step trace of what the agent did.

Sources

Every factual statement above, with the page it came from and the date that page was read.

  1. The Attensira API reference states that re-sending the run request without an Idempotency-Key starts a second billed run, and that a repeat call with the same key does not.

    docs.attensira.com · retrieved

    “Re-sending this POST without an Idempotency-Key starts a second billed run.”

  2. The API reference states that this endpoint answers 200 because it returns a handle to work in progress rather than a resource at a new URL, and that the caller polls the sessions endpoint.

    docs.attensira.com · retrieved

    “Returns a session handle, not a finished result.”

Next

The reference this is written from →Every endpoint →The same capability over MCP →