> For the complete documentation index, see [llms.txt](https://docs.tiny.plus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiny.plus/api/concepts/listing.md).

# Listing, filtering and paging

`GET /v2/{type}` returns a page of records of one type, for example `GET /v2/projects`:

```json
{
    "total_records": 485,
    "returned_records": 15,
    "records": [
        { "id": "1343", "name": "10 Downing Street", ... },
        ...
    ]
}
```

`total_records` counts every record that matches, and `returned_records` counts the ones on this page.

## The shape of the response

| Parameter               | Description                                                                                                                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `return_format`         | `array` returns `records` as an array, in order. We recommend it. Without it, `records` is an object keyed by record id, and many JSON libraries lose the order.                    |
| `with_related`          | Default `1`. Each record's related records are returned in a `related` object, grouped by record type and keyed by id. Set it to `0` if you don't need them, for a faster response. |
| `related_return_format` | `array` makes each group in `related` an array.                                                                                                                                     |
| `fields`                | A comma-separated list of the fields to return, for example `fields=id,name,modified_date`.                                                                                         |
| `records_only`          | Returns the list of records without the totals around it.                                                                                                                           |
| `with_health`           | Adds a `health` object to each record, with its `rating` from 0 to 100 and the `reasons` behind it.                                                                                 |

{% hint style="warning" %}
Related records, teams and tags are only loaded when a page has 50 records or fewer. With a `limit` above 50, records come back without `related` or a team, and with empty `tags`. Even on smaller pages, a record with a very large number of links may not have all of them listed. To see every link a record has, get the record on its own with `with_related=1`.
{% endhint %}

## Paging and sorting

| Parameter | Description                                                                                                                                  |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `start`   | The offset of the first record to return. Default `0`.                                                                                       |
| `limit`   | How many records to return. Default `15`, maximum `1000` (`50` for posts). A higher `limit` is a `400` error. `limit=0` returns the maximum. |
| `sort`    | A field name, optionally followed by `asc` or `desc`, for example `sort=modified_date desc`.                                                 |

To read every record, keep adding `limit` to `start` until you've read `total_records`. Sort explicitly while you do, so the order can't change between pages. [Fair use](/api/concepts/fair-use.md) suggests a page size.

## Filtering

To filter a list, add any of the record type's fields as a query parameter. When you give several filters, a record must match all of them.

| Form                                     | Matches                                                                                                                                                                                                                                                                                    | Example                               |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
| `field=value`                            | Equal to the value.                                                                                                                                                                                                                                                                        | `record_status=active`                |
| `field=>value`                           | Greater than the value.                                                                                                                                                                                                                                                                    | `modified_date=>2026-01-01 00:00:00`  |
| `field=<value`                           | Less than the value.                                                                                                                                                                                                                                                                       | `project_value=<50000`                |
| `field=!value`                           | Not equal to the value. This also leaves out records where the field is blank.                                                                                                                                                                                                             | `record_status=!lost`                 |
| `field=a,b`                              | Any of the values. Only works on fields whose `field_type` is `id`, `staff`, `int`, `bit`, `percentage` or `fancy_select`, such as the `record_status` of projects, companies and contacts. On any other field, such as a task's `record_status`, the comma is taken as part of the value. | `record_status=proposal,won`          |
| `field=!a,b`                             | None of the values. Works on the same fields as `field=a,b`.                                                                                                                                                                                                                               | `record_status=!lost,cancelled`       |
| `field=from..to`                         | Between the two values, inclusive. Works on date fields. Either end may be left blank.                                                                                                                                                                                                     | `created_date=2026-01-01..2026-03-31` |
| `tags_{collection id}={tag id},{tag id}` | Tagged with any of these tags from the collection.                                                                                                                                                                                                                                         | `tags_12=31,32`                       |
| `custom_{field id}=value`                | A custom field equal to the value. Takes one value only.                                                                                                                                                                                                                                   | `custom_104=Sydney`                   |

URL-encode the values, especially `<` (`%3C`), `>` (`%3E`) and spaces. Date-time filters compare in UTC.

On a date-time field, a date on its own means midnight at the start of that day. So `modified_date=2026-09-01..2026-09-30` stops at the start of 30 September. To include the whole of the last day, end the range with the next day, or with a time such as `2026-09-30 23:59:59`. To find a field's `field_type`, and the ids of your custom fields and tags, see [Record types and your account's fields](/api/concepts/record-types.md).

{% hint style="warning" %}
A parameter that isn't a field of the record type is ignored without an error, so a misspelt filter returns every record. Check field names against `GET /v2/fields/{type}`.
{% endhint %}

A custom field filter must match the field's type. Custom fields of type text, link, yes/no, whole number, percentage, currency and date (`YYYY-MM-DD`) can be filtered. Anything else is a `400` error, as is a value the field can't hold.

### Records for one person

| Parameter         | Returns                                                                                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `me=1`            | Records whose team the token's user is on. On accounts where "assigned" means the assigned user only, records assigned to them. The parameter only has to be present, so `me=0` does the same. |
| `subscribed=1`    | Records the token's user is assigned to or subscribes to. `subscribed={team member id}` does the same for another team member.                                                                 |
| `staff={id},{id}` | Records with any of these team members on the team.                                                                                                                                            |

### Records linked to another record

| Parameter        | Returns                                                                                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `linked_to={id}` | Records linked to the record with that id, whichever of the two the link was made from. A list of tasks also includes the tasks whose `related_id` is that record. A value that isn't a record id is a `400` error. |

`GET /v2/activities?linked_to=62377&record_status=open` lists the open tasks linked to contact 62377, as the contact's Meetings & Tasks panel does. That includes tasks filed against the contact's company and linked to the contact, such as a [relationship plan](/api/endpoints/relationship-plans.md)'s follow-ups with that contact, which `related_id=62377` wouldn't find. [`/me`](/api/endpoints/me.md) lists `linked_to` in `api_features`.

## Searching

To find records by the words in their name, use `GET /v2/search/{type}?q={words}`. It returns a short summary of each match, and ignores filters. Always pass a `limit`: without one, it returns every match. [Search](/api/endpoints/records.md#search) has the details.