# Common query parameters

WEEGLOO's list endpoints (GETs that return a collection, such as `GET /spaces/{spaceId}/contents`) accept common query parameters. With these parameters you limit how many items a page returns, set the sort criteria, fetch related resources alongside, select only the fields you need, narrow the list by conditions, and move to the next or previous page.

These parameters behave the same way regardless of resource kind. Each resource reference describes only the conditions specific to that resource and points to this page for the common parameters covered here.

## Parameters {#parameters}

| Parameter | Type | Description |
|---|---|---|
| `limit` | integer | Number of items to return per page. 1-100. Default 15. |
| `skip` | integer | Number of items to skip. Default 0. Use the cursor (`next`, `prev`) instead of `skip` for paging. See [Pagination (cursor)](#pagination-cursor) below. |
| `next` | string | Next page cursor. Obtained from `links.next` in the previous response. |
| `prev` | string | Previous page cursor. Obtained from `links.prev` in the previous response. |
| `order` | string | Sort criteria. Comma-separated for multi-level sorting (e.g. `sys.createdAt,sys.id`). Default `sys.createdAt,sys.id`. A field starting with `fields.` includes the locale (e.g. `fields.title.en-US`). |
| `include` | integer | The level to which related resources are expanded and fetched. 0=default, 1=related resources, 2=nested relations, 3=full. Default 0. |
| `select` | string | A comma-separated list of fields to include (e.g. `sys.id,sys.createdAt`) or to exclude (e.g. `-sys.id`) in the result. Do not mix include and exclude in one request. |
| `filter` | (condition) | Narrows the list by conditions. See [Filter](#filter) below for the format. |

The kinds of `sys` fields used in `order` and `select` are listed in [System properties (sys)](/api/reference/common/system-properties.md).

## Filter {#filter}

Filter conditions are not wrapped in `filter[]`; you send them directly as query parameters. The format is `{field}[{operator}]={value}`, and if you omit the operator it is interpreted as `eq`. For the full set of available operators, see [Operators](#operators) below.

```
{field}[{operator}]={value}
```

For example, to fetch only items whose `name` starts with `Tumbler`, send `name[prefix]=Tumbler`. The rules and caveats are as follows.

- **Do not wrap conditions in `filter[]`.** Wrapping as in `filter[name[prefix]]=Tumbler` does not work.
- **Multiple conditions are combined with AND.** Only items that satisfy all of them remain; OR search, where matching just one of several conditions is enough, is not supported. To match one of several values within a single field, use `in`.
- **A `fields.` condition includes the locale.** For example, `fields.file.ko-KR.mimeGroups=Image` keeps only image files in a *Media* list, and `sys.createdAt[gte]=2026-06-01T00:00:00Z` keeps only items created after that time.
- **Filtering or sorting a *Content* list by a `fields.` condition also requires the *Content Type*.** Send `sys.contentType.sys.id` together (flat `/contents` only); a bare `contentType=` does not substitute for it. See the [Content reference](/api/reference/cda/content.md#api) for details.

### Operators {#operators}

| Operator | Meaning | Value |
|---|---|---|
| `eq` | Equal. If you omit the operator, it is interpreted as this. | Single value |
| `ne` | Not equal | Single value |
| `in` | Equal to one of the listed values | List of values |
| `nin` | Not equal to any of the listed values | List of values |
| `all` | An array field contains all of the listed values | List of values |
| `exists` | Whether a value is present | `true` or `false` |
| `prefix` | Prefix match | Single value |
| `gt` / `gte` | Greater than / greater than or equal | Single value |
| `lt` / `lte` | Less than / less than or equal | Single value |
| `regex` | Regular expression match. **Advanced search only** (see [Advanced search](#advanced-search) below). | Regular expression |
| `near` | A Location field within a given distance of a point. **Advanced search only**. | `longitude,latitude,distance` (distance in kilometers) |
| `within` | A Location field inside a polygon. **Advanced search only**. | Three or more `longitude,latitude` coordinate pairs joined together |

RichText and Json fields are not searchable, so they cannot be used in filter conditions.

### Advanced search {#advanced-search}

The `regex`, `near`, and `within` operators and text full-text search work only in advanced search. You turn advanced search on by adding the header `X-Weegloo-Advanced-Search: true` to a list request, and the same header is returned in the response.

- **Full-text search**: When you use `eq` on a text field (LongText) that has full-text search enabled, it finds not only exactly matching values but also items that contain that value, through partial and fuzzy matching. If advanced search is not turned on, or if your plan does not provide advanced search, the same `eq` works as an exact match.
- **Location search**: `near` (radius) and `within` (polygon) apply only to Location fields and work only in advanced search.
- If you send `regex`, `near`, or `within` on a request that cannot use advanced search, they are not accepted.

## Pagination (cursor) {#pagination-cursor}

A list response body contains a `links` object, which holds `next` and `prev`. `links.next` is the full path to the next page.

```
/v1/spaces/tcq4V2Xb/contents?limit=15&next=<cursor>
```

There are two ways to fetch the next page. You can call the `links.next` path as is, or you can take the `next` cursor value out of `links.next` and pass it as the `next` parameter of your next request. If there is no `links.next`, it is the last page. You move to the previous page the same way with `links.prev`.

Do not increase `skip` to turn pages. If items are added or removed between list calls, the `skip` position shifts and items can be dropped or duplicated. The cursor (`next`, `prev`) does not have this problem.

The following is an example of a list response structure. The wrapper's `sys.type` is `TotalPageResponse`, `items` holds the array of items, and `links` holds the navigation paths.

```json
{
  "sys": { "type": "TotalPageResponse" },
  "limit": 15,
  "totalCount": 42,
  "items": [
    {
      "sys": {
        "id": "3trmXRM3RqbgSnifyg7PUl8DzDgDzP",
        "type": "Content",
        "space": { "sys": { "id": "tcq4V2Xb", "type": "Refer", "targetType": "Space" } },
        "createdAt": "2026-06-18T09:51:14.597Z",
        "updatedAt": "2026-06-18T09:51:44.128Z",
        "version": 2,
        "status": "Published"
      }
    }
  ],
  "links": {
    "self": "/v1/spaces/tcq4V2Xb/contents?limit=15",
    "next": "/v1/spaces/tcq4V2Xb/contents?limit=15&next=Q3Vyc29yVmFsdWU"
  }
}
```

`totalCount` is the total number of items that match the conditions, and `limit` is the page size applied to this response. `items` holds only the items belonging to that page.

## Related documents {#related-documents}

- [System properties (sys)](/api/reference/common/system-properties.md): The `sys` fields used in `order` and `select`.
- [Conventions](/api/reference/common/conventions.md): Media type, JSON Patch, and concurrency.