Read records in Creatio
readQuery Creatio CRM records with filters, pagination, and sorting to retrieve exactly the data you need.
Instructions
Query Creatio records. Workflow: 1) list-entities 2) describe-entity 3) read with select, filters, orderBy, top. Key params: select (fields to return), filters (conditions — recommended), orderBy (sorting), top (limit), skip (pagination offset), count (return total). Always include fields used in filters in select when select is provided. Filter related records via navigation (Contact/Name, Contact/Id) — a scalar lookup XxxId with a GUID is handled for you. Paginate with skip+top (+ a stable orderBy). To COUNT, set count:true (response becomes { total, value }); for count-only use count:true + top:0. For date/time filtering see /datetime-guide prompt. For Contact/Owner filtering see /contactid-guide prompt. Examples: entity:'Order', select:['Id','Number','Amount'], filters:{ all:[{ field:'ContactId', op:'eq', value:'' }] }, orderBy:'Amount desc', top:25, skip:0. count-only: entity:'Opportunity', filters:{ all:[{ field:'ContactId', op:'eq', value:'' }] }, count:true, top:0.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Max rows to return ($top). Defaults to 50 when omitted (so results are never unbounded); raise it or paginate with skip for more. Use top:0 with count:true for a count-only query. Suggest 25–200. | |
| skip | No | Offset pagination ($skip): skip this many matching rows before returning. Combine with top to page, e.g. page 3 of 25 → skip:50, top:25. Pair with a stable orderBy so pages do not overlap. | |
| count | No | When true, also return the TOTAL number of matching records ($count=true), ignoring top/skip. The response shape becomes { total, value } instead of a bare array. 💡 For a COUNT-ONLY question ("how many opportunities does X have"), set count:true AND top:0 — you get { total: N, value: [] } in one request instead of fetching rows. Filter the same way as a normal read (e.g. lookups via ContactId → auto Contact/Id). | |
| entity | Yes | Creatio OData entity set to query (e.g., Contact, Account, Activity). Tip: call "list-entities" first, then "describe-entity" to confirm fields before reading. | |
| select | No | Fields to return from the main entity. Strongly recommended for performance. ⚠️ IMPORTANT: $select works ONLY for direct properties of the entity! - ✅ CORRECT: select=['Id','Name','AccountId','Email'] - ❌ WRONG: select=['Account/Name'] - navigation paths NOT supported ⚠️ CRITICAL: When using $filter with $select: - ALWAYS include filtered fields in $select array - Example: filter by AccountId → select=['Id','AccountId',...] - Creatio returns error "Column by path X not found" if field filtered but not selected - This does NOT apply to expanded entities - those are separate 💡 TO GET RELATED DATA: Use expand parameter (RECOMMENDED)! - expand=['Account'] loads full Account object automatically - No need to include expanded fields in select - Much better than making separate requests Use 'describe-entity' to discover available field names. | |
| filters | No | Structured filters (alternative to raw $filter). Handles OData syntax, GUID formatting, and lookup navigation automatically. 🔗 FILTERING BY A LOOKUP (related record) — use NAVIGATION, not the scalar FK: - By name (best): Contact/Name eq 'Andrew Baker', Type/Name eq 'Employee' - By id: Contact/Id eq <guid> (GUID, no quotes) - ❌ Do NOT filter the scalar `ContactId`/`OwnerId`/`AccountId` directly — Creatio OData 500s with "Column by path XxxId not found in schema". - The primary key `Id eq <guid>` DOES work as-is (it is a real column, not a lookup). (With this structured parameter you can pass either form — a `XxxId` field with a GUID value is auto-rewritten to `Xxx/Id`.) Examples: - Lookup by name: { all:[{ field:'Contact/Name', op:'eq', value:'Andrew Baker' }] } (RECOMMENDED) - Lookup by id: { all:[{ field:'ContactId', op:'eq', value:'60733efc-f36b-1410-a883-16d83cab0980' }] } // becomes Contact/Id eq <guid> - Multiple AND: { all:[{ field:'IsActive', op:'eq', value:true }, { field:'Name', op:'contains', value:'John' }] } - Multiple OR: { any:[{ field:'Stage/Name', op:'eq', value:'Presentation' }, { field:'Stage/Name', op:'eq', value:'Negotiation' }] } | |
| orderBy | No | OData $orderby clause for sorting results. Syntax: "FieldName asc" or "FieldName desc" Multiple fields: "Field1 asc, Field2 desc" ✅ EXAMPLES: - orderBy: "Name asc" - sort by name ascending - orderBy: "CreatedOn desc" - newest first - orderBy: "Amount desc" - highest amount first - orderBy: "Name asc, Amount desc" - sort by multiple fields ⚠️ NOTE: You can only sort by direct properties of the entity. Sorting by navigation properties (like Account/Name) is NOT supported in Creatio OData. |