How to filter threads with query language

When using Comments and retrieving threads with our REST API, it’s possible to filter for specific threads using custom metadata and our custom query language. This enables the Get Threads REST API to have filtering that works the same as with useThreads and liveblocks.getThreads.

Query language

You can filter threads by their metadata, resolved status, or visibility, allowing you to select for certain properties, values, or even for string prefixes. Filters can be combined using AND logic.

// Resolved threadsresolved:true
// Threads with { status: 'open' } string metadatametadata['status']:'open'
// Threads with `{ org }` string metadata that starts with "liveblocks:"metadata['org']^'liveblocks:'
// Threads with { priority: 3 } number metadatametadata['priority']:3
// Threads with { pinned: false } boolean metadatametadata['pinned']:false
// Threads without a `color` propertymetadata['color']:null
// Private threadsvisibility:'private'
// Combine queries with ANDresolved:true AND metadata['priority']:3
// A more complex combinationmetadata['status']:'closed' AND metadata['org']^'liveblocks:'

How to use

To use the query language with the REST API pass your query string to the query parameter. For example, given this query:

metadata['status']:'open' AND metadata['priority']:3

Encode it, and add it to the query parameter:

https://api.liveblocks.io/v2/rooms/{roomId}/threads?query=metadata%5B'status'%5D%3A'open'%20AND%20metadata%5B'priority'%5D%3A3

To learn more on setting custom metadata on threads, make sure to read our guide.