Filtering
Narrow list results with query parameters.
List endpoints accept filter query parameters. Each endpoint documents the filters it supports in the API reference. Undocumented query parameters return 400.
Operators
Pass the field name for an exact match, or add an operator in brackets:
| Parameter | Returns objects whose field |
|---|---|
field=value | equals value |
field[neq]=value | does not equal value |
field[in]=a,b | equals any of the comma-separated values |
field[not_in]=a,b | equals none of the comma-separated values |
field[gt]=value | is greater than value (exclusive) |
field[gte]=value | is greater than or equal to value (inclusive) |
field[lt]=value | is less than value (exclusive) |
field[lte]=value | is less than or equal to value (inclusive) |
field[is_null]=true | is null |
field[not_null]=true | is not null |
Combining filters returns objects that match all of them:
curl "https://api.getmateo.com/v1/conversation-events?type[in]=conversation.closed,conversation.reopened&created_at[gte]=2026-01-01T00:00:00Z" \
--header "Authorization: Bearer <your_api_token>" \
--header "hellomateo-version: 2026-07-01"Send timestamps in RFC 3339 format, such as 2026-01-01T00:00:00Z or 2026-01-01T01:00:00+01:00.
Timestamp precision
hellomateo stores timestamps with microsecond precision, but the API returns and accepts them with millisecond precision. A timestamp in a response is the stored value cut off after the millisecond, so it can be up to one millisecond earlier than the stored value. Filters compare against the stored value.
When you pass a timestamp from a response back as a filter, the object it came from:
- is always included by
[gte]and always excluded by[lt]. - can still be included by
[gt]. - can be excluded by
[lte].
Do not use timestamp filters to fetch only objects you have not seen yet. Where an endpoint supports ending_before, pass the ID of the newest object you have processed instead. That returns exactly the objects that are newer than it. See Poll for new objects.