Guides
API reference
MCP server
Changelogcurl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/tasks/{id}/runs \
--header 'Authorization: Bearer <token>'const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-prod.heliyos.ai/v1/platform/tasks/{id}/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api-prod.heliyos.ai/v1/platform/tasks/{id}/runs"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text){
"meta": {
"message": "Task run started."
},
"data": {
"triggered": true,
"orchestratorRunId": "3f9a1c2b7d4e4f0a9b8c7d6e5f4a3b2c",
"status": "queued"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}Run workers on a task
Starts Heliyos workers on a task now, the same as pressing Play on the task. The call takes no body.
What it does, in order:
- Clears the task’s paused flag and, unless the task is
completedorcancelled, moves it toin_progress(and setsisFinishedto false). - Looks for a run already open on the task (
queued,running,paused,awaiting_approvalorwaiting). If there is one, it is returned withtriggered: falseand no new run starts. Aqueuedorrunningrun that has written nothing for 20 minutes is treated as dead and does not count. - Otherwise starts a new run with
triggered: trueand statusqueued. The run starts even when no worker subscribes to new tasks, and it cancels any wake-up a worker had scheduled for the task.
The call returns as soon as the run is queued. Follow it with GET /v1/platform/workers/runs/{id}
using orchestratorRunId.
Credits. Each time the run calls one of your custom workers, the workspace is charged a fixed number of credits; Heliyos’s built-in workers are free. If the workspace cannot cover a custom worker call when the run starts, nothing starts and the call answers 409. Actions the workers take (for example enrichment) can use credits of their own.
Reviews. Workers write companies, people, tasks, notes and email drafts directly. Deal changes,
sending email, booking meetings, actions in connected apps and anything a worker asks you to decide
wait for a person’s review unless the workspace’s autopilot settings allow them, and even then a call
below the confidence threshold still waits. While an action waits, the run’s status is awaiting_approval.
Idempotency. Calling again while a run is open returns that run. The check is not atomic, so two calls at the same moment can start two runs.
curl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/tasks/{id}/runs \
--header 'Authorization: Bearer <token>'const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-prod.heliyos.ai/v1/platform/tasks/{id}/runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api-prod.heliyos.ai/v1/platform/tasks/{id}/runs"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text){
"meta": {
"message": "Task run started."
},
"data": {
"triggered": true,
"orchestratorRunId": "3f9a1c2b7d4e4f0a9b8c7d6e5f4a3b2c",
"status": "queued"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}heliyos_tasks_run.Authorizations
A workspace API key, sent as Authorization: Bearer heliyos_.... Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in.
Path Parameters
The task's id.
^[0-9a-fA-F]{24}$Was this page helpful?