> ## 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. # Get a run > Returns one run: its status, what set it off, every step with a one-line summary, the reviews it raised, its credit and model usage, and its final reply once it has one. Send `wait` to long-poll: the call holds for up to that many seconds while the run is `queued` or `running`, and returns as soon as it finishes or starts waiting on a person or a schedule. A run that is already in one of those states returns at once. `include=detail` adds the title, error, the workers that took part and the tool-call count. `include=step_payloads` adds each step's raw input, output and error, and the execution graph; these can be large. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_runs_get`](https://docs.heliyos.ai/mcp/tools/ask-runs-and-reviews#heliyos-runs-get). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/platform/workers/runs/{id} 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/{id}: get: tags: - Workers and runs summary: Get a run description: >- Returns one run: its status, what set it off, every step with a one-line summary, the reviews it raised, its credit and model usage, and its final reply once it has one. Send `wait` to long-poll: the call holds for up to that many seconds while the run is `queued` or `running`, and returns as soon as it finishes or starts waiting on a person or a schedule. A run that is already in one of those states returns at once. `include=detail` adds the title, error, the workers that took part and the tool-call count. `include=step_payloads` adds each step's raw input, output and error, and the execution graph; these can be large. operationId: getWorkerRun parameters: - name: id in: path required: true schema: type: string pattern: ^[A-Za-z0-9_.:@=+-]+$ minLength: 1 maxLength: 128 description: >- The run id (`runId` from Ask Heliyos, or `orchestratorRunId` from **List runs**). example: 9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e - name: wait in: query required: false schema: type: integer minimum: 0 maximum: 30 description: >- Seconds to long-poll until the run finishes or waits on a person (0 = answer at once). description: >- Seconds to wait for the run to finish or stop on a person, 0 to 30. Defaults to 0 (answer at once). example: 30 - name: include in: query required: false schema: type: string pattern: ^(detail|step_payloads)(,(detail|step_payloads))*$ description: >- Comma list. detail: title, surface, error, workers, toolCalls, createdAt (the run view). step_payloads: each step's raw input, output and error, and the execution graph. description: >- Comma-separated extras: `detail`, `step_payloads`, or both (`detail,step_payloads`). example: detail responses: '200': description: The run. 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. data: $ref: '#/components/schemas/WorkerRun' example: meta: message: Successful request data: id: 9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e status: awaiting_approval trigger: type: chat startedAt: '2026-11-05T10:12:02.000Z' endedAt: null threadId: 3fa9c2d17b4e taskId: null steps: - seq: 1 type: worker title: Account researcher status: completed startedAt: '2026-11-05T10:12:05.000Z' endedAt: '2026-11-05T10:12:31.000Z' summary: >- Contoso moved to Negotiation on Tuesday. Procurement asked for a security review. - seq: 2 type: approval title: send_email status: pending startedAt: '2026-11-05T10:12:38.000Z' endedAt: null summary: null reviews: - id: 6729d2f0a1b2c3d4e5f6a7b8 status: PENDING type: email_draft usage: credits: 5 requests: 7 inputTokens: 40120 outputTokens: 1210 totalTokens: 41330 title: Contoso follow-up agentName: Heliyos surface: chat error: null workers: - nodeId: w1 agentId: 6720f3a1b2c3d4e5f6a7b8c9 agentName: Account researcher status: completed toolCalls: 4 createdAt: '2026-11-05T10:12:02.000Z' '400': description: Validation failed 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: no run with this id in the workspace.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: WorkerRun: type: object properties: id: type: string description: The run id. status: type: string enum: - queued - running - awaiting_approval - paused - waiting - scheduled - completed - failed - skipped - cancelled - stopped description: > Still going: - `queued`: created, about to start. - `running`: working now. Waiting on a person or a schedule (it will not move until that happens): - `awaiting_approval`: paused on one or more reviews in `reviews`. It resumes when every one is decided. - `paused`: paused by a person. It resumes when someone resumes it or sends a message on its thread. - `waiting`: it set itself a wait and wakes up at the scheduled time. - `scheduled`: it waits for a scheduled time. Finished, never changes again: - `completed`: done. `output` has the reply. - `failed`: stopped on an error. Read `error` (with `include=detail`) and the failed step. - `skipped`: did not run, for example because the same event already started a run. - `cancelled`: cancelled before it finished. - `stopped`: stopped by a person. trigger: allOf: - $ref: '#/components/schemas/WorkerRunTrigger' nullable: true description: What set the run off. startedAt: allOf: - $ref: '#/components/schemas/Timestamp' nullable: true description: When the run started. endedAt: allOf: - $ref: '#/components/schemas/Timestamp' nullable: true description: When it finished. `null` until it is in a finished status. threadId: type: string nullable: true description: The conversation the run belongs to, for chat runs. taskId: type: string nullable: true description: The task the run works on, for task runs. steps: type: array description: Every step so far, in order. items: $ref: '#/components/schemas/WorkerRunStep' reviews: type: array description: The reviews the run raised, oldest first. items: $ref: '#/components/schemas/WorkerRunReview' usage: allOf: - $ref: '#/components/schemas/WorkerRunUsage' nullable: true description: Credits and model usage so far. output: allOf: - $ref: '#/components/schemas/WorkerRunOutput' description: The run's final reply, once it has one. title: type: string nullable: true description: '`include=detail` only: the run''s title.' agentName: type: string nullable: true description: >- `include=detail` only: who planned the run, Heliyos or the worker it focused on. surface: type: string nullable: true description: >- `include=detail` only: where the run started. See `surface` on **List runs**. error: type: string nullable: true description: '`include=detail` only: why the run failed.' workers: type: array description: '`include=detail` only: the workers that took part.' items: type: object properties: nodeId: type: string description: The worker's step in the run. agentId: type: string description: The worker's id. agentName: type: string description: The worker's name. status: type: string description: The worker's status in this run. startedAt: $ref: '#/components/schemas/Timestamp' endedAt: $ref: '#/components/schemas/Timestamp' toolCalls: type: integer description: '`include=detail` only: how many tool calls the run made.' createdAt: allOf: - $ref: '#/components/schemas/Timestamp' nullable: true description: '`include=detail` only: when the run was created.' graph: type: object nullable: true additionalProperties: true description: >- `include=step_payloads` only: the run's full execution graph (`nodes`, `edges`). 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: {} 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`. Timestamp: type: string format: date-time description: An ISO 8601 date-time in UTC. example: '2026-11-04T09:30:00.000Z' WorkerRunStep: type: object properties: seq: type: integer description: The step's position in the run, starting at 1. type: type: string description: > What the step was: `worker` (a worker was called), `tool` (a tool call), `approval` (a review was raised), `wait` and `wakeup` (the run scheduled a wait and woke up), `handoff`, `final` (the reply). Older or light runs can show other kinds. title: type: string nullable: true description: The worker, tool or step label. status: type: string nullable: true description: >- The step's status, for example `pending`, `running`, `completed`, `failed`, `waiting`, `approved` or `rejected`. startedAt: allOf: - $ref: '#/components/schemas/Timestamp' nullable: true description: When the step started. endedAt: allOf: - $ref: '#/components/schemas/Timestamp' nullable: true description: When the step ended. `null` while it runs. summary: type: string nullable: true description: >- The first 200 characters of the step's error, else of its result's text. `null` when the result is raw data. input: nullable: true description: '`include=step_payloads` only: the step''s raw input.' output: nullable: true description: '`include=step_payloads` only: the step''s raw output.' error: nullable: true description: '`include=step_payloads` only: the step''s raw error.' WorkerRunReview: type: object description: >- A review the run raised. Reviews are decided by a person in Heliyos, under Review. properties: id: allOf: - $ref: '#/components/schemas/ObjectId' description: The review's id. status: type: string nullable: true enum: - PENDING - PROCESSING - APPROVED - REJECTED - null description: | - `PENDING`: waiting for a person. - `PROCESSING`: decided, and the decision is being carried out. - `APPROVED`: approved. The run goes on with the action. - `REJECTED`: rejected. The run goes on without it. type: type: string nullable: true description: >- What is being reviewed, for example `email_draft` (an email to send), `deal_update` (a deal change), `meeting_scheduled` or `classification_label`. The set is open: an action from a connected app uses its own name. See [List reviews](/api-reference/reviews/list-reviews). 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. 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. ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ description: A 24-character hexadecimal id. example: 66f1a8c3e4b0a1b2c3d4e5f6 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.