Finds records of one object by filters, sort and text search, page by page. It can also save the whole result as a file in your account instead of returning it in the chat.
- Changes data: no
- Who can use it: Your role’s rights on that object in the “Entities” group of the role: “Read”.
What it is for
- Follow your trips and see when a truck reached a point. See Fleets.
- Export a list and email it as a file. See Email.
- Find drafts, a shipment by number or records by condition. See How it works.
- Check for a duplicate before creating a truck. See Fleets.
- Export a whole list to a file. See How it works.
Example prompts
- “Show the draft shipments created this week.”
- “Find our locations with Lviv in the name.”
- “Export every truck to a file.”
Good to know
- Each field supports its own operators, or none:
entities-schemalists them asfilter_ops, and text search covers only fields markedsearchable. For example, locations are searched by name and filtered by name or type. - Shipments are filtered by number, your own code, status, final price, distance and creation date.
- Without
sort, system objects (shipments, trips, trucks and the others) come newest first. Sorting: shipments by creation date, trucks and trailers by plate, locations by name, trips by order date. - Text search: a shipment by number or your own code, a truck by plate, VIN or code, a trailer by plate or VIN, a driver by phone, a location by name, a data model record by its text fields.
- A file holds up to 2,000 records and 2 MB. With
sort, a list or a file holds up to 100 records.truncatedsays when the result was cut. Each export is saved as a JSON file named after the object; itsfile_idcan be attached to an email withintegration-cargofy-send_email.
Reference
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
entity | string | yes | The object, as entities-list names it. |
filters | array | no | Conditions, all of which must match. Each: field, op and value. op is one of eq, neq, in, gt, gte, lt, lte, contains, between, is_null. |
sort | object | no | field and dir: asc or desc, desc by default. Not together with cursor. |
limit | integer | no | Records per page, 1 to 100. 20 by default. |
cursor | string | no | next_cursor of the previous page, to get the next one. |
search | string | no | Text to search for in the records. |
save_as_file | boolean | no | Saves the result as a file in your account and returns the file instead of the records. |
Returns
count, total, next_cursor and records, each with id, display_value and data. With save_as_file: file_id, file_name, path, count, total and truncated.
Errors
- A refusal for an object that cannot be read.
- An unknown operator: “Invalid filter operator …” with the list of valid ones.
- A field that does not support the operator, for example
Field "city" does not support filter operator "eq". - “sort must be an object with a field.” or “sort.dir must be "asc" or "desc".”
Field "…" is not sortable.Unknown filter field "…".