List records

curl --request GET \
  --url https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "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"
        }
      }
    }
  ]
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

Records

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:

{
  "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:

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 and Filtering and sorting.

GET

platform

base-schemas

{id}

records

List records

curl --request GET \
  --url https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api-prod.heliyos.ai/v1/platform/base-schemas/{id}/records"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "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"
        }
      }
    }
  ]
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "message": "<string>",
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "details": "<unknown>"
  }
}

In the Heliyos MCP server: heliyos_records_list, heliyos_watchlist_get.

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.

Path Parameters

string

required

The object's id.

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

Query Parameters

limit

integer

default:20

Records per page, 1 to 100. Defaults to 20. In page-number mode it is the page size when filters.pageSize is not sent.

Required range: 1 <= x <= 100

cursor

string

The next_cursor from the previous page. Only valid in cursor mode: no sort and no board in filters. next_cursor from the previous page; only valid with the default sort.

Maximum string length: 200

page

integer

A page number, starting at 1. Switches to page-number paging. filters.page takes precedence when both are sent.

Required range: x >= 1

filters

string

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. <objectType>.<fieldKey> (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 <objectType>.<fieldKey> 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. JSON-encoded filter object (search, filters, sort, page, pageSize, bypassPageSizeCap). Optional. pageSize above its bound is clamped: 200, or 5000 with bypassPageSizeCap: true.

Maximum string length: 20000

Response

A page of records, or a board when filters.viewType is kanban.

Overview

Workspace

Schemas

Records

Timeline

Activities

Interactions

Notes

Tasks

Workers and runs

Reviews

Scouts

Signals

Watchlist

Knowledge base

Files

Labels

Team

Notification settings

List records

Authorizations

Path Parameters

Query Parameters

Response