> ## 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 records > Returns the records of one object (base schema), such as your companies, people, deals or a custom object. Get the object's id and its field keys from the Objects endpoints. Each record's `data` holds only the object's fields. A field you may not view comes back as `null`. Every record also carries its links in `relationships` (each with the linked record's field values in `data`) and counts of linked comments, notes and open tasks. **Paging.** There are two modes. - **Cursor (default).** Send `limit` (1 to 100, default 20). Records come newest first (by creation). When `meta.pagination.next_cursor` is present, send it back as `cursor` for the next page. - **Page number.** Used as soon as you send `page` (query or `filters`), `filters.pageSize`, a `filters.sort` or a board (`"viewType": "kanban"`). Without a sort, records come most recently updated first. `meta.pagination` is `{ page, limit, totalPages, count, hasMore }`, where `count` is the number of matching records and `limit` is the page size actually used. A `cursor` together with a sort or a board is a 400. **Page size in page-number mode** is `filters.pageSize`, or `limit` when you do not send one. It is capped at 100. With `"bypassPageSizeCap": true` it can go up to 5000, for callers that need a complete set in one response. A `pageSize` above 200 (5000 with the bypass) is clamped rather than rejected. **Filtering.** Send a JSON object in `filters`, URL-encoded. Its keys are described on the parameter below. For example, deals in negotiation worth at least 50,000 that mention "northwind", soonest close date first, 50 per page: ```json { "search": "northwind", "filters": [ { "field": "stage", "operator": "equals", "value": "Negotiation" }, { "field": "deal_value", "operator": "greaterThanOrEqual", "value": 50000, "conjunction": "and" } ], "sort": [ { "field": "close_date", "direction": "asc" } ], "page": 1, "pageSize": 50 } ``` `curl -G --data-urlencode` encodes the JSON into the query string for you: ```bash curl -G "https://api-prod.heliyos.ai/v1/platform/base-schemas/66a0f1e2d3c4b5a697880003/records" \ -H "Authorization: Bearer heliyos_..." \ --data-urlencode 'filters={ "search": "northwind", "filters": [ { "field": "stage", "operator": "equals", "value": "Negotiation" }, { "field": "deal_value", "operator": "greaterThanOrEqual", "value": 50000, "conjunction": "and" } ], "sort": [ { "field": "close_date", "direction": "asc" } ], "page": 1, "pageSize": 50 '}' ``` **Boards.** With `"viewType": "kanban"` the response groups records by a field instead of paging them: `data` is an array of `RecordKanbanColumn` (`columnId`, `items`, `pagination`) holding every matching record, and `meta.pagination` is `{ page, limit, totalCount }`. See [Pagination](/api-reference/pagination) and [Filtering and sorting](/api-reference/filtering). > [!NOTE] > > In the Heliyos MCP server: [`heliyos_records_list`](https://docs.heliyos.ai/mcp/tools/records#heliyos-records-list), [`heliyos_watchlist_get`](https://docs.heliyos.ai/mcp/tools/watchlist#heliyos-watchlist-get). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/platform/base-schemas/{id}/records 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/base-schemas/{id}/records: get: tags: - Records summary: List records description: >- Returns the records of one object (base schema), such as your companies, people, deals or a custom object. Get the object's id and its field keys from the Objects endpoints. Each record's `data` holds only the object's fields. A field you may not view comes back as `null`. Every record also carries its links in `relationships` (each with the linked record's field values in `data`) and counts of linked comments, notes and open tasks. **Paging.** There are two modes. - **Cursor (default).** Send `limit` (1 to 100, default 20). Records come newest first (by creation). When `meta.pagination.next_cursor` is present, send it back as `cursor` for the next page. - **Page number.** Used as soon as you send `page` (query or `filters`), `filters.pageSize`, a `filters.sort` or a board (`"viewType": "kanban"`). Without a sort, records come most recently updated first. `meta.pagination` is `{ page, limit, totalPages, count, hasMore }`, where `count` is the number of matching records and `limit` is the page size actually used. A `cursor` together with a sort or a board is a 400. **Page size in page-number mode** is `filters.pageSize`, or `limit` when you do not send one. It is capped at 100. With `"bypassPageSizeCap": true` it can go up to 5000, for callers that need a complete set in one response. A `pageSize` above 200 (5000 with the bypass) is clamped rather than rejected. **Filtering.** Send a JSON object in `filters`, URL-encoded. Its keys are described on the parameter below. For example, deals in negotiation worth at least 50,000 that mention "northwind", soonest close date first, 50 per page: ```json { "search": "northwind", "filters": [ { "field": "stage", "operator": "equals", "value": "Negotiation" }, { "field": "deal_value", "operator": "greaterThanOrEqual", "value": 50000, "conjunction": "and" } ], "sort": [ { "field": "close_date", "direction": "asc" } ], "page": 1, "pageSize": 50 } ``` `curl -G --data-urlencode` encodes the JSON into the query string for you: ```bash curl -G "https://api-prod.heliyos.ai/v1/platform/base-schemas/66a0f1e2d3c4b5a697880003/records" \ -H "Authorization: Bearer heliyos_..." \ --data-urlencode 'filters={ "search": "northwind", "filters": [ { "field": "stage", "operator": "equals", "value": "Negotiation" }, { "field": "deal_value", "operator": "greaterThanOrEqual", "value": 50000, "conjunction": "and" } ], "sort": [ { "field": "close_date", "direction": "asc" } ], "page": 1, "pageSize": 50 '}' ``` **Boards.** With `"viewType": "kanban"` the response groups records by a field instead of paging them: `data` is an array of `RecordKanbanColumn` (`columnId`, `items`, `pagination`) holding every matching record, and `meta.pagination` is `{ page, limit, totalCount }`. See [Pagination](/api-reference/pagination) and [Filtering and sorting](/api-reference/filtering). operationId: listRecords parameters: - name: id in: path required: true schema: type: string pattern: ^[0-9a-fA-F]{24}$ description: The object's id. example: 66a0f1e2d3c4b5a697880003 - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: >- Records per page, 1 to 100. Defaults to 20. In page-number mode it is the page size when `filters.pageSize` is not sent. 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 in cursor mode: no sort and no board in `filters`. - name: page in: query required: false schema: type: integer minimum: 1 description: >- A page number, starting at 1. Switches to page-number paging. `filters.page` takes precedence when both are sent. example: 1 - name: filters in: query required: false schema: type: string maxLength: 20000 description: >- JSON-encoded filter object (search, filters, sort, page, pageSize, bypassPageSizeCap). Optional. pageSize above its bound is clamped: 200, or 5000 with bypassPageSizeCap: true. description: >- A JSON object, URL-encoded, at most 20,000 characters. No key may start with `$` or contain a dot. Keys: - `search` (string): matches records where any field value contains the text, ignoring case. Text, numbers and booleans are searched; lists, objects and values longer than 100 characters are not. Results are not ranked by relevance; they keep the mode's order or your `sort`. - `filters` (array, at most 500): conditions `{ "field", "operator", "value", "conjunction" }`. - `field`: a field key, or `createdAt`, `updatedAt` or `isAgentAssigned` (watched). Anything from the first `-` on is ignored. `.` (for example `company.company_name`) compares values stored on the record's links, not the linked record itself. - `operator`: `equals`, `notEquals` (exact match; text ignores case); `contains`, `notContains`, `startsWith`, `endsWith` (text, ignoring case; `value` must be a string, and a comma in a `contains` or `notContains` value means any or none of the parts); `empty`, `notEmpty` (missing, null or `""`; no value); `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual` (numbers); `after`, `before` (dates, the same as `greaterThan` and `lessThan`). Any other operator is treated as an exact match on the raw value. - `value`: a string, number or boolean. A string that looks like a number is compared as a number. Date fields are stored as text, so send ISO 8601 dates (`2026-12-31`). For `createdAt` and `updatedAt` the value is read as a date, and `equals` matches the whole day. - `conjunction`: `and` (default) or `or`. The first condition's is ignored; every other condition must use the same one. Mixing `and` and `or` is a 400. - `sort` (array): `{ "field", "direction" }`, with the same field names as conditions and direction `asc` or `desc`. Text sorts ignore case. Sorting by `.` leaves out records without a link of that type. - `page` (integer, at least 1) and `pageSize` (integer, at least 1): page-number paging. - `bypassPageSizeCap` (boolean): raises the page size cap from 100 to 5000. - `isAgentAssigned` (boolean): `true` for watched records only, `false` for the others. - `enrich` (boolean, default `true`): `false` leaves out linked records' values and returns 0 for the activity counts. Faster for pickers. - `viewType` (`kanban`) with `kanbanConfig.groupByField` (a field key, default `status`): return a board grouped by that field. example: >- {"search":"northwind","filters":[{"field":"stage","operator":"equals","value":"Negotiation"}]} responses: '200': description: A page of records, or a board when `filters.viewType` is `kanban`. 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 description: >- The records. With `"viewType": "kanban"`, an array of `RecordKanbanColumn` instead. items: $ref: '#/components/schemas/Record' example: meta: message: Objects fetched successfully pagination: limit: 20 next_cursor: NjZmMWE4YzNlNGIwYTFiMmMzZDRlNWY2 data: - _id: 6721c3d5e6f7a8b9c0d1e2f3 baseSchemaId: 66a0f1e2d3c4b5a697880003 organizationId: 66a0f1e2d3c4b5a697887766 objectType: deals data: deal_name: Northwind Traders renewal stage: Negotiation deal_value: 48000 close_date: '2026-12-15' assigned_to: - id: 66a0f1e2d3c4b5a697881111 firstName: Dana lastName: Reyes email: dana@example.com relationships: - _id: 6721c3d5e6f7a8b9c0d1e2f4 objectId: 66f1a8c3e4b0a1b2c3d4e5f6 schemaId: 66a0f1e2d3c4b5a697880001 objectType: company data: company_name: Northwind Traders website: https://northwind.example isAgentAssigned: false aiColumnStatus: {} commentCount: 1 noteCount: 2 taskCount: 1 metadata: created: at: '2026-11-02T14:10:00.000Z' by: 66a0f1e2d3c4b5a697881111 updated: at: '2026-11-04T09:30:00.000Z' by: 66a0f1e2d3c4b5a697881111 '400': description: >- VALIDATION_FAILED: `filters` is not a JSON object, carries a `$` or dotted key, mixes `and` and `or`, gives a text operator a non-string value, or `cursor` is sent with a sort or a board. A query the database rejects (for example a malformed sort) answers "Error fetching records". content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: 'FORBIDDEN_ACTION: you may not view this object.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: 'NOT_FOUND: no object 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: 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. Record: type: object description: >- One record. Which properties are present depends on the endpoint: list responses add activity counts, the get response adds `id`, `notes` and `tasks`. properties: _id: $ref: '#/components/schemas/ObjectId' id: type: string description: Get responses only. The record's id as a string, the same as `_id`. baseSchemaId: allOf: - $ref: '#/components/schemas/ObjectId' description: The object the record belongs to. organizationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The workspace the record belongs to. objectType: type: string description: >- The object's type: `company`, `people`, `deals` or a custom object's type. example: deals data: type: object additionalProperties: true description: >- The field values, keyed by the object's field keys. In list and get responses `data` holds only the object's fields, and a field you may not view is `null`. Create and update responses return the values as stored. relationships: type: array description: The records this record is linked to. items: $ref: '#/components/schemas/RecordRelationship' enrichmentStatus: type: string nullable: true enum: - NOT_ENRICHED - STARTED - FINISHED - FAILED description: >- Companies and people only. `NOT_ENRICHED` on create, `STARTED` while an enrichment runs, `FINISHED` or `FAILED` after it. enrichmentDate: allOf: - $ref: '#/components/schemas/Timestamp' nullable: true description: When the record was last enriched, or null. isAgentAssigned: type: boolean description: >- `true` when a worker watches the record (the record is on the watchlist). agentAssignmentStatus: type: string nullable: true description: >- `STARTED` while a newly assigned worker is setting up, otherwise null or absent. aiColumnStatus: type: object additionalProperties: type: string description: >- The run status of each AI field on this record, keyed by field key, for example `NOT_STARTED`. hubspotId: type: string description: >- The record's HubSpot id, when the workspace syncs it to HubSpot. Not in list responses. workspaceFolder: type: string description: >- The record's folder in the worker workspace, when one exists. Not in list responses. commentCount: type: integer description: >- List responses only. Open comment threads linked to the record. 0 with `"enrich": false`. noteCount: type: integer description: >- List responses only. Notes linked to the record. 0 with `"enrich": false`. taskCount: type: integer description: >- List responses only. Unfinished tasks linked to the record. 0 with `"enrich": false`. notes: type: array description: Get responses only. Every note linked to the record, newest first. items: type: object additionalProperties: true tasks: type: array description: Get responses only. Every task linked to the record, newest first. items: type: object additionalProperties: true metadata: $ref: '#/components/schemas/AuditMetadata' 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 RecordRelationship: type: object description: A link from this record to another record in the workspace. properties: _id: allOf: - $ref: '#/components/schemas/ObjectId' description: Id of the link itself. objectId: allOf: - $ref: '#/components/schemas/ObjectId' description: Id of the linked record. schemaId: allOf: - $ref: '#/components/schemas/ObjectId' description: Id of the linked record's object. objectType: type: string description: >- The linked record's object type: `company`, `people`, `deals` or a custom object's type. example: company data: type: object additionalProperties: true description: >- List responses only: the linked record's field values. Empty when the linked record no longer exists, and absent when the list was requested with `"enrich": false`. fullData: type: object nullable: true additionalProperties: true description: >- Get responses only. The complete linked record, in the same shape as `Record`. Timestamp: type: string format: date-time description: An ISO 8601 date-time in UTC. example: '2026-11-04T09:30:00.000Z' AuditMetadata: type: object description: Who created and last changed the resource, and when. properties: created: type: object properties: at: $ref: '#/components/schemas/Timestamp' by: allOf: - $ref: '#/components/schemas/ObjectId' description: Id of the user (or the API key's owner) who created it. updated: type: object properties: at: $ref: '#/components/schemas/Timestamp' by: allOf: - $ref: '#/components/schemas/ObjectId' description: Id of the user who last changed it. 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.