curl --request GET \
--url https://api-prod.heliyos.ai/v1/platform/workers/runs \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-prod.heliyos.ai/v1/platform/workers/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/workers/runs"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"meta": {
"message": "Successful request",
"pagination": {
"limit": 20,
"next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2"
}
},
"data": [
{
"_id": "6729d1e2f3a4b5c6d7e8f9a0",
"orchestratorRunId": "9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e",
"organizationId": "66a0f1e2d3c4b5a697887766",
"status": "completed",
"title": "Contoso weekly summary",
"surface": "chat",
"runtime": "sandbox",
"userInput": "Summarise what changed with Contoso this week and list open risks.",
"triggerRef": {
"type": "chat"
},
"relationships": [
{
"objectId": "66f1a8c3e4b0a1b2c3d4e5f6",
"objectType": "company"
}
],
"threadId": "3fa9c2d17b4e",
"userId": "66a0f1e2d3c4b5a697881111",
"workers": [
{
"agentId": "6720f3a1b2c3d4e5f6a7b8c9",
"agentName": "Account researcher",
"nodeId": "w1",
"status": "completed"
}
],
"toolCalls": 6,
"finalOutput": {
"final_response_by": "Heliyos",
"response": "Contoso moved to Negotiation on Tuesday."
},
"usage": {
"credits": 5,
"requests": 9,
"inputTokens": 48210,
"outputTokens": 1630,
"totalTokens": 49840
},
"createdAt": "2026-11-05T10:12:02.000Z",
"updatedAt": "2026-11-05T10:12:41.000Z",
"completedAt": "2026-11-05T10:12:41.000Z"
}
]
}{
"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>"
}
}List runs
Returns the workspace’s runs, newest first: Ask Heliyos conversations, worker chats, task runs,
and runs started by events and schedules. Read one run’s steps with
Get a run, using its orchestratorRunId.
By default the list pages with a cursor: pass limit, then send meta.pagination.next_cursor
back as cursor. Sending page, offset or skip, or a sort other than newest first, switches to
offset paging: meta.pagination then has limit, offset, total and hasMore, and there is no
cursor. See Pagination.
Filters combine with AND.
curl --request GET \
--url https://api-prod.heliyos.ai/v1/platform/workers/runs \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-prod.heliyos.ai/v1/platform/workers/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/workers/runs"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text){
"meta": {
"message": "Successful request",
"pagination": {
"limit": 20,
"next_cursor": "NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2"
}
},
"data": [
{
"_id": "6729d1e2f3a4b5c6d7e8f9a0",
"orchestratorRunId": "9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e",
"organizationId": "66a0f1e2d3c4b5a697887766",
"status": "completed",
"title": "Contoso weekly summary",
"surface": "chat",
"runtime": "sandbox",
"userInput": "Summarise what changed with Contoso this week and list open risks.",
"triggerRef": {
"type": "chat"
},
"relationships": [
{
"objectId": "66f1a8c3e4b0a1b2c3d4e5f6",
"objectType": "company"
}
],
"threadId": "3fa9c2d17b4e",
"userId": "66a0f1e2d3c4b5a697881111",
"workers": [
{
"agentId": "6720f3a1b2c3d4e5f6a7b8c9",
"agentName": "Account researcher",
"nodeId": "w1",
"status": "completed"
}
],
"toolCalls": 6,
"finalOutput": {
"final_response_by": "Heliyos",
"response": "Contoso moved to Negotiation on Tuesday."
},
"usage": {
"credits": 5,
"requests": 9,
"inputTokens": 48210,
"outputTokens": 1630,
"totalTokens": 49840
},
"createdAt": "2026-11-05T10:12:02.000Z",
"updatedAt": "2026-11-05T10:12:41.000Z",
"completedAt": "2026-11-05T10:12:41.000Z"
}
]
}{
"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_runs_list.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.
Query Parameters
Runs per page, 1 to 100. Defaults to 20.
1 <= x <= 100The next_cursor from the previous page. Only valid with the default order (newest first).
next_cursor from the previous page; only valid with the default sort.
200A page number, starting at 1, for offset paging. Pages are limit runs long.
x >= 1Runs to skip, for offset paging. Wins over page.
x >= 0Same as offset.
x >= 0Case-insensitive text matched against the run id, title, the message that started it, worker names, the triggering event name and the final reply. Up to 500 characters.
500Only runs in this status, exact match: queued, running, awaiting_approval, paused, waiting, scheduled, completed, failed, skipped, cancelled or stopped.
50Only runs that started here: chat (Ask Heliyos), worker_chat (a chat with one worker), task_chat (a chat on a task), background (events, schedules and tasks) or worker_direct.
50Only runs on this task, including chats that mention it.
100Only runs of this conversation (the threadId from Ask Heliyos).
1 - 100^[A-Za-z0-9_.:@=+-]+$Only runs about this email thread or meeting, or started by it.
^[0-9a-fA-F]{24}$Only runs about this company record, or started by it.
^[0-9a-fA-F]{24}$Only runs about this person record, or started by it.
^[0-9a-fA-F]{24}$sandbox or light. Runs started through workers are sandbox. light runs come from an older pipeline that is hidden unless you also send its surface.
sandbox, light Only runs this worker took part in, was considered for, or focused on.
100Only runs created at or after this ISO 8601 date-time.
Only runs created at or before this ISO 8601 date-time.
Comma-separated trigger kinds: only runs set off by one of them, for example event,mention. Kinds include chat, event, webhook, mention, task_created and scheduled.
Comma-separated trigger kinds, e.g. "event,mention".
200Comma-separated email thread or meeting ids. Only runs about any of them, or started by one. Comma-separated interaction ids.
5000Sort field: createdAt (default), updatedAt, status, title or surface. Anything but createdAt switches to offset paging.
createdAt, updatedAt, status, title, surface desc (default) or asc. asc switches to offset paging.
asc, desc run (default) returns runs as described here. timeline returns each run flattened into the run-and-steps shape the Heliyos inbox renders; that shape is for the app and may change.
"timeline": the run + steps view the inbox renders.
run, timeline Was this page helpful?

