Field selection

Reduce response size and improve performance by requesting only the fields you need using select, populate, and depth.

Prerequisites:

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

Steps

1. Select top-level fields

Pass the select parameter as a nested object with boolean values. Set a field to true to include it.

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

Result: Each document contains only id, title, slug, and startDate. The id field is always included regardless of selection.

{
  "docs": [
    {
      "id": "6639a1c2f3b4a5d6e7f90001",
      "title": "La Traviata",
      "slug": "la-traviata-autumn-2025",
      "startDate": "2025-10-15T18:30:00.000Z"
    }
  ],
  "totalDocs": 47,
  "limit": 10,
  "totalPages": 5,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": true,
  "prevPage": null,
  "nextPage": 2
}

2. Select nested fields

Use dot-bracket notation to select fields within nested objects.

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

Result: Each event includes title and the tessitura.performanceId and tessitura.availability fields.

3. Control relationship population with `populate`

The populate parameter controls which fields are included when related documents are expanded. This is particularly useful for the events endpoint, which populates several relationships by default.

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

Result: Each event includes title and a venue object containing only title and city from the venues collection.

{
  "docs": [
    {
      "id": "6639a1c2f3b4a5d6e7f90001",
      "title": "La Traviata",
      "venue": {
        "id": "6639a1c2f3b4a5d6e7f70001",
        "title": "Main Stage",
        "city": "London"
      }
    }
  ]
}

4. Control relationship depth

The depth parameter controls how many levels of relationship fields are populated. A depth of 0 returns only IDs for relationship fields.

curl -s \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-basker-tenant-slug: royal-opera-house" \
  "https://api.basker.app/partners/2026-02/royal-opera-house/events?depth=0&limit=1"

Result: Relationship fields contain only the referenced document's ID string, not the expanded object.

{
  "docs": [
    {
      "id": "6639a1c2f3b4a5d6e7f90001",
      "title": "La Traviata",
      "venue": "6639a1c2f3b4a5d6e7f70001",
      "season": "6639a1c2f3b4a5d6e7f60001"
    }
  ]
}

Depth	Behaviour
`0`	Relationship fields return IDs only
`1`	Relationship fields are populated one level deep
`2`	Nested relationships within populated documents are also expanded

Most collections return all fields by default. The events collection is an exception: it applies a curated default selection of approximately 30 fields and a default population configuration for 8 related collections. Providing your own select or populate parameter overrides these defaults entirely. See the Events reference for the full list.

Result

When complete, you will have:

Reduced response size by selecting only needed fields
Controlled relationship expansion with populate
Adjusted population depth with depth

Verify: The returned documents contain only the fields you requested plus id.

Troubleshooting

Fields are missing from the response If you provide a select parameter, only selected fields are returned. Ensure every field you need is set to true.

Relationships return IDs instead of objects The depth parameter may be set to 0, or the field was not included in populate. Increase depth or add the collection to populate.

Default fields appear even without select Some collections (notably events) apply a default selection when you do not provide the select parameter. This is by design -- it returns the most commonly needed fields. Pass your own select to override.

Events reference -- default select and populate configuration for events
How to filter results -- narrowing results
Query parameters reference -- all parameters with types and defaults