Read records in Creatio
readQuery Creatio records using filters, select, orderBy, top, skip, and count. Retrieve specific fields, filter by related records, and paginate results efficiently.
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. |