Appearance
Audience
These tools find the tags, segments and custom fields in an account, for example to choose who a campaign goes to or which tag starts an automation.
They are read-only. Tags, segments and custom fields are created and edited in Rule. The tools never read or change individual subscribers.
Every tool also takes the optional account_id (see Accounts). It is left out of the tables below.
Paging
All four tools return up to 100 items at a time:
| Parameter | Type | Required | Description |
|---|---|---|---|
page | number | No | Page number, starting at 1. |
per_page | number | No | Items per page, up to 100. Defaults to 100. |
Each answer says whether there are more pages (hasMore). To find something specific, the assistant searches by name (query) instead of paging, and only then says whether it exists.
list-tags
Lists the account's tags with their id and a link to each tag in Rule, or finds tags by name.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | No | Find every tag whose name contains this text (not case-sensitive). The whole list is searched, so paging does not apply. |
page, per_page | number | No | See Paging. |
- A search says whether the whole list was searched (
searchedAll). In an account with a very large number of tags, a tag that is not found may still exist. - Rule does not report how many tags there are in total, so the assistant cannot tell you the number of pages.
Try asking: "List my tags."
list-segments
Lists the account's segments with their id and a link to each segment in Rule, or finds segments by name.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | No | Find every segment whose name contains this text (not case-sensitive). The whole list is searched, so paging does not apply. |
page, per_page | number | No | See Paging. |
- Segments that Rule creates for its own use (behind automation delays) are not listed. A page can therefore hold fewer segments than
per_page. - The rules that define a segment cannot be read here; open the segment in Rule.
Try asking: "Which segments do I have?"
list-custom-field-groups
Lists the account's custom field groups, each with the custom fields inside it.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | No | Only groups whose name contains this text (not case-sensitive). |
include_fields | boolean | No | Include each group's fields. Defaults to true. With false, each group shows only how many fields it has. |
page, per_page | number | No | See Paging. |
- Each field has a
type, such astext,number,boolean,date,singleormultiple. - A group marked
historicalkeeps every value a subscriber has had (for example one entry per order), not just the latest. - The selectable values of
singleandmultiplefields are not listed; they come from subscriber data. - In an account with very many fields, a page can be too large to return. The tool then says so, and the assistant lists the groups without their fields (
include_fields: false), or searches withquery. - To check whether a group exists, the assistant searches for it by name rather than paging.
Try asking: "What custom fields do I have?"
list-custom-fields
Lists the custom fields in one group.
| Parameter | Type | Required | Description |
|---|---|---|---|
group_id | number | Yes | The group's id, from list-custom-field-groups. |
query | string | No | Only fields whose name contains this text (not case-sensitive). |
page, per_page | number | No | See Paging. |
- A group that does not belong to the account is reported as not found.
Try asking: "Which fields are in my Orders group?"