Querying: filters, fields & pagination

api_v3_list and api_v3_get reuse the same query semantics as API v3, surfaced as tool arguments. This page covers filtering, sparse fieldsets, pagination, and how related resources are returned.

Use api_v3_resource_schema to discover, per resource, which attributes are filterable and which operators each one accepts — it is the source of truth.

Standard filters

Every resource accepts these, regardless of type:

Filter	Type	Description
ids	string	Comma-separated list of IDs to fetch, e.g. "12,34,56".
updated_since	string	ISO 8601 timestamp; only records updated after this time. Useful for incremental sync — see the updated_since flow guide.
limit	integer	Page size (default 25, max 100).
offset	integer	Pagination offset (default 0).

These are passed as top-level arguments on api_v3_list, not inside filter.

Resource-specific filters

Some resources declare extra filters tailored to them. For example, bookings accepts:

Filter	Type	Description
rental_id	integer	Only bookings for this rental.
include_canceled	boolean	If true, include canceled bookings (default false).
status	string	Comma-separated: booked, unavailable, tentative.
from	string	Only bookings starting on/after this ISO 8601 date (default: now).
until	string	Only bookings starting on/before this ISO 8601 date.
checkin_from	string	Only bookings with check-in on/after this date.
checkout_until	string	Only bookings with checkout on/before this date.

Resource-specific filters are also passed as top-level arguments and are listed under resource_filters in the resource schema. Each resource defines its own set (or none).

Filtering

The filter argument on api_v3_list filters on a resource's attributes and relationships.

Exact-match equality

Pass a bare value to match it exactly:

{ "filter": { "currency": "EUR" } }

Comparison operators

Instead of a bare value, pass an object { "op": <operator>, "value": <value> }:

{ "filter": { "final_price": { "op": "gt", "value": 1000 } } }

Combining conditions (ranges)

Pass an array of operator objects to AND them together — e.g. a range:

{ "filter": { "final_price": [ { "op": "gteq", "value": 600 }, { "op": "lt", "value": 800 } ] } }

Available operators

The operators an attribute accepts depend on its type. The resource schema lists them per attribute; the common sets are:

Column type	Operators
numeric / date / datetime	eq, not_eq, gt, gteq, lt, lteq
string / text	eq, in, not_eq, matches, does_not_match
boolean	eq, not_eq

matches / does_not_match perform a case-insensitive substring match.

Filtering an unsupported attribute or operator returns an error

If you filter on an attribute that isn't filterable, or use an operator the attribute doesn't accept, the server returns an Invalid params error that lists the valid options. Check api_v3_resource_schema first.

Filtering by relationships

You can filter by a belongs_to relationship's foreign key, using either the <relationship>_id key or the bare <relationship> key:

{ "filter": { "rental_id": 42 } }

Polymorphic relationships require the companion <relationship>_type key alongside <relationship>_id:

{ "filter": { "created_by_id": 1, "created_by_type": "User" } }

The resource schema's relationships[].filter block tells you the exact keys, type, operators, and any required companion key for each relationship.

Sparse fieldsets

Use the fields argument (on both api_v3_list and api_v3_get) to return only a subset of attributes per record. This reduces payload size — helpful for keeping an agent's context small.

{ "fields": ["start_at", "end_at", "final_price"] }

• The record id is always included, even if you don't list it.
• Relationship links are preserved, so records stay traversable.
• Requesting an attribute that doesn't exist returns an Invalid params error listing the valid attributes.

This mirrors JSON:API-style sparse fieldsets. The set of selectable attributes for a resource is exactly its attributes list in api_v3_resource_schema.

Pagination

api_v3_list is offset-based:

• limit — page size, default 25, capped at 100. Values below 1 are clamped to 1; values above 100 are clamped to 100.
• offset — number of records to skip, default 0.
• Records are ordered by id ascending.

Every list response includes a meta object with the total count so you can page through results:

{
  "bookings": [ /* … */ ],
  "meta": { "total_count": 248, "limit": 25, "offset": 50 }
}

To fetch the next page, add limit to offset (e.g. offset: 75) until offset + limit >= total_count.

Custom sorting isn't exposed over MCP

List results are always ordered by id. If you need a different sort order, use the API v3 REST endpoints directly.

Related resources

Relationships are returned the way the API v3 serializer returns them — relationship links are included in each record (and preserved even when you use sparse fieldsets). To pull the related records themselves, follow the relationship with a second tool call, e.g. take a booking's rental_id and call api_v3_get with resource: "rentals", or filter a list by the foreign key as shown in Filtering by relationships.