Query Parameters

Most Directus API endpoints can use global query parameters to alter the data that is returned.

Fields

Specify which fields are returned. This parameter also supports dot notation to request nested relational fields, and wildcards (*) to include all fields at a specific depth.

{
  "fields": ["first_name", "last_name", { "avatar": ["description"] }]
}

GET /items/posts
    ?fields=first_name,last_name,avatar.description

Use native GraphQL queries.

Examples

Value	Description
`first_name,last_name`	Return only the `first_name` and `last_name` fields.
`title,author.name`	Return `title` and the related `author` item's `name` field.
`*`	Return all fields.
`.`	Return all fields and all immediately related fields.
`,images.`	Return all fields and all fields within the `images` relationship.

Wildcards and performance While wildcards are very useful, we recommend only requesting specific fields in production. By only requesting the fields you need, you can speed up the request, and reduce the overall output size.

Many to Any Fields

As Many to Any (M2A) fields have nested data from multiple collections, you are not always able to fetch the same field from every related collection. In M2A fields, you can use the following syntax to specify what fields to fetch from which related nested collection type: ?fields=m2a-field:collection-scope.field

Example
In an posts collection there is a Many to Any field called sections that points to headings, paragraphs, and videos. Different fields should be fetched from each related collection.

import { createDirectus, rest, readItems } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItems("posts", {
filter: {
  title: {
    _eq: "Hello",
  },
},
}),
);


GET /items/posts
?fields[]=title
&fields[]=sections.item:headings.title
&fields[]=sections.item:headings.level
&fields[]=sections.item:paragraphs.body
&fields[]=sections.item:videos.source

import { createDirectus, rest, readItems } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItems("posts", {
search: "Directus",
}),
);

GET /items/posts
?search=Directus

query {
posts(search: "Directus") {
id
}
}

What fields to sort results by. Sorting defaults to ascending, but appending a - will reverse this. Fields are prioritized by the order in the parameter. The dot notation is used to sort with values of related fields.

import { createDirectus, rest, readItems } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItems("posts", {
sort: ["sort", "-date_created", "author.name"],
}),
);

GET /items/posts
?sort=sort,-date_created,author.name

query {
posts(sort: ["sort", "-date_created", "author.name"]) {
id
}
}

Set the maximum number of items that will be returned. The default limit is set to 100. -1 will return all items.

import { createDirectus, rest, readItems } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItems("posts", {
limit: 50,
}),
);

GET /items/posts
?limit=50

query {
posts(limit: 50) {
id
}
}

Large limits and performance
Depending on the size of your collection, fetching the maximum amount of items may result in degraded performance or timeouts.The maximum number of items that can be requested on the API can be configured using the QUERY_LIMIT_MAX environment variable. This cannot be overridden by changing the value of limit.

import { createDirectus, rest, readItems } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItems("posts", {
offset: 100,
}),
);

GET /items/posts
?offset=100

query {
posts(offset: 100) {
id
}
}

An alternative to offset. Returned values are the value of limit multiplied by page. The first page is 1.

import { createDirectus, rest, readItems } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItems("posts", {
page: 2,
}),
);

GET /items/posts
?page=2

query {
posts(page: 2) {
id
}
}

Function	Description
`count`	Counts how many items there are
`countDistinct`	Counts how many unique items there are
`sum`	Adds together the values in the given field
`sumDistinct`	Adds together the unique values in the given field
`avg`	Get the average value of the given field
`avgDistinct`	Get the average value of the unique values in the given field
`min`	Return the lowest value in the field
`max`	Return the highest value in the field
`countAll`	Equivalent to `?aggregate[count]=*` (GraphQL only)

import { createDirectus, rest, aggregate } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
aggregate("posts", {
aggregate: { count: "*" },
}),
);

GET /items/posts
?aggregate[count]=*

query {
posts_aggregated {
countAll
}
}

import { createDirectus, rest, aggregate } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
aggregate("posts", {
aggregate: {
  count: ["views", "comments"],
},
groupBy: ["author", "year(publish_date)"],
}),
);

GET /items/posts
?aggregate[count]=views,comments
&groupBy[]=author
&groupBy[]=year(publish_date)

query {
posts_aggregated(groupBy: ["author", "year(publish_date)"]) {
group
count {
  views
  comments
}
}
}

import { createDirectus, rest, readItems } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItems("posts", {
deep: {
  translations: {
    _filter: {
      languages_code: {
        _eq: "en-US",
      },
    },
  },
},
}),
);

// There are two available syntax:

GET /items/posts
?deep[translations][_filter][languages_code][_eq]=en-US

GET /items/posts
?deep={ "translations": { "_filter": { "languages_code": { "_eq": "en-US" }}}}

# Natively supported by GraphQL.
query {
posts {
translations(filter: { languages_code: { code: { _eq: "en-US" } } }) {
  id
}
}
}

Example
Only get 3 related posts, with only the top rated comment nested:

{
"deep": {
"related_posts": {
  "_limit": 3,
  "comments": {
    "_sort": "rating",
    "_limit": 1
  }
}
}
}

import { createDirectus, rest, readItems } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com")
.with(staticToken())
.with(rest());

const result = await directus.request(
readItems("posts", {
alias: {
  all_translations: "translations",
  dutch_translations: "translations",
},
deep: {
  dutch_translations: {
    _filter: {
      code: {
        _eq: "nl-NL",
      },
    },
  },
},
}),
);

GET /items/posts
?alias[all_translations]=translations
&alias[dutch_translations]=translations
&deep[dutch_translations][_filter][code][_eq]=nl-NL

# Natively supported by GraphQL.
query {
posts {
dutch_translations: translations(filter: { code: { _eq: "nl-NL" } }) {
  id
}

all_translations: translations {
  id
}
}
}

Aliases in combination with other features
Aliases support being used in combination with:

functions, e.g. alias[release_year]=year(released)
in the deep query parameter, e.g. deep[author][_alias][birthyear]=year(birthday)

Note that it is not possible to use aliases on relational fields e.g. alias[author_name]=author.name and not possible to have . in the alias name itself e.g. alias[not.possible]=field.

Saves the API response to a file. Valid values are csv, json, xml, yaml.

?export=type

Reserved version keys The keys published and draft are reserved. Use published (or main for backward compatibility) to explicitly fetch the published base item. Use draft to fetch the global draft version.

import { createDirectus, rest, readItem } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItem("posts", {
version: "v1",
}),
);

?version=v1

query {
posts_by_id(id: 1, version: "v1") {
id
}
}

import { createDirectus, rest, readItem } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItem("posts", {
version: "v1",
versionRaw: true,
}),
);

GET /items/posts/1
?version=v1&versionRaw=true

query {
posts_by_version(id: 1, version: "v1") {
id
}
}

Functions accept a field and return a modified value. Functions can be used in any query parameter you'd normally supply a field key, including fields, aggregation, and filters.

The syntax for using a function is function(field).

Function	Description
`year`	Extract the year from a datetime/date/timestamp field
`month`	Extract the month from a datetime/date/timestamp field
`week`	Extract the week from a datetime/date/timestamp field
`day`	Extract the day from a datetime/date/timestamp field
`weekday`	Extract the weekday from a datetime/date/timestamp field
`hour`	Extract the hour from a datetime/time/timestamp field
`minute`	Extract the minute from a datetime/time/timestamp field
`second`	Extract the second from a datetime/time/timestamp field
`count`	Extract the number of items from a JSON array or relational field

import { createDirectus, rest, readItems } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItems("posts", {
filter: {
  "year(date_published)": {
    _eq: 1968,
  },
},
}),
);

GET /items/posts
?filter[year(date_published)][_eq]=1968

query {
posts(filter: { date_published_func: { year: { _eq: 1968 } } }) {
id
}
}

# Due to GraphQL name limitations, append `_func` at the end of the field name and use the function name as the nested field.

Extract a specific value from a JSON field and return it as a separate field in the response. See Using the json(field, path) function for full path syntax and examples.

This function cannot be used in filter. To filter on JSON values, use the _json filter operator instead.

When backlink is set to false, the API will exclude reverse relations during *.* wildcard field expansion to prevent circular references and reduce duplicate data in responses.

The backlink parameter defaults to true, so you need to explicitly set it to false to enable the filtering behavior.

Wildcard Only
The backlink parameter only affects *.* wildcard field expansion. Explicitly specified field names are not filtered. For example: fields=author.articles will still include the reverse relation even when backlink=false.

import { createDirectus, rest, readItems } from "@directus/sdk";
const directus = createDirectus("https://directus.example.com").with(rest());

const result = await directus.request(
readItems("posts", {
backlink: false,
}),
);

GET /items/posts
?fields=*.*.*
&backlink=false

Example
Red lines mark the response when backlink is set to true while green marks when backlinks is set to false. The articles collection consists of a many-to-one relation to Users called author and a many-to-many relation to Tags called tags.
GET /items/articles?fields=*.*.*&backlink=true / false

{
"data": [
{
  "id": 1,
  "title": "My first Article",
  "author": {
    "id": 2,
    "name": "Nils",
    "articles": [
      {         "id": 1,         "title": "My first Article",         "author": {           "id": 2,           "name": "Nils",           "articles": [1]         },         "tags": [           {             "id": 3,             "articles_id": 1,             "tags_id": 4          }         ]       }       1    ]
  },
  "tags": [
    {
      "id": 3,
      "articles_id": {         "id": 1,         "title": "My first Article",         "author": {           "id": 2,           "name": "Nils",           "articles": [1]         },          "tags": [           {             "id": 3,             "articles_id": 1,             "tags_id": 4          }         ]       },       "articles_id": 1,       "tags_id": {
        "id": 4,
        "tag": "Tag1",
        "articles": [
          {             "id": 3,             "articles_id": 1,             "tags_id": 4          }           3        ]
      }
    }
  ]
}
]
}

    # Use can use native GraphQL Union types.

    query {
        posts {
            sections {
                item {
                    ... on headings {
                        title
                        level
                    }
                    ... on paragraphs {
                        body
                    }
                    ... on videos {
                        source
                    }
                }
            }
        }
    }
    ```

    ```js [SDK]
    import { createDirectus, rest, readItems } from '@directus/sdk';
    const directus = createDirectus('https://directus.example.com').with(rest());

    const result = await directus.request(
        readItems('posts', {
            fields: [
                'title',
                {
                    sections: [
                        {
                            item: {
                                headings: ['title', 'level'],
                                paragraphs: ['body'],
                                videos: ['source'],
                            }
                        }
                    ]
                }
            ],
        })
    );
    ```
    ::

::

## Filter

Specify which items are returned based on the result of a [filter rule](/guides/connect/filter-rules).

::code-group

```http [REST]
// There are two available syntax:

GET /items/posts
?filter[title][_eq]=Hello

GET /items/posts
?filter={ "title": { "_eq": "Hello" }}

query {
posts(filter: { title: { _eq: "Hello" } }) {
id
}
}

# Attribute names in GraphQL cannot contain the `:` character. If you are filtering Many to Any fields, you will need to replace it with a double underscore.

Get once-a-month release notes & real‑world code tips...no fluff. 🐰

Filter Rules

Learn about filter rules in Directus - available operators, filter syntax, relational fields, dynamic variables, logical operators, and functions parameters. Understand how to build complex filters for permissions, validations, and automations.

Relational Data

Directus enables you to manage and interact with relational data. This section will guide you through the different types of relationships and how to work with them.

Fields

Many to Any Fields

Search

Sort

Limit

Offset

Page

Aggregate

GroupBy

Deep

Alias

Export

Version

VersionRaw

Functions

The JSON Function

Backlink