Listing, filtering and paging

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

{
    "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.

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.

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

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

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's follow-ups with that contact, which related_id=62377 wouldn't find. /me 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 has the details.