Querying items
Filter, sort and search a board's items, read them group by group or with a Group by, or run a saved view, and page through the results with cursors.
Use the items query when you need more than every item in creation order. Each answer is one page, with a cursor for the next.
The examples on this page, except the one in The board's groups, use a board of deals with these columns: stage (status, with the labels new, quoted, won and lost), owner (person), close_date (date), contact_email (email) and amount (number).
Two ways to read items
GET /v1/boards/{boardId}/items | POST /v1/boards/{boardId}/items/query | |
|---|---|---|
| What it returns | Every live item, oldest first | The items that match your query, in your order |
| What you can send | limit and cursor in the URL | A saved view, or a filter, sort, Group by and search, plus layout, groupIds, limit, cursor, timeZone, archived and counts, in a JSON body |
| Counts | No | With counts: true |
| Reference | List items | Query items |
The plain GET is the same read as a query with an empty body. A cursor from the GET works with an empty query, and the other way round. Use the GET to copy a whole board, and the query for anything else.
The query is a POST because a filter does not fit in a URL. It only reads: it changes nothing.
Both answer with items, nextCursor, formerMembers and apiKeys. Each item has its ID, name, values keyed by column ID, its group (groupId) and its place in that group (position), who created and last changed it and when, and whether it is archived. Values come only for the board's live columns. formerMembers names the people the items mention who have left the workspace, and apiKeys names the keys that created or changed them. The value of each column type is in Column values.
The request body
Send either a saved view's ID in view (Saved views), or the query fields: filter, sort and group. Every other field works with both: layout and groupIds, search, archived (true for archived items instead of live ones), limit and cursor (Paging), timeZone and counts.
Left out or null, filter, group and search mean none. layout left out means flat, except for a saved view. An empty body, {}, returns every live item in creation order.
viewstringoptional
A saved view's ID. It stands in for
filter,sortandgroup, so they cannot be sent with it;search,archived,layoutandgroupIdscan. With a view,layoutleft out isgroupsfor a table view with no column grouping andflatotherwise. Parts of the view that no longer fit the board's columns are left out.- Pattern
^viw_[0-9a-z]{21}$
- Pattern
filterFilter or nulloptional
Which items to include. Left out or null means all.
Show 2 fieldsHide 2 fields
joinstringrequired
How the entries combine:
andwhen all must match,orwhen any one is enough.- One of
"and","or"
- One of
conditionsarray of one of FilterCondition, FilterGrouprequired
Conditions and condition groups. A condition has
column; a condition group hasconditions. Up to 25 conditions in all, those in condition groups included, and up to 5 condition groups.- Up to 25 items
Show 2 optionsHide 2 options
One of:
FilterConditionFilterCondition
One test on one column:
column,operatorand, except foris_emptyandis_not_empty,value. Which operators a column takes depends on its type.Show 11 optionsHide 11 options
One of:
operator: "is"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is"
- Always
valueFilterValuerequired
A plain value, Me on a person column, or a relative date on a date column. Text is matched ignoring ASCII case. A day tested against a column that includes a time means that whole day in
timeZone.Show 3 optionsHide 3 options
One of:
option 1one of string, number
A label or option ID for status and dropdown, a user ID for person, text (up to 200 characters), a number, or a date as
YYYY-MM-DDorYYYY-MM-DDTHH:MM:SS.sssZ.FilterMeFilterMe
Me: the member making the request. Person columns only. An API key is not a person, so a key's query that holds Me answers
QUERY_INVALID.Show 1 fieldHide 1 field
typestringrequired
- Always
"me"
- Always
FilterRelativeDateFilterRelativeDate
A range of days worked out when the query runs, in
timeZone. Date columns only.ismeans inside it,is_notoutside it,greater_thanafter its end andless_thanbefore its start.Show 2 fieldsHide 2 fields
typestringrequired
- Always
"relative_date"
- Always
valuestringrequired
The range. Weeks start on Monday;
last_7_daysandnext_7_daysinclude today.- One of
"today","yesterday","tomorrow","this_week","last_week","next_week","this_month","last_month","last_7_days","last_30_days","next_7_days","next_30_days"
- One of
operator: "is_not"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is_not"
- Always
valueFilterValuerequired
A plain value, Me on a person column, or a relative date on a date column. Text is matched ignoring ASCII case. A day tested against a column that includes a time means that whole day in
timeZone.
operator: "is_any_of"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is_any_of"
- Always
valuearray of FilterValuerequired
1 to 25 values, each as for
is.- 1 to 25 items
operator: "is_none_of"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is_none_of"
- Always
valuearray of FilterValuerequired
1 to 25 values, each as for
is.- 1 to 25 items
operator: "is_empty"object
Show 2 fieldsHide 2 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is_empty"
- Always
operator: "is_not_empty"object
Show 2 fieldsHide 2 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"is_not_empty"
- Always
operator: "contains"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"contains"
- Always
valuestringrequired
Text to look for, 1 to 200 characters, ignoring ASCII case.
- 1 to 200 characters
operator: "does_not_contain"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"does_not_contain"
- Always
valuestringrequired
Text to look for, 1 to 200 characters, ignoring ASCII case.
- 1 to 200 characters
operator: "greater_than"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"greater_than"
- Always
valueone of string, number, FilterRelativeDaterequired
A number, a date, or a relative date.
Show 2 optionsHide 2 options
One of:
option 1one of string, number
A label or option ID for status and dropdown, a user ID for person, text (up to 200 characters), a number, or a date as
YYYY-MM-DDorYYYY-MM-DDTHH:MM:SS.sssZ.FilterRelativeDateFilterRelativeDate
A range of days worked out when the query runs, in
timeZone. Date columns only.ismeans inside it,is_notoutside it,greater_thanafter its end andless_thanbefore its start.Show 2 fieldsHide 2 fields
typestringrequired
- Always
"relative_date"
- Always
valuestringrequired
The range. Weeks start on Monday;
last_7_daysandnext_7_daysinclude today.- One of
"today","yesterday","tomorrow","this_week","last_week","next_week","this_month","last_month","last_7_days","last_30_days","next_7_days","next_30_days"
- One of
operator: "less_than"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"less_than"
- Always
valueone of string, number, FilterRelativeDaterequired
A number, a date, or a relative date.
Show 2 optionsHide 2 options
One of:
option 1one of string, number
A label or option ID for status and dropdown, a user ID for person, text (up to 200 characters), a number, or a date as
YYYY-MM-DDorYYYY-MM-DDTHH:MM:SS.sssZ.FilterRelativeDateFilterRelativeDate
A range of days worked out when the query runs, in
timeZone. Date columns only.ismeans inside it,is_notoutside it,greater_thanafter its end andless_thanbefore its start.Show 2 fieldsHide 2 fields
typestringrequired
- Always
"relative_date"
- Always
valuestringrequired
The range. Weeks start on Monday;
last_7_daysandnext_7_daysinclude today.- One of
"today","yesterday","tomorrow","this_week","last_week","next_week","this_month","last_month","last_7_days","last_30_days","next_7_days","next_30_days"
- One of
operator: "between"object
Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to test.
nameis the Name column.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
operatorstringrequired
- Always
"between"
- Always
valueobjectrequired
A range of numbers or dates. Both ends are inside it.
Show 2 fieldsHide 2 fields
fromone of string, numberrequired
The low end, inside the range.
toone of string, numberrequired
The high end, inside the range.
FilterGroupFilterGroup
A condition group inside a filter, with its own
join. It holds conditions only, not other condition groups.Show 2 fieldsHide 2 fields
joinstringrequired
How the entries combine:
andwhen all must match,orwhen any one is enough.- One of
"and","or"
- One of
conditionsarray of FilterConditionrequired
1 to 25 conditions.
- 1 to 25 items
sortSortoptional
The order. Left out or empty means creation order, or in the
groupslayout the items'positionin each group. In thegroupslayout a sort applies inside each group.- Up to 5 items
Show 2 fieldsHide 2 fields
columnstringrequired
The column ID to sort by.
nameis the Name column. A button column cannot be sorted.- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
directionstringrequired
ascfor ascending,descfor descending.- One of
"asc","desc"
- One of
groupGroupBy or nulloptional
Group by: puts the items in sections by one column's value. Left out or null means none. This is not the board's groups: for those, use the
groupslayout.Show 3 fieldsHide 3 fields
columnstringrequired
The column ID to group by. It must hold one value: not a button, not the Name column, and not a person or dropdown column that allows several.
- Pattern
^[a-z][a-z0-9_]{0,39}$
- Pattern
directionstringrequired
The order of the sections. The section of empty cells is always last.
- One of
"asc","desc"
- One of
showEmptybooleanoptional
True to list every label or option that no matching item has too, with a count of 0, in the column's order (reversed for
desc). For status and dropdown columns; other types ignore it. Left out means false. It adds sections to the counts only; the items are the same.
searchstring or nulloptional
One phrase, up to 200 characters, looked for in the item's name and its text, long text, link, phone and email values, ignoring ASCII case. Trimmed; left out, null or empty means no search.
- Up to 200 characters
archivedbooleanoptional
True for archived items instead of live ones. Left out means live items.
layoutstringoptional
How the items are laid out when there is no column grouping.
flat: the sort, then creation order.groups: the board's order, group by group in the order of the board'sgroups, and inside each group the sort, or the items'positionwhen there is no sort, then the ID. Left out meansflat, except for a view (seeview). A column grouping decides the sections andlayoutis ignored; archived items (archived: true) are always one flat list.- One of
"flat","groups"
- One of
groupIdsarray of stringoptional
Only the items of these board groups: 1 to 50 group IDs, each once. Left out means every group. An ID that names no live group of the board matches nothing. A list in which no ID is a live group answers 500
INTERNALtoday, a known bug, unless a filter, a search,archived: trueor thegroupslayout applies too; then it answers no items. It narrows the items only:countandgroupsstill cover every group.- 1 to 50 items
limitintegeroptional
Items per page, 1 to 1,000; 100 if left out. It may change between pages.
- 1 to 1,000
- Default
100
cursorstringoptional
The
nextCursorof the last page, passed back unread. It works only with the query it came from, and never expires. Up to 2,048 characters.- 1 to 2,048 characters
timeZonestringoptional
An IANA time zone name, such as
Europe/Berlin, for relative dates and the buckets of a Group by on a date column. Left out means UTC.- 1 to 64 characters
countsbooleanoptional
True to get
count, andgroupsandgroupsKindin a query with a column grouping or thegroupslayout. Counting can read the whole board.- Default
false
- Default
Filters
Conditions and condition groups
A filter has a join, and or or, and a list of conditions. A condition names a column, an operator and, for most operators, a value.
{
"filter": {
"join": "and",
"conditions": [
{ "column": "stage", "operator": "is", "value": "quoted" },
{ "column": "amount", "operator": "greater_than", "value": 2500 }
]
}
}An entry of conditions can also be a condition group: its own join and its own list of conditions. Condition groups go one level deep, so a condition group holds conditions only. This filter finds deals that are won, or quoted above 2,500:
{
"filter": {
"join": "or",
"conditions": [
{ "column": "stage", "operator": "is", "value": "won" },
{
"join": "and",
"conditions": [
{ "column": "stage", "operator": "is", "value": "quoted" },
{ "column": "amount", "operator": "greater_than", "value": 2500 }
]
}
]
}
}A filter with no conditions matches every item. Use name as the column ID to filter on the item's name.
Operators by column type
| Column type | Operators |
|---|---|
| Name, text, long text, link, phone, email | is, is_not, is_any_of, is_none_of, is_empty, is_not_empty, contains, does_not_contain |
| Number, date | is, is_not, is_any_of, is_none_of, is_empty, is_not_empty, greater_than, less_than, between |
| Status, dropdown, person | is, is_not, is_any_of, is_none_of, is_empty, is_not_empty |
| Button | None |
On a link column, the text operators read the URL.
Values
The operator decides the value's shape:
is,is_not,greater_thanandless_thantake one value.is_any_ofandis_none_oftake a list of at least one value.containsanddoes_not_containtake text of at least one character.betweentakes{"from": …, "to": …}. Both ends are inside the range.is_emptyandis_not_emptytake no value.
The column's type decides what a value is:
| Column type | Value |
|---|---|
| Name, text, long text, link, phone, email | Text |
| Number | A number |
| Date | A day as YYYY-MM-DD, a moment as YYYY-MM-DDTHH:MM:SS.sssZ, or a relative date |
| Status, dropdown | A label's or option's ID, not its name |
| Person | A user ID: userId in GET /v1/workspace/members |
How values match:
- Text matching ignores the case of ASCII letters,
isincluded:acmeisACME. - In a cell that holds several values (a dropdown or person column that allows several),
ismeans the cell includes the value, andis_any_ofthat it includes at least one.is_notandis_none_ofmean it includes none of them. - An empty cell matches
is_not,is_none_ofanddoes_not_contain: an empty cell is not X. is_emptyon a person column finds unassigned items.- A day tested against a date column that includes a time means that whole day, in the query's time zone.
- A moment tested against a date column without a time means the day the moment falls on, in the query's time zone.
- The query does not check that a label or a person exists. A value that names none is not refused; no cell holds it.
Relative dates
A date condition can use a range of days that is worked out when the query runs:
{ "column": "close_date", "operator": "is", "value": { "type": "relative_date", "value": "this_week" } }The ranges are today, yesterday, tomorrow, this_week, last_week, next_week, this_month, last_month, last_7_days, last_30_days, next_7_days and next_30_days. Weeks start on Monday. last_7_days ends today and next_7_days starts today; both include today.
A relative date is a range, not a day. is means inside it, is_not outside it, greater_than after its end and less_than before its start. between does not take relative dates. The range is worked out in the query's time zone.
Sorting
sort is a list of levels, each a column and a direction, asc or desc. The first level is the main key. Use up to 5 levels, each column once.
{ "sort": [{ "column": "close_date", "direction": "asc" }, { "column": "amount", "direction": "desc" }] }- With no sort, items come in creation order, oldest first. In the
groupslayout, they come bypositioninside each group. - The item ID always breaks ties, in the direction of the last level (ascending with no sort), so the order is complete and pages never overlap.
- Empty values come last, in both directions.
| Column type | Sorts by |
|---|---|
| Name, text, long text, link, phone, email | The text, ignoring the case of ASCII letters |
| Number | The number |
| Date | The day or the moment |
| Status | The label's place in the column's list, not its name |
| Dropdown | The place, in the column's list, of the first option in the cell |
| Person | The name of the first person in the cell |
| Button | Cannot be sorted |
The board's groups
A board's items are in its groups: named, colored sections, in the board's own order. Every item is in exactly one group. Its groupId names the group, and its position is its place there: a whole number, lowest first, that can be negative. Only the order of the numbers means anything. The board's groups, in order, come with GET /v1/boards/{boardId}/groups and in the board's own answer. To make, rename, order or delete groups, see Groups. To put an item in another group, move it.
The groups layout
layout says how the items come when the query has no Group by:
layout | Order |
|---|---|
flat, the default | Your sort, or creation order when there is no sort, as in Sorting. The groups play no part. |
groups | The board's order, as the app's table shows it: group by group, in the order of the board's groups. Inside each group, your sort, or position when there is no sort. The item ID breaks ties. |
- A filter and a search run across all groups. In the
groupslayout, a sort applies inside each group. - With a Group by, the Group by decides the sections and
layoutis ignored. - The archived list (
archived: true) is always flat. - The plain
GETof a board's items is always flat.
Reading some groups
groupIds reads only the items of the groups it names: 1 to 50 group IDs, each once. It works in both layouts, with a Group by, and in the archived list.
- An ID that is not a live group of the board matches nothing. It is not refused.
- A known bug: when no ID in the list is a live group, a query with no filter and no search answers 500
INTERNAL, unless it reads in thegroupslayout (a Group by turns that off) or the archived list. Send IDs of the board's live groups only. - It narrows the items only.
countandgroupsstill cover every group, so one request can read one group's items and every group's count. - In the archived list, an item whose group was deleted counts as in the board's first group.
This example uses the Moves board from the reference pages. It has two groups: Moves, its first, and Storage. Moves holds the Hendricks move and the two moves that the batch example added. Move an item put the Okafor move at the end of Storage. The query reads Storage's items in the board's order, with the counts of both groups:
curl -X POST https://api.melonforce.com/v1/boards/brd_8k2m4q7x1v9c3n5b6z0wp/items/query \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "layout": "groups", "groupIds": ["grp_5m8c2x7v4b1n9q3k6j0hd"], "counts": true }'{
"items": [
{
"id": "itm_xsvoz5vx75h21yin3lpkv",
"boardId": "brd_8k2m4q7x1v9c3n5b6z0wp",
"groupId": "grp_5m8c2x7v4b1n9q3k6j0hd",
"position": 1024,
"name": "Okafor, studio move",
"values": { "status": "k4m9q2xa", "move_date": "2026-12-09" },
"createdAt": "2026-11-18T15:02:41.044Z",
"createdBy": "apk_xghhfpw3ki1zdys219nfi",
"updatedAt": "2026-11-19T10:14:05.227Z",
"updatedBy": "apk_xghhfpw3ki1zdys219nfi",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "api_key"
}
],
"nextCursor": null,
"formerMembers": [],
"count": 4,
"groups": [
{ "key": "grp_8k2m4q7x1v9c3n5b6z0wp", "count": 3 },
{ "key": "grp_5m8c2x7v4b1n9q3k6j0hd", "count": 1 }
],
"groupsKind": "board",
"apiKeys": [{ "id": "apk_xghhfpw3ki1zdys219nfi", "name": "Booking sync", "revoked": false }]
}groupIds kept the items to Storage, but count and groups cover both groups, in the board's order. groupsKind is board, so each key is a group's ID.
Group by
group lays the items out in sections by one column's value, in a direction of its own. It is not the board's groups: those belong to the board, and every item is in one. A Group by only lays out the items of a query, and a view can save one.
{ "group": { "column": "stage", "direction": "asc" } }- Sections come in the order of a sort on that column, in that direction. The section of empty cells is always last.
- Inside a section, your
sortapplies. - Pages run through the sections in order, so the items of one section come together.
- Status and dropdown columns make a section for each label or option, in the column's order. A person column makes one for each person, in name order. Text sections ignore the case of ASCII letters, so
ACMEandacmeare one section. - A date column makes buckets, worked out in the query's time zone:
earlier,last_week,earlier_this_week,yesterday,today,tomorrow,later_this_week,next_weekandlater. Withdescthe list runs backwards.
showEmpty: true also lists, in the counts, each label or option that no matching item has, with a count of 0, in the column's order (backwards with desc). It works on status and dropdown columns; other types ignore it. It adds sections to the counts only: the items are the same. Left out, it is false.
{ "group": { "column": "stage", "direction": "asc", "showEmpty": true }, "counts": true }The Name column cannot be grouped, because every item would be its own section. Nor can a button column, or a dropdown or person column that allows several values. A Group by on one of these answers 400 GROUPING_NOT_ALLOWED.
Counts
Counting can mean reading the whole board, so counts come only when you send counts: true. Ask for them when you need them, for example on the first page.
countis the number of items that match on the whole board, not on the page.groupslists sections, each with akeyand acount. It comes with a Group by or with thegroupslayout, andgroupsKindsays which:column, for a Group by: each section that has at least one matching item, in the Group by's order, with the empty section last. WithshowEmpty, the labels or options that no item has are listed too, at 0.board, for thegroupslayout: every live group of the board, in the board's order, with 0 for a group that has no matching item.
- Without a Group by or the
groupslayout, onlycountcomes. groupIdsnarrows the items, notcountorgroups.
A section's key depends on what makes the sections:
| Sections by | Key |
|---|---|
| Status | The label's ID |
| Dropdown | The option's ID |
| Person | The user ID |
| Text, long text, link, phone, email | The text with ASCII letters in lower case (a link's URL) |
| Number | The number |
| Date | A bucket, such as today |
| Any column, for empty cells | null |
The board's groups (groupsKind board) | The group's ID |
To get counts without rows, send a small limit. See the example.
Search
search is one phrase. An item matches when its name, or the value of one of its text, long text, link, phone or email columns, contains the phrase, ignoring the case of ASCII letters. Status, dropdown and person names, numbers and dates are not searched; use a filter for those. The phrase is trimmed, and an empty one means no search.
Search works with a filter or a saved view: an item must match both.
Time zone
timeZone is an IANA name, such as Europe/Berlin or America/New_York. The query uses it for:
- relative dates, such as
todayandthis_week; - the buckets of a Group by on a date column;
- a day tested against a date column that includes a time;
- a moment tested against a date column without a time.
Without it, the query uses UTC. Send your users' time zone when you use any of these, or "today" will follow UTC's day.
Saved views
Send a view's ID in view to run the filter, sort and Group by that the view has saved. The board's views and their IDs come with GET /v1/boards/{boardId}.
- You can send
search,archived,layout,groupIds,limit,cursor,timeZoneandcountswith a view. - You cannot send
filter,sortorgroupwith a view: that answers 400INVALID_REQUEST. - With no
layout, a table view with no Group by runs in thegroupslayout, as the app's table shows it. Any other view, a Kanban or a view with a Group by, runsflat. - A view that no longer fits the board's columns still runs. A condition, sort level or Group by that names a deleted column, or no longer fits its column, is left out. So is a Group by on the Name column: Name cannot be grouped, but an older view can still hold one. A table view left with no Group by then runs in the
groupslayout. The view itself is not changed. - A query sent as fields is checked strictly instead: a part that does not fit answers 400
QUERY_INVALID. - A view ID that is not on the board answers 404
NOT_FOUND.
"Me" does not work with a key
A filter in the app can say "Me" in a person column: {"type": "me"}. It means the person looking at the view. An API key is not a person, so a query with Me answers 400 QUERY_INVALID. That includes a saved view whose filter holds Me. Filter by a person's user ID instead.
Paging with cursors
Each answer has nextCursor. To get the next page, send the same query again with cursor set to it. When nextCursor is null, you have every item.
A short page is not the end
Only a null nextCursor means the end. A page can be shorter than limit, or even empty, and still have a next page. Keep asking until nextCursor is null.
- A cursor is opaque text of up to 2,048 characters. Pass it back as it is; do not read or build one.
- A cursor works only with the query it came from: the same filter, sort, Group by, search,
layout,groupIds,archivedand time zone. For a saved view, that is the view as it was when the cursor was made. Anything else answers 400CURSOR_MISMATCH. Start again from the first page. - A relative date that moves every day (
today,yesterday,tomorrow,last_7_days,last_30_days,next_7_days,next_30_days), or a Group by on a date column, ties a cursor to the day it was made, in the query's time zone. A week or month range (this_week,last_monthand so on) ties it to that week or month. Yesterday's cursor fortodayanswersCURSOR_MISMATCH. limitis not part of the query, so you can change it between pages.- A cursor does not expire, and nothing is kept on the server.
- An item deleted or archived after the cursor was made does not stop the walk. A cursor that cannot be read answers 400
CURSOR_INVALID. Start again from the first page. - Most cursors hold the sort values of the item they name. A cursor for a sort or Group by on a person column does not, nor does one whose values are too long to keep. For those, the API reads the item again, and if it no longer exists at all, the cursor answers 400
CURSOR_INVALIDtoo. - An item that changes while you page can appear twice or be missed. To follow changes exactly, use the changes feed.
- In the
groupslayout, a group reordered, deleted or restored between two pages can make items appear twice or be missed. The cursor goes on from the group's place that it holds, and the walk does not fail for it. - Each request counts once against your rate limit, whatever its page size.
Errors
| Status | Code | When |
|---|---|---|
| 400 | INVALID_REQUEST | The body does not match its schema: an unknown field, a value over one of the limits, a column sorted twice, a view sent with filter, sort or group, a groupIds that is empty, names more than 50 groups, names one twice or holds a string that is not a group ID, or a time zone name that does not exist. No details. |
| 400 | QUERY_INVALID | The query does not fit the board: a column it lacks, an operator or value that does not fit the column, a column that cannot be sorted, or Me from a key. Or the query is too large to run. Details: issues. |
| 400 | GROUPING_NOT_ALLOWED | The Group by column cannot be grouped: Name, a button, or a dropdown or person column that allows several. Details: issues. |
| 400 | CURSOR_MISMATCH | The cursor came from a different query. |
| 400 | CURSOR_INVALID | The cursor cannot be read, or, for some cursors, its item no longer exists at all. See Paging with cursors. |
| 404 | NOT_FOUND | No such board, or no such view on it. |
| 413 | PAYLOAD_TOO_LARGE | The body is over 64 KB. |
All codes are on the errors page.
Reading QUERY_INVALID
details.issues has one entry for each problem. path says where it is in your query, as keys and list indexes from the top. code says what is wrong, and message is a short note for a person.
{
"error": {
"code": "QUERY_INVALID",
"details": {
"issues": [
{
"path": ["filter", "conditions", 1, "operator"],
"code": "operator_not_allowed",
"message": "This column does not support that operator."
}
]
}
}
}| Issue code | Meaning |
|---|---|
unknown_column | The board has no column with that ID. |
operator_not_allowed | The operator does not fit the column's type. |
value_not_allowed | The value does not fit the column's type, Me is not on a person column, Me came from a key, or the query is too large to run. |
not_sortable | The column cannot be sorted. |
not_groupable | The column cannot be used in a Group by. |
Read a code you do not know as "invalid".
A query too large to run
The API runs a query as database statements, and one statement can hold only so many values. A query within the limits can still need too many values for one statement, for example with many conditions on many different columns. It answers 400 QUERY_INVALID with one issue: an empty path, the code value_not_allowed, and the message "The query is too large. Use fewer conditions or columns." Send fewer conditions, or conditions on fewer columns.
Limits
| What | Limit |
|---|---|
| Page size | 100 by default, 1,000 at most |
| A cursor | 2,048 characters |
| Sort levels | 5 |
| Conditions in a filter, those in condition groups included | 25 |
| Condition groups in a filter | 5 |
Group IDs in groupIds | 50 |
Values in an is_any_of or is_none_of list | 25 |
| Text in a condition | 200 characters |
| Search text | 200 characters |
| Request body | 64 KB |
A query within these limits can still be too large to run.
Examples
Open deals for one person, closing this week
Deals owned by one person, not won or lost, with a close date this week in New York, soonest first. A deal with no stage counts as open, because an empty cell matches is_none_of.
curl -X POST https://api.melonforce.com/v1/boards/brd_bon9eqa7ghrajwyom13ul/items/query \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"join": "and",
"conditions": [
{ "column": "owner", "operator": "is", "value": "k7Rt2Vx9Lq4Mz8Pw1Nc6Hb3Jd5Fg0Sa" },
{ "column": "stage", "operator": "is_none_of", "value": ["won", "lost"] },
{ "column": "close_date", "operator": "is", "value": { "type": "relative_date", "value": "this_week" } }
]
},
"sort": [{ "column": "close_date", "direction": "asc" }],
"timeZone": "America/New_York"
}'{
"items": [
{
"id": "itm_351b7q8p6horasiedlz7r",
"boardId": "brd_bon9eqa7ghrajwyom13ul",
"groupId": "grp_bon9eqa7ghrajwyom13ul",
"position": 7168,
"name": "Acme renewal",
"values": {
"stage": "quoted",
"owner": ["k7Rt2Vx9Lq4Mz8Pw1Nc6Hb3Jd5Fg0Sa"],
"close_date": "2026-11-18",
"contact_email": "jordan@acme.example",
"amount": 4200
},
"createdAt": "2026-11-02T14:05:12.000Z",
"createdBy": "apk_6pif0678ucdpdgarns42x",
"updatedAt": "2026-11-16T09:41:57.000Z",
"updatedBy": "k7Rt2Vx9Lq4Mz8Pw1Nc6Hb3Jd5Fg0Sa",
"archivedAt": null,
"createdByType": "api_key",
"updatedByType": "member"
},
{
"id": "itm_cyx54uca4ap6tog4xg3nx",
"boardId": "brd_bon9eqa7ghrajwyom13ul",
"groupId": "grp_bon9eqa7ghrajwyom13ul",
"position": 18432,
"name": "Globex pilot",
"values": {
"owner": ["k7Rt2Vx9Lq4Mz8Pw1Nc6Hb3Jd5Fg0Sa"],
"close_date": "2026-11-20"
},
"createdAt": "2026-11-10T16:22:03.000Z",
"createdBy": "k7Rt2Vx9Lq4Mz8Pw1Nc6Hb3Jd5Fg0Sa",
"updatedAt": "2026-11-10T16:22:03.000Z",
"updatedBy": "k7Rt2Vx9Lq4Mz8Pw1Nc6Hb3Jd5Fg0Sa",
"archivedAt": null,
"createdByType": "member",
"updatedByType": "member"
}
],
"nextCursor": null,
"formerMembers": [],
"apiKeys": [{ "id": "apk_6pif0678ucdpdgarns42x", "name": "CRM sync", "revoked": false }]
}Search, page by page
Every deal whose name or text values contain "acme". The loop sends the same query with each nextCursor, stops only when it is null, and stops with the answer if it is an error. It needs jq.
cursor=null
while :; do
body=$(jq -n --argjson cursor "$cursor" '{ search: "acme" } + (if $cursor then { cursor: $cursor } else {} end)')
page=$(curl -s -X POST https://api.melonforce.com/v1/boards/brd_bon9eqa7ghrajwyom13ul/items/query \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d "$body")
echo "$page" | jq -e '.items' > /dev/null || { echo "$page" >&2; exit 1; } # an error answer
echo "$page" | jq -c '.items[]'
cursor=$(echo "$page" | jq '.nextCursor')
[ "$cursor" = "null" ] && break
doneThe second request's body looks like this. Its cursor is the first page's nextCursor, as it was given; the one here is only an example.
{
"search": "acme",
"cursor": "eyJ2IjoxLCJoIjoiSERTQlZtZmYiLCJwIjoxLCJpIjoiaXRtXzR3OGUycjZ0MHkzdTdpMW81cDlhcyIsImsiOlsxNzk0NDcxMzMwMDAwXX0"
}Count items by stage
Group by stage with counts: true and a limit of 1, to get the counts with as few rows as possible.
curl -X POST https://api.melonforce.com/v1/boards/brd_bon9eqa7ghrajwyom13ul/items/query \
-H "Authorization: Bearer $MELONFORCE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "group": { "column": "stage", "direction": "asc" }, "counts": true, "limit": 1 }'{
"items": [
{
"id": "itm_jvcmlgk06z6npxa8k1rgh",
"boardId": "brd_bon9eqa7ghrajwyom13ul",
"groupId": "grp_bon9eqa7ghrajwyom13ul",
"position": 43008,
"name": "Initech upgrade",
"values": { "stage": "new", "amount": 900 },
"createdAt": "2026-11-17T11:30:45.000Z",
"createdBy": "u3Ye8Bn1Qw5Ks9Dm2Xv7Gt4Lr6Pc0Hz",
"updatedAt": "2026-11-17T11:30:45.000Z",
"updatedBy": "u3Ye8Bn1Qw5Ks9Dm2Xv7Gt4Lr6Pc0Hz",
"archivedAt": null,
"createdByType": "member",
"updatedByType": "member"
}
],
"nextCursor": "eyJ2IjoxLCJoIjoiLXQ0UF9lTlIiLCJwIjoxLCJpIjoiaXRtXzlkM2Y3aDFrNW04cDJzNnYweDR6YiIsImsiOlswLDE3OTQ5MjA1MzgwMDBdfQ",
"formerMembers": [],
"count": 42,
"groups": [
{ "key": "new", "count": 12 },
{ "key": "quoted", "count": 9 },
{ "key": "won", "count": 15 },
{ "key": "lost", "count": 4 },
{ "key": null, "count": 2 }
],
"groupsKind": "column",
"apiKeys": []
}groupsKind is column, so each key is a stage's label ID. The sections follow the order of the column's labels, and the empty section, null, is last.