Skip to main content
GET
List runs
In the Heliyos MCP server: heliyos_runs_list.

Authorizations

Authorization
string
header
required

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

limit
integer
default:20

Runs per page, 1 to 100. Defaults to 20.

Required range: 1 <= x <= 100
cursor
string

The 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.

Maximum string length: 200
page
integer

A page number, starting at 1, for offset paging. Pages are limit runs long.

Required range: x >= 1
offset
integer

Runs to skip, for offset paging. Wins over page.

Required range: x >= 0
skip
integer

Same as offset.

Required range: x >= 0

Case-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.

Maximum string length: 500
status
string

Only runs in this status, exact match: queued, running, awaiting_approval, paused, waiting, scheduled, completed, failed, skipped, cancelled or stopped.

Maximum string length: 50
surface
string

Only 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.

Maximum string length: 50
taskId
string

Only runs on this task, including chats that mention it.

Maximum string length: 100
threadId
string

Only runs of this conversation (the threadId from Ask Heliyos).

Required string length: 1 - 100
Pattern: ^[A-Za-z0-9_.:@=+-]+$
interactionId
string

Only runs about this email thread or meeting, or started by it.

Pattern: ^[0-9a-fA-F]{24}$
companyId
string

Only runs about this company record, or started by it.

Pattern: ^[0-9a-fA-F]{24}$
personId
string

Only runs about this person record, or started by it.

Pattern: ^[0-9a-fA-F]{24}$
runtime
enum<string>

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.

Available options:
sandbox,
light
agentId
string

Only runs this worker took part in, was considered for, or focused on.

Maximum string length: 100
from
string<date-time>

Only runs created at or after this ISO 8601 date-time.

to
string<date-time>

Only runs created at or before this ISO 8601 date-time.

triggerType
string

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".

Maximum string length: 200
interactionIds
string

Comma-separated email thread or meeting ids. Only runs about any of them, or started by one. Comma-separated interaction ids.

Maximum string length: 5000
sortBy
enum<string>

Sort field: createdAt (default), updatedAt, status, title or surface. Anything but createdAt switches to offset paging.

Available options:
createdAt,
updatedAt,
status,
title,
surface
sortOrder
enum<string>

desc (default) or asc. asc switches to offset paging.

Available options:
asc,
desc
view
enum<string>

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.

Available options:
run,
timeline

Response

A page of runs.

meta
object
required
data
object[]
required