Directus icon

Directus

Consume Directus API

Actions100

Overview

The Directus node for n8n, when configured with the Resource: Item and Operation: List, allows you to retrieve a list of items from a specified collection in your Directus instance. This operation is highly flexible, supporting advanced querying, filtering, aggregation, field selection, sorting, pagination, and exporting results in various formats (JSON, CSV, XML).

Common scenarios:

  • Fetching all records from a specific collection (e.g., articles, users).
  • Applying filters or search queries to retrieve only relevant items.
  • Exporting data for reporting or backup purposes.
  • Aggregating data (e.g., count, sum, average) or grouping by certain fields.
  • Integrating Directus data into other workflows or automations.

Practical examples:

  • Retrieve all published blog posts and export them as a CSV file.
  • Get a paginated list of users who registered after a certain date.
  • Aggregate sales data by month and output each group as a separate item.

Properties

Name Type Meaning
Collection options Unique name of the parent collection from which to list items. Required.
Return All boolean If true, returns all results; if false, limits the number of returned items according to the "Limit" property. Required.
Limit number Maximum number of objects to return (only shown if "Return All" is false). Must be between 1 and 100. Required.
Split Into Items boolean If true, outputs each element of the result array as its own n8n item. If false, outputs the entire array as a single item. Required.
JSON/RAW Parameters boolean If true, allows setting query parameters via a raw JSON object instead of the UI fields.
Query Parameters json Custom query parameters as a flat JSON object (shown if "JSON/RAW Parameters" is true).
Additional Fields collection Advanced options for the request (shown if "JSON/RAW Parameters" is false):
- Aggregate
- Binary Property for Export Data
- Deep (JSON)
- Export
- Fields
- File Name for Export Data
- Filter (JSON)
- Group By
- Meta
- Offset
- Search
- Sort
Aggregate fixedCollection Define aggregation functions (count, sum, avg, min, max, etc.) to apply on fields.
Binary Property for Export Data string Name of the binary property to store exported file data (used with Export).
Deep (JSON) json Set nested relational dataset query parameters.
Export options Export API response to a file (json, csv, xml).
Fields string Specify which fields to return in the response.
File Name for Export Data string File name for exported data (without extension).
Filter (JSON) json Filter items by given conditions (as JSON).
Group By string Group results by one or more fields (e.g., author, year).
Meta string Specify what metadata to include in the response.
Offset number Number of items to skip (for pagination).
Search string Search query to filter items containing the given text in any field.
Sort string Sorting order for returned items (CSV of fields, use minus sign for descending, question mark for random).

Output

  • If "Split Into Items" is true:
    Each item from the collection is output as a separate n8n item, with its data in the json property.

  • If "Export" is set (csv, json, xml):
    The exported file is attached as binary data under the specified binary property name (default: data). The json property will still contain the data (or metadata about the export).

  • If neither "Split Into Items" nor "Export" is used:
    The json property contains either:

    • An array of items (if multiple are returned), or
    • A single object (if only one item is returned).

Example output structure:

[
  {
    "json": {
      "id": 1,
      "title": "First Article",
      "author": "Alice"
      // ...other fields
    }
  },
  {
    "json": {
      "id": 2,
      "title": "Second Article",
      "author": "Bob"
      // ...other fields
    }
  }
]

If exporting:

[
  {
    "json": { /* summary or metadata */ },
    "binary": {
      "data": {
        "data": "<Buffer ...>",
        "fileName": "export.csv",
        "mimeType": "text/csv"
      }
    }
  }
]

Dependencies

  • Directus API: Requires access to a running Directus instance.
  • API Credentials: You must configure the directusApi credentials in n8n (typically an API token or user/password).
  • n8n Environment: No special environment variables required beyond standard n8n setup.

Troubleshooting

Common issues:

  • Invalid collection name: Ensure the "Collection" property matches an existing collection in Directus.
  • Authentication errors: Check that your API credentials are correct and have sufficient permissions.
  • Malformed JSON in filters or parameters: When using JSON fields (e.g., Filter, Deep, Query Parameters), ensure valid JSON syntax.
  • Export errors: If exporting, make sure the binary property name does not conflict with existing properties.

Error messages and resolutions:

  • "Cannot read property 'data' of undefined": Likely due to an incorrect API response or misconfigured parameters. Double-check your input values.
  • "Unexpected token ... in JSON": Indicates invalid JSON in one of the JSON input fields. Validate your JSON before submitting.
  • "Request failed with status code 401": Authentication issue. Recheck your Directus credentials.
  • "Collection not found": The specified collection does not exist. Verify the collection name.

Links and References

Discussion