> ## Documentation Index > Fetch the complete documentation index at: https://docs.heliyos.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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](/api-reference/pagination). Filters combine with AND. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_runs_list`](https://docs.heliyos.ai/mcp/tools/ask-runs-and-reviews#heliyos-runs-list). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/platform/workers/runs openapi: 3.0.3 info: title: Heliyos API version: 1.0.0 description: >- The REST API for Heliyos, the AI operating system for revenue. Every request is scoped to the workspace that owns the API key. Responses are JSON in a `{ meta, data }` envelope; errors use `{ message, error: { code, message, details } }`. contact: name: Heliyos support email: soham@heliyos.ai url: https://www.heliyos.ai servers: - url: https://api-prod.heliyos.ai description: Production security: - bearerAuth: [] tags: - name: Workspace description: >- The workspace your API key belongs to, and the log of credits it has used. Every other call in this API is scoped to this workspace. - name: Schemas description: >- Objects are your record types: companies, people, deal pipelines and any custom objects you add. Each object has fields, and a field's type decides what its records can hold. - name: Records description: >- Records are the rows of an object (base schema): companies, people, deals and custom objects. A record holds field values keyed by the object's field keys and links to other records. - name: Timeline description: >- The AI-written timeline of a company, person or deal: summary entries Heliyos writes on a schedule. For the exact change history see Activities, and for emails and meetings see Interactions. - name: Activities description: >- The change history of records and tasks: who created, changed or deleted what, and when. People, workers and the system each appear as the actor on the changes they make. - name: Interactions description: >- Email threads and meetings synced from connected mailboxes and calendars, linked to the people and companies they involve. - name: Notes description: >- Free-text notes, optionally linked to records, tasks and interactions. Notes show up on the timeline of every record they are linked to, and workers read them as customer memory. - name: Tasks description: >- Work items for people and workers, optionally linked to records. A task can be assigned to people, to workers, or both, and workers can be started on it directly. - name: Workers and runs description: >- Workers are the AI teammates of your workspace (the API calls them agents). Define what each one does and what starts it, ask Heliyos to do work, and follow every run, its steps and the reviews it waits on. - name: Reviews description: >- Reviews keep the team in control of consequential work. When a worker wants to send an email, change a deal, book a meeting, act in a connected app or needs a person's answer, the action waits as a review until someone approves or rejects it. - name: Scouts description: >- Scouts watch companies and the web for events such as funding rounds, product launches, leadership changes or press coverage, and record each finding as a signal. A workspace Scout defines what to look for; company Scouts are its copies running on individual companies. - name: Signals description: >- Signals are what Scouts find: one event, such as a funding round or a new executive, with a summary, its sources and the company it is about. New signals are unread until you mark them read. - name: Watchlist description: >- The watchlist is the set of companies your workers monitor. Each watched company uses one Watcher from your plan: the workers keep it enriched, pull in its emails and meetings, and run Scouts on it. - name: Knowledge base description: >- What your workers know about the business: the business context, four fixed texts (products, pain points, value proposition, qualification criteria) and any custom entries your team adds. Workers read it on their next run. Files your workers read live under Files, with kind `knowledge_base`. - name: Files description: >- Knowledge base files that workers read, and files attached to records, tasks and other resources. The API calls them attachments. Uploading takes three calls: get an upload URL, send the bytes to it, then create the file. - name: Labels description: >- Label groups that sort your email threads, for example Intent or Pricing questions. Heliyos files each classified thread under a group, and each group holds the more specific labels it brings together. The API calls them classification labels. - name: Team description: >- The people in your workspace and their roles: joined members and pending invitations. Inviting someone sends them an email. - name: Notification settings description: >- Which workspace events send notification emails, how often, and to whom. There is one settings document per workspace, shared by everyone in it. paths: /v1/platform/workers/runs: get: tags: - Workers and runs summary: List runs description: >- 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](/api-reference/pagination). Filters combine with AND. operationId: listWorkerRuns parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Runs per page, 1 to 100. Defaults to 20. example: 20 - name: cursor in: query required: false schema: type: string maxLength: 200 description: >- next_cursor from the previous page; only valid with the default sort. description: >- The `next_cursor` from the previous page. Only valid with the default order (newest first). - name: page in: query required: false schema: type: integer minimum: 1 description: >- A page number, starting at 1, for offset paging. Pages are `limit` runs long. - name: offset in: query required: false schema: type: integer minimum: 0 description: Runs to skip, for offset paging. Wins over `page`. - name: skip in: query required: false schema: type: integer minimum: 0 description: Same as `offset`. - name: search in: query required: false schema: type: string maxLength: 500 description: >- 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. example: Contoso - name: status in: query required: false schema: type: string maxLength: 50 description: >- Only runs in this status, exact match: `queued`, `running`, `awaiting_approval`, `paused`, `waiting`, `scheduled`, `completed`, `failed`, `skipped`, `cancelled` or `stopped`. example: awaiting_approval - name: surface in: query required: false schema: type: string maxLength: 50 description: >- 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`. example: chat - name: taskId in: query required: false schema: type: string maxLength: 100 description: Only runs on this task, including chats that mention it. example: 6721a0b1c2d3e4f5a6b7c8d9 - name: threadId in: query required: false schema: type: string pattern: ^[A-Za-z0-9_.:@=+-]+$ minLength: 1 maxLength: 100 description: Only runs of this conversation (the `threadId` from Ask Heliyos). example: 3fa9c2d17b4e - name: interactionId in: query required: false schema: type: string pattern: ^[0-9a-fA-F]{24}$ description: Only runs about this email thread or meeting, or started by it. example: 6721a3c4d5e6f7a8b9c0d1e2 - name: companyId in: query required: false schema: type: string pattern: ^[0-9a-fA-F]{24}$ description: Only runs about this company record, or started by it. example: 66f1a8c3e4b0a1b2c3d4e5f6 - name: personId in: query required: false schema: type: string pattern: ^[0-9a-fA-F]{24}$ description: Only runs about this person record, or started by it. example: 66f1a8c3e4b0a1b2c3d4e5f7 - name: runtime in: query required: false schema: type: string enum: - sandbox - light description: >- `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`. - name: agentId in: query required: false schema: type: string maxLength: 100 description: >- Only runs this worker took part in, was considered for, or focused on. example: 6720f3a1b2c3d4e5f6a7b8c9 - name: from in: query required: false schema: type: string format: date-time description: Only runs created at or after this ISO 8601 date-time. example: '2026-11-01T00:00:00Z' - name: to in: query required: false schema: type: string format: date-time description: Only runs created at or before this ISO 8601 date-time. example: '2026-11-05T23:59:59.999Z' - name: triggerType in: query required: false schema: type: string maxLength: 200 description: Comma-separated trigger kinds, e.g. "event,mention". description: >- 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`. example: event,scheduled - name: interactionIds in: query required: false schema: type: string maxLength: 5000 description: Comma-separated interaction ids. description: >- Comma-separated email thread or meeting ids. Only runs about any of them, or started by one. - name: sortBy in: query required: false schema: type: string enum: - createdAt - updatedAt - status - title - surface description: >- Sort field: `createdAt` (default), `updatedAt`, `status`, `title` or `surface`. Anything but `createdAt` switches to offset paging. - name: sortOrder in: query required: false schema: type: string enum: - asc - desc description: '`desc` (default) or `asc`. `asc` switches to offset paging.' - name: view in: query required: false schema: type: string enum: - run - timeline description: '"timeline": the run + steps view the inbox renders.' description: >- `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. responses: '200': description: A page of runs. content: application/json: schema: type: object required: - meta - data properties: meta: type: object required: - message properties: message: type: string description: A human-readable summary of the result. pagination: $ref: '#/components/schemas/KeysetPagination' data: type: array items: $ref: '#/components/schemas/WorkerRunListItem' example: 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' '400': description: >- VALIDATION_FAILED: for example a cursor sent with a sort other than newest first. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: KeysetPagination: type: object description: >- Cursor paging. Pass `next_cursor` back as `cursor` with the same `limit` for the next page. required: - limit properties: limit: type: integer description: The page size used for this page. example: 20 next_cursor: type: string description: Cursor for the next page. Absent on the last page. WorkerRunListItem: type: object additionalProperties: true description: >- A run as stored, without its step log and execution graph. Read one run with **Get a run** for its steps. Runs can carry more fields than these; treat unknown ones as internal and subject to change. properties: _id: $ref: '#/components/schemas/ObjectId' orchestratorRunId: type: string description: The run id. Pass it to **Get a run**. organizationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The workspace. status: type: string description: The run's status. See `status` on **Get a run** for every value. title: type: string description: A short title for the run. surface: type: string description: >- Where the run started: `chat` (Ask Heliyos), `worker_chat`, `task_chat`, `background` (an event, schedule or task) or `worker_direct`. runtime: type: string description: '`sandbox` or `light`.' agentName: type: string nullable: true description: The worker the run focused on, when there was one. userInput: type: string description: The message that started a chat run, up to 4,000 characters. trigger: type: object additionalProperties: true description: The trigger that started the run, with its payload. triggerRef: allOf: - $ref: '#/components/schemas/WorkerRunTrigger' description: The trigger kind and the record it named. relationships: type: array description: Every record the run touched. items: type: object properties: objectId: type: string description: The record's id. objectType: type: string description: >- The record's kind, for example `company`, `people`, `deals`, `task` or `interaction`. taskId: type: string nullable: true description: The task the run works on. threadId: type: string nullable: true description: The conversation, for chat runs. userId: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true description: The person who started the run, for chat runs. workers: type: array description: >- The workers that took part (`agentId`, `agentName`, `nodeId`, `status`). items: type: object additionalProperties: true toolCalls: type: integer description: How many tool calls the run made. finalOutput: allOf: - $ref: '#/components/schemas/WorkerRunOutput' nullable: true description: The final reply, once there is one. usage: $ref: '#/components/schemas/WorkerRunUsage' error: type: string description: Why the run failed. createdAt: $ref: '#/components/schemas/Timestamp' updatedAt: $ref: '#/components/schemas/Timestamp' completedAt: allOf: - $ref: '#/components/schemas/Timestamp' description: When the run finished. ErrorEnvelope: type: object required: - message - error properties: message: type: string description: Same as error.message. error: type: object required: - code - message properties: code: type: string enum: - VALIDATION_FAILED - UNAUTHENTICATED - FORBIDDEN_ACTION - NOT_FOUND - RATE_LIMITED - CONFLICT - INTERNAL message: type: string details: {} ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ description: A 24-character hexadecimal id. example: 66f1a8c3e4b0a1b2c3d4e5f6 WorkerRunTrigger: type: object description: What set the run off, without its payload. properties: type: type: string description: >- The trigger kind, for example `chat`, `event`, `mention`, `task_created` or `scheduled`. objectType: type: string description: >- The kind of record the trigger named, for example `task`, `company` or `interaction`. objectId: type: string description: The id of that record. event: type: string description: The event name, for example `deal.updated`. WorkerRunOutput: type: object additionalProperties: true description: The run's final reply. properties: final_response_by: type: string description: Who wrote the reply, Heliyos or the worker that owned the answer. response: type: string description: The reply text, in Markdown. WorkerRunUsage: type: object additionalProperties: true description: What the run used. Counters appear once there is something to count. properties: credits: type: number description: Credits charged to the workspace by this run (custom worker calls). requests: type: integer description: Model requests made. inputTokens: type: integer description: Input tokens used. outputTokens: type: integer description: Output tokens used. totalTokens: type: integer description: Input plus output tokens. Timestamp: type: string format: date-time description: An ISO 8601 date-time in UTC. example: '2026-11-04T09:30:00.000Z' securitySchemes: bearerAuth: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.