Skip to content
MelonforceAPI docs

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}/itemsPOST /v1/boards/{boardId}/items/query
What it returnsEvery live item, oldest firstThe items that match your query, in your order
What you can sendlimit and cursor in the URLA saved view, or a filter, sort, Group by and search, plus layout, groupIds, limit, cursor, timeZone, archived and counts, in a JSON body
CountsNoWith counts: true
ReferenceList itemsQuery 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.

view

stringoptional

A saved view's ID. It stands in for filter, sort and group, so they cannot be sent with it; search, archived, layout and groupIds can. With a view, layout left out is groups for a table view with no column grouping and flat otherwise. Parts of the view that no longer fit the board's columns are left out.

  • Pattern ^viw_[0-9a-z]{21}$
filter

Filter or nulloptional

Which items to include. Left out or null means all.

Show 2 fieldsHide 2 fields
join

stringrequired

How the entries combine: and when all must match, or when any one is enough.

  • One of "and", "or"
conditions

array of one of FilterCondition, FilterGrouprequired

Conditions and condition groups. A condition has column; a condition group has conditions. 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:

FilterCondition

FilterCondition

One test on one column: column, operator and, except for is_empty and is_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
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is"
value

FilterValuerequired

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 1

one 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-DD or YYYY-MM-DDTHH:MM:SS.sssZ.

FilterMe

FilterMe

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
type

stringrequired

  • Always "me"
FilterRelativeDate

FilterRelativeDate

A range of days worked out when the query runs, in timeZone. Date columns only. is means inside it, is_not outside it, greater_than after its end and less_than before its start.

Show 2 fieldsHide 2 fields
type

stringrequired

  • Always "relative_date"
value

stringrequired

The range. Weeks start on Monday; last_7_days and next_7_days include 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"
operator: "is_not"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is_not"
value

FilterValuerequired

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.

Same options as value above

operator: "is_any_of"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is_any_of"
value

array of FilterValuerequired

1 to 25 values, each as for is.

  • 1 to 25 items

Same options as value above

operator: "is_none_of"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is_none_of"
value

array of FilterValuerequired

1 to 25 values, each as for is.

  • 1 to 25 items

Same options as value above

operator: "is_empty"

object

Show 2 fieldsHide 2 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is_empty"
operator: "is_not_empty"

object

Show 2 fieldsHide 2 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "is_not_empty"
operator: "contains"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "contains"
value

stringrequired

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
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "does_not_contain"
value

stringrequired

Text to look for, 1 to 200 characters, ignoring ASCII case.

  • 1 to 200 characters
operator: "greater_than"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "greater_than"
value

one of string, number, FilterRelativeDaterequired

A number, a date, or a relative date.

Show 2 optionsHide 2 options

One of:

option 1

one 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-DD or YYYY-MM-DDTHH:MM:SS.sssZ.

FilterRelativeDate

FilterRelativeDate

A range of days worked out when the query runs, in timeZone. Date columns only. is means inside it, is_not outside it, greater_than after its end and less_than before its start.

Show 2 fieldsHide 2 fields
type

stringrequired

  • Always "relative_date"
value

stringrequired

The range. Weeks start on Monday; last_7_days and next_7_days include 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"
operator: "less_than"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "less_than"
value

one of string, number, FilterRelativeDaterequired

A number, a date, or a relative date.

Show 2 optionsHide 2 options

One of:

option 1

one 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-DD or YYYY-MM-DDTHH:MM:SS.sssZ.

FilterRelativeDate

FilterRelativeDate

A range of days worked out when the query runs, in timeZone. Date columns only. is means inside it, is_not outside it, greater_than after its end and less_than before its start.

Show 2 fieldsHide 2 fields
type

stringrequired

  • Always "relative_date"
value

stringrequired

The range. Weeks start on Monday; last_7_days and next_7_days include 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"
operator: "between"

object

Show 3 fieldsHide 3 fields
column

stringrequired

The column ID to test. name is the Name column.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
operator

stringrequired

  • Always "between"
value

objectrequired

A range of numbers or dates. Both ends are inside it.

Show 2 fieldsHide 2 fields
from

one of string, numberrequired

The low end, inside the range.

to

one of string, numberrequired

The high end, inside the range.

FilterGroup

FilterGroup

A condition group inside a filter, with its own join. It holds conditions only, not other condition groups.

Show 2 fieldsHide 2 fields
join

stringrequired

How the entries combine: and when all must match, or when any one is enough.

  • One of "and", "or"
conditions

array of FilterConditionrequired

1 to 25 conditions.

  • 1 to 25 items

Same options as FilterCondition above

sort

Sortoptional

The order. Left out or empty means creation order, or in the groups layout the items' position in each group. In the groups layout a sort applies inside each group.

  • Up to 5 items
Show 2 fieldsHide 2 fields
column

stringrequired

The column ID to sort by. name is the Name column. A button column cannot be sorted.

  • Pattern ^[a-z][a-z0-9_]{0,39}$
direction

stringrequired

asc for ascending, desc for descending.

  • One of "asc", "desc"
group

GroupBy 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 groups layout.

Show 3 fieldsHide 3 fields
column

stringrequired

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}$
direction

stringrequired

The order of the sections. The section of empty cells is always last.

  • One of "asc", "desc"
showEmpty

booleanoptional

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.

search

string 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
archived

booleanoptional

True for archived items instead of live ones. Left out means live items.

layout

stringoptional

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's groups, and inside each group the sort, or the items' position when there is no sort, then the ID. Left out means flat, except for a view (see view). A column grouping decides the sections and layout is ignored; archived items (archived: true) are always one flat list.

  • One of "flat", "groups"
groupIds

array 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 INTERNAL today, a known bug, unless a filter, a search, archived: true or the groups layout applies too; then it answers no items. It narrows the items only: count and groups still cover every group.

  • 1 to 50 items
limit

integeroptional

Items per page, 1 to 1,000; 100 if left out. It may change between pages.

  • 1 to 1,000
  • Default 100
cursor

stringoptional

The nextCursor of 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
timeZone

stringoptional

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
counts

booleanoptional

True to get count, and groups and groupsKind in a query with a column grouping or the groups layout. Counting can read the whole board.

  • Default false

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.

Two conditions joined by and
{
  "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:

A condition group inside an or
{
  "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 typeOperators
Name, text, long text, link, phone, emailis, is_not, is_any_of, is_none_of, is_empty, is_not_empty, contains, does_not_contain
Number, dateis, is_not, is_any_of, is_none_of, is_empty, is_not_empty, greater_than, less_than, between
Status, dropdown, personis, is_not, is_any_of, is_none_of, is_empty, is_not_empty
ButtonNone

On a link column, the text operators read the URL.

Values

The operator decides the value's shape:

  • is, is_not, greater_than and less_than take one value.
  • is_any_of and is_none_of take a list of at least one value.
  • contains and does_not_contain take text of at least one character.
  • between takes {"from": …, "to": …}. Both ends are inside the range.
  • is_empty and is_not_empty take no value.

The column's type decides what a value is:

Column typeValue
Name, text, long text, link, phone, emailText
NumberA number
DateA day as YYYY-MM-DD, a moment as YYYY-MM-DDTHH:MM:SS.sssZ, or a relative date
Status, dropdownA label's or option's ID, not its name
PersonA user ID: userId in GET /v1/workspace/members

How values match:

  • Text matching ignores the case of ASCII letters, is included: acme is ACME.
  • In a cell that holds several values (a dropdown or person column that allows several), is means the cell includes the value, and is_any_of that it includes at least one. is_not and is_none_of mean it includes none of them.
  • An empty cell matches is_not, is_none_of and does_not_contain: an empty cell is not X.
  • is_empty on 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:

A relative date
{ "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.

Two sort levels
{ "sort": [{ "column": "close_date", "direction": "asc" }, { "column": "amount", "direction": "desc" }] }
  • With no sort, items come in creation order, oldest first. In the groups layout, they come by position inside 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 typeSorts by
Name, text, long text, link, phone, emailThe text, ignoring the case of ASCII letters
NumberThe number
DateThe day or the moment
StatusThe label's place in the column's list, not its name
DropdownThe place, in the column's list, of the first option in the cell
PersonThe name of the first person in the cell
ButtonCannot 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:

layoutOrder
flat, the defaultYour sort, or creation order when there is no sort, as in Sorting. The groups play no part.
groupsThe 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 groups layout, a sort applies inside each group.
  • With a Group by, the Group by decides the sections and layout is ignored.
  • The archived list (archived: true) is always flat.
  • The plain GET of 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 the groups layout (a Group by turns that off) or the archived list. Send IDs of the board's live groups only.
  • It narrows the items only. count and groups still 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:

One group's items, in the board's order
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 }'
200 OK
{
  "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 by stage
{ "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 sort applies.
  • 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 ACME and acme are 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_week and later. With desc the 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 by stage, with the empty stages
{ "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.

  • count is the number of items that match on the whole board, not on the page.
  • groups lists sections, each with a key and a count. It comes with a Group by or with the groups layout, and groupsKind says 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. With showEmpty, the labels or options that no item has are listed too, at 0.
    • board, for the groups layout: 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 groups layout, only count comes.
  • groupIds narrows the items, not count or groups.

A section's key depends on what makes the sections:

Sections byKey
StatusThe label's ID
DropdownThe option's ID
PersonThe user ID
Text, long text, link, phone, emailThe text with ASCII letters in lower case (a link's URL)
NumberThe number
DateA bucket, such as today
Any column, for empty cellsnull
The board's groups (groupsKind board)The group's ID

To get counts without rows, send a small limit. See the example.

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 today and this_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, timeZone and counts with a view.
  • You cannot send filter, sort or group with a view: that answers 400 INVALID_REQUEST.
  • With no layout, a table view with no Group by runs in the groups layout, as the app's table shows it. Any other view, a Kanban or a view with a Group by, runs flat.
  • 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 groups layout. 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, archived and time zone. For a saved view, that is the view as it was when the cursor was made. Anything else answers 400 CURSOR_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_month and so on) ties it to that week or month. Yesterday's cursor for today answers CURSOR_MISMATCH.
  • limit is 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_INVALID too.
  • An item that changes while you page can appear twice or be missed. To follow changes exactly, use the changes feed.
  • In the groups layout, 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

StatusCodeWhen
400INVALID_REQUESTThe 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.
400QUERY_INVALIDThe 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.
400GROUPING_NOT_ALLOWEDThe Group by column cannot be grouped: Name, a button, or a dropdown or person column that allows several. Details: issues.
400CURSOR_MISMATCHThe cursor came from a different query.
400CURSOR_INVALIDThe cursor cannot be read, or, for some cursors, its item no longer exists at all. See Paging with cursors.
404NOT_FOUNDNo such board, or no such view on it.
413PAYLOAD_TOO_LARGEThe 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.

400 QUERY_INVALID
{
  "error": {
    "code": "QUERY_INVALID",
    "details": {
      "issues": [
        {
          "path": ["filter", "conditions", 1, "operator"],
          "code": "operator_not_allowed",
          "message": "This column does not support that operator."
        }
      ]
    }
  }
}
Issue codeMeaning
unknown_columnThe board has no column with that ID.
operator_not_allowedThe operator does not fit the column's type.
value_not_allowedThe 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_sortableThe column cannot be sorted.
not_groupableThe 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

WhatLimit
Page size100 by default, 1,000 at most
A cursor2,048 characters
Sort levels5
Conditions in a filter, those in condition groups included25
Condition groups in a filter5
Group IDs in groupIds50
Values in an is_any_of or is_none_of list25
Text in a condition200 characters
Search text200 characters
Request body64 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.

Open deals for one person, closing this week
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"
  }'
200 OK
{
  "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.

Search, page by page
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
done

The 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.

The second request's body
{
  "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.

Count items by stage
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 }'
200 OK
{
  "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.