> ## 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 task events > Serves tasks only. The id must be a task's; any other id answers 404. For a company, person, deal or custom object record use List record events. Returns the change history of one task, newest first: who created or changed it, when, a one-line summary of each change, and before and after snapshots of the task. The two lists differ in scope. List record events folds in the events of everything linked to the record (its tasks, notes, emails, meetings, comments and files). This list holds only the task's own changes: a note or comment linked to the task does not appear here. The task's own changes also show up in List record events of every record the task is linked to. Changes made by people (in the app or through the API) and by workers are both recorded. An event is written just after the change it describes, so a change you have just made can take a moment to appear. A worker write that changes nothing a person would see (for example only its own run bookkeeping) is not recorded. This list has no filters: no event type, operation, date, actor or text search. Read the pages and filter on `metadata.operationType` and `metadata.actor` yourself. By default the list pages with a cursor: pass `limit`, then send `meta.pagination.next_cursor` back as `cursor`. Sending `page` switches to page-number paging, where `meta.pagination` holds only `page` and `limit` (no total and no `hasMore`): a page shorter than `limit` is the last one. See [Pagination](/api-reference/pagination). Task snapshots can be large. Send `fields` to get back only the parts of each snapshot you read. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_tasks_events`](https://docs.heliyos.ai/mcp/tools/tasks#heliyos-tasks-events). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/platform/tasks/{id}/events 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/tasks/{id}/events: get: tags: - Activities summary: List task events description: >- Serves tasks only. The id must be a task's; any other id answers 404. For a company, person, deal or custom object record use List record events. Returns the change history of one task, newest first: who created or changed it, when, a one-line summary of each change, and before and after snapshots of the task. The two lists differ in scope. List record events folds in the events of everything linked to the record (its tasks, notes, emails, meetings, comments and files). This list holds only the task's own changes: a note or comment linked to the task does not appear here. The task's own changes also show up in List record events of every record the task is linked to. Changes made by people (in the app or through the API) and by workers are both recorded. An event is written just after the change it describes, so a change you have just made can take a moment to appear. A worker write that changes nothing a person would see (for example only its own run bookkeeping) is not recorded. This list has no filters: no event type, operation, date, actor or text search. Read the pages and filter on `metadata.operationType` and `metadata.actor` yourself. By default the list pages with a cursor: pass `limit`, then send `meta.pagination.next_cursor` back as `cursor`. Sending `page` switches to page-number paging, where `meta.pagination` holds only `page` and `limit` (no total and no `hasMore`): a page shorter than `limit` is the last one. See [Pagination](/api-reference/pagination). Task snapshots can be large. Send `fields` to get back only the parts of each snapshot you read. operationId: listTaskEvents parameters: - name: id in: path required: true schema: type: string pattern: ^[0-9a-fA-F]{24}$ description: >- The task's id. Ids of companies, people, deals, custom object records, notes and interactions answer 404; for a record's history use List record events. example: 6728c9afb2c3d4e5f6a7b8ce - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Events 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. When you send both `cursor` and `page`, `cursor` wins. - name: page in: query required: false schema: type: integer minimum: 1 description: >- A page number, starting at 1, for page-number paging. Pages are `limit` events long. - name: fields in: query required: false schema: type: string maxLength: 2000 description: >- Only these fields of `originalVersion` and `updatedVersion`, comma-separated, for example `title,status,relationships.objectId`. Up to 30 field paths, each one to three dot-separated names of letters, digits and `_` (starting with a letter or `_`, up to 64 characters each). `_id`, `timestamp`, `metadata` and `changeSummary` are always returned. Leave it out for whole snapshots. example: title,status,dueDate responses: '200': description: A page of the task's events, newest first. 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/TaskEvent' example: meta: message: Task events fetched successfully pagination: limit: 20 next_cursor: NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2 data: - _id: 6728e1a0b2c3d4e5f6a7b8e2 timestamp: '2026-11-04T15:20:00.000Z' metadata: eventType: AUDIT operationType: UPDATE objectType: task objectUUID: 6728c9afb2c3d4e5f6a7b8ce organizationUUID: 66a0f1e2d3c4b5a697887766 actor: type: USER uuid: 66a0f1e2d3c4b5a697881111 name: Priya Patel changeSummary: >- Priya Patel moved Send security questionnaire to Northwind Traders from Backlog to In progress. originalVersion: title: Send security questionnaire to Northwind Traders status: backlog dueDate: '2026-11-08T00:00:00.000Z' updatedVersion: title: Send security questionnaire to Northwind Traders status: in_progress dueDate: '2026-11-08T00:00:00.000Z' - _id: 6728c9b0b2c3d4e5f6a7b8cf timestamp: '2026-11-04T09:40:00.000Z' metadata: eventType: AUDIT operationType: CREATE objectType: task objectUUID: 6728c9afb2c3d4e5f6a7b8ce organizationUUID: 66a0f1e2d3c4b5a697887766 actor: type: AGENT uuid: 3f9a1c2b7d4e4f0a9b8c7d6e5f4a3b2c name: Account researcher changeSummary: >- Account researcher created the task Send security questionnaire to Northwind Traders. originalVersion: null updatedVersion: title: Send security questionnaire to Northwind Traders status: backlog dueDate: '2026-11-08T00:00:00.000Z' '400': description: >- VALIDATION_FAILED: a malformed query value or cursor, or a `fields` value that is not up to 30 comma-separated field paths. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: 'FORBIDDEN_ACTION: you cannot view tasks.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: >- NOT_FOUND: no task with this id in the workspace (including a task that was deleted), or the id belongs to a record, note or interaction. 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. TaskEvent: type: object description: >- One change to a task. Snapshots are stored as they were at the time of the change, with credential values (tokens, secrets, passwords, API keys) replaced by `[REDACTED]`. additionalProperties: true properties: _id: $ref: '#/components/schemas/ObjectId' timestamp: allOf: - $ref: '#/components/schemas/Timestamp' description: When the change happened. metadata: type: object additionalProperties: true properties: eventType: type: string description: >- `AUDIT` on every task event: a person or worker created or changed the task. The other event types (`INTERACTION`, `ENRICHMENT`) belong to records and do not appear here. example: AUDIT operationType: type: string enum: - CREATE - UPDATE - DELETE description: >- `CREATE`: the task was created. `UPDATE`: the task changed. `DELETE` is recorded when a task is deleted, but a deleted task's history can no longer be read here (the call answers 404). objectType: type: string description: Always `task`. objectUUID: type: string description: The task's id. Always the task you asked for. organizationUUID: type: string description: The workspace id. actor: type: object description: Who made the change. properties: type: type: string enum: - USER - AGENT - SYSTEM description: >- `USER`: a person, in the Heliyos app or through an API key. `AGENT`: a worker. `SYSTEM`: Heliyos itself. Task changes are almost always `USER` or `AGENT`. uuid: type: string description: >- For `USER`, the user id (for an API key, the key owner's id). For `AGENT`, the worker run id; older entries say `agent`. name: type: string description: >- A display name: the person's name, or the worker's name (`Heliyos` when Heliyos itself made the change during a run). changeSummary: type: string description: >- A one-line, human-readable description of the change, written by Heliyos shortly after the change. Can be missing on very recent or older events. originalVersion: type: object nullable: true additionalProperties: true description: >- The task before the change: null or empty for a create. With `fields`, only the requested fields are present. updatedVersion: type: object nullable: true additionalProperties: true description: >- The task after the change. With `fields`, only the requested fields are present. 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 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.