import QsIntroFull from '/docs/snippets/qs-intro-full.md'
import QsForQueryBody from '/docs/snippets/qs-for-query-body.md'

REST API: Population & Field Selection#

Use the populate parameter to include relations, media fields, components, and dynamic zones in REST API responses. Use the fields parameter to return only specific fields.

The REST API by default does not populate any relations, media fields, components, or dynamic zones. Use the populate parameter to populate specific fields. Use the fields parameter to return only specific fields with the query results.

Field selection#

Queries can accept a fields parameter to select only some fields. By default, the REST API only returns the following types of fields:

string types: string, text, richtext, enumeration, email, password, and uid,
date types: date, time, datetime, and timestamp,
number types: integer, biginteger, float, and decimal,
generic types: boolean, array, and JSON.

Use case	Example parameter syntax
Select a single field	`fields=name`
Select multiple fields	`fields[0]=name&fields[1]=description`

curl 'http://localhost:1337/api/restaurants?fields[0]=name&fields[1]=description' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify(
  {
    fields: ['name', 'description'],
  },
  {
    encodeValuesOnly: true, // prettify URL
  }
);

await request(`/api/restaurants?${query}`);

{
  "data": [
    {
      "id": 4,
      "Name": "Pizzeria Arrivederci",
      "Description": [
        {
          "type": "paragraph",
          "children": [
            {
              "type": "text",
              "text": "Specialized in pizza, we invite you to rediscover our classics, such as 4 Formaggi or Calzone, and our original creations such as Do Luigi or Nduja."
            }
          ]
        }
      ],
      "documentId": "lr5wju2og49bf820kj9kz8c3"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 4
    }
  }
}

Population#

The REST API by default does not populate any type of fields, so it will not populate relations, media fields, components, or dynamic zones unless you pass a populate parameter to populate various field types. Populated relations always return full objects; the REST API currently cannot return just an array of IDs.

The find permission must be enabled for the content-types that are being populated. If a role does not have access to a content-type, the content-type will not be populated (see Users & Permissions for additional information on how to enable find permissions for content-types).

You can use the populate parameter alone or in combination with multiple operators for more control over the population.

populate=deep plugins are not recommended in Strapi.

The following table lists populate use cases with example syntax. Each row links to the Understanding populate guide for details:

Use case	Example parameter syntax	Detailed explanations to read
Populate everything, 1 level deep, including media fields, relations, components, and dynamic zones	`populate=*`	Populate all relations and fields, 1 level deep
Populate one relation, 1 level deep	`populate=a-relation-name`	Populate 1 level deep for specific relations
Populate several relations, 1 level deep	`populate[0]=relation-name&populate[1]=another-relation-name&populate[2]=yet-another-relation-name`	Populate 1 level deep for specific relations
Populate some relations, several levels deep	`populate[root-relation-name][populate][0]=nested-relation-name`	Populate several levels deep for specific relations
Populate a component	`populate[0]=component-name`	Populate components
Populate a component and one of its nested components	`populate[0]=component-name&populate[1]=component-name.nested-component-name`	Populate components
Populate a dynamic zone (only its first-level scalar fields)	`populate[0]=dynamic-zone-name`	Populate dynamic zones
Populate a dynamic zone, including component-specific fields, nested components, and relations	`populate[dynamic-zone-name][on][component-category.component-name][populate][relation-name][populate][0]=field-name`	Populate dynamic zones

Combining population with other operators#

You can combine the populate operator with other operators such as field selection, filters, and sort in the population queries.

Populate with field selection#

fields and populate can be combined.

curl 'http://localhost:1337/api/articles?fields[0]=title&fields[1]=slug&populate[headerImage][fields][0]=name&populate[headerImage][fields][1]=url' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify(
  {
    fields: ['title', 'slug'],
    populate: {
      headerImage: {
        fields: ['name', 'url'],
      },
    },
  },
  {
    encodeValuesOnly: true, // prettify URL
  }
);

await request(`/api/articles?${query}`);

{
  "data": [
    {
      "id": 1,
      "documentId": "h90lgohlzfpjf3bvan72mzll",
      "title": "Test Article",
      "slug": "test-article",
      "headerImage": {
        "id": 1,
        "documentId": "cf07g1dbusqr8mzmlbqvlegx",
        "name": "17520.jpg",
        "url": "/uploads/17520_73c601c014.jpg"
      }
    }
  ],
  "meta": {}
}

Populate with filtering#

filters and populate can be combined.

curl 'http://localhost:1337/api/articles?populate[categories][sort][0]=name%3Aasc&populate[categories][filters][name][$eq]=Cars' \
  -H 'Authorization: Bearer <token>'

const qs = require('qs');
const query = qs.stringify(
  {
    populate: {
      categories: {
        sort: ['name:asc'],
        filters: {
          name: {
            $eq: 'Cars',
          },
        },
      },
    },
  },
  {
    encodeValuesOnly: true, // prettify URL
  }
);

await request(`/api/articles?${query}`);

{
  "data": [
    {
      "id": 1,
      "documentId": "a1b2c3d4e5d6f7g8h9i0jkl",
      "title": "Test Article",
      "categories": {
        "data": [
          {
            "id": 2,
            "documentId": "jKd8djla9ndalk98hflj3",
            "name": "Cars"
          }
        ]
      }
    }
  ],
  "meta": {}
}

:::tip Performance tip
In production, always use explicit population instead of wildcards like populate=*. Limit population depth to 2-3 levels and consider centralizing population logic in route middlewares. See on the Strapi blog.
:::