Filtering

Filter collection results using the where query parameter to retrieve only the documents that match your criteria.

Prerequisites:

A valid API key (see How to authenticate)
A resolved tenant context (see Understanding multi-tenancy)

Steps

1. Filter by a single field

Pass a where parameter with the field name, operator, and value. The query string format uses nested bracket notation.

curl -s -G \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  --data-urlencode 'where[title][equals]=La Traviata' \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events"

Result: Only events whose title exactly equals "La Traviata" are returned.

2. Use comparison operators

The API supports several operators for different types of comparison.

Operator	Description	Example
`equals`	Exact match	`where[title][equals]=Swan Lake`
`contains`	Substring match (case-insensitive)	`where[title][contains]=opera`
`greater_than`	Greater than	`where[startDate][greater_than]=2025-10-01T00:00:00.000Z`
`greater_than_equal`	Greater than or equal	`where[startDate][greater_than_equal]=2025-10-01T00:00:00.000Z`
`less_than`	Less than	`where[endDate][less_than]=2025-12-31T23:59:59.000Z`
`less_than_equal`	Less than or equal	`where[endDate][less_than_equal]=2025-12-31T23:59:59.000Z`

Date range example -- events starting in October 2025:

curl -s -G \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  --data-urlencode 'where[startDate][greater_than_equal]=2025-10-01T00:00:00.000Z' \
  --data-urlencode 'where[startDate][less_than]=2025-11-01T00:00:00.000Z' \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events"

Result: Only events with startDate in October 2025.

3. Combine conditions with AND

Use the and array to require all conditions to be true.

curl -s -G \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  --data-urlencode 'where[and][0][startDate][greater_than_equal]=2025-10-01T00:00:00.000Z' \
  --data-urlencode 'where[and][1][venue][equals]=6639a1c2f3b4a5d6e7f70001' \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events"

Result: Events starting from October 2025 AND at the specified venue.

4. Combine conditions with OR

Use the or array to match documents that satisfy at least one condition.

curl -s -G \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  --data-urlencode 'where[or][0][title][contains]=Traviata' \
  --data-urlencode 'where[or][1][title][contains]=Swan Lake' \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events"

Result: Events whose title contains either "Traviata" or "Swan Lake".

5. Filter by relationship field

Filter by a related document's ID. Relationship fields store the ID of the referenced document.

curl -s -G \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  --data-urlencode 'where[season][equals]=6639a1c2f3b4a5d6e7f60001' \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events"

Result: Events belonging to the specified season.

You never need to add a tenant filter to your where clause. The API automatically constrains every query to the resolved tenant, and your where conditions are merged with that constraint using an and combinator.

If your tenant belongs to a tenant group, reads of shared collections are constrained to the group rather than a single tenant. Because your conditions are and-combined with that constraint, you can add where[tenant][equals]=<member-id> to narrow a shared read to one member of the group.

URL encoding

When passing where as a query string, special characters must be URL-encoded. The --data-urlencode flag in curl handles this automatically. If you are constructing URLs manually (for example, in application code), ensure you encode the parameter values.

A where clause can also be passed as a JSON object in the query string:

curl -s -G \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  --data-urlencode 'where={"title":{"contains":"Traviata"}}' \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events"

Result

When complete, you will have:

Filtered collection results using field-level operators
Combined multiple conditions with and and or
Filtered by relationship fields

Verify: The totalDocs value in the response reflects the filtered count, not the total collection size.

Troubleshooting

Empty docs array with no error The filter matched no documents. Check the field name, operator, and value. Try removing conditions one at a time to isolate the issue.

"Server Error" when using where The where value may be malformed JSON. Ensure bracket notation is correct or that JSON is valid. Use --data-urlencode to avoid encoding issues.

How to sort and paginate -- ordering and paging through filtered results
Query parameters reference -- all operators and parameters
Collections overview -- available collections to filter