---
title: "JSON:API Query Builder"
date: "2025-10-29T07:45:23+00:00"
summary:
image:
type: "page"
url: "/acquia-source/jsonapi-query-builder"
id: "a0217b21-e42a-4502-8cb6-d5a12b0d1c8a"
---

Acquia Source provides the JSON:API Query Builder to reduce integration time and enhance your experience with JSON:API. It helps you to build JSON:API queries, preview well-formatted real-time responses, and generate code samples.

JSON:API Query Builder interface
--------------------------------

The following image illustrates the sections of the JSON:API Query Builder interface with labels:

![acquia-source_headless-query-builder-user-interface](https://acquia.widen.net/content/741330c1-c409-4f7e-b526-45815f81ba3b/web/9e9cc_acquia-source_headless-query-builder-user-interface.png?w=1072&itok=Tk1OihCj)

The following table describes the sections labelled in the preceding image:

Label

Description

A

The **Query Builder** tab to build JSON:API queries with fields, filters, and relationships.

B

The **Authentication** tab to access examples of authentication when accessing the API from external applications.

C

The **Examples** tab to access examples of JSON:API queries.

D

The **Entity Type** and **Bundle** dropdowns to select the entity type and bundle for a query.

For information about entity types and bundles, visit [Entity types](/acquia-source/entity-types "Entity types").

E

The **Page** and **Limit** fields to set the pagination parameters for a query.

F

The **Request History** section to check the history of requests.

G

*   The **Fields** tab to add fields to a query.
*   The **Filters** tab to add filters and filter groups to a query.
*   The **Includes** tab to add relationships to a query.
*   The **Sort** tab to add sort criteria  to a query.
*   The **</>** tab to copy the API code example.

H

The **Response** section to review and copy the response.

I

The **Execute Query** button for manual execution of a query.

J

The **Auto Execute** checkbox for automatic execution of a query.

After you select this checkbox and make any changes to your query, the response is immediately updated.

K

The **Request URL** section to copy the Request URL.

Building a JSON:API query
-------------------------

Use the following steps to build a JSON:API query:

1.  [Access your site](/node/69836#access-a-site).
2.  In the left sidebar, click **API** \> **JSON:API Query Builder**.
3.  Select the entity type and bundle for your query.
    
    The **Bundle** dropdown shows the bundles that belong to the selected entity type.
    
4.  Set the pagination parameters for your query:
    1.  In the **Page** field, set the offset value.
        
        This value specifies the number of pages to be skipped. This is useful when implementing pagination.
        
    2.  In the **Limit** field, set the page limit.
        
        This value specifies the maximum number of items to be returned in a single response. Setting a lower limit helps the server to respond faster.
        
5.  Add filters and filter groups to your query:
    1.  Click the **Filters** tab.
        
        This tab includes the **Add Filter** and **Filter Groups (AND/OR logic)** sections to add filters and filter groups respectively.
        
    2.  In the **Field** dropdown, select the required field.
        
        This dropdown shows the fields that belong to the selected entity type and bundle.
        
    3.  In the **Operator** dropdown, select the required operator.
    4.  In the **Value** field, enter an exact value.
        
        For example, `1` or `true`.
        
    5.  Click **Add Filter**.
        
        The filter is added to the Selected Filters section.
        
    6.  Continue to add more filters, as required.
    7.  In the **Group Name** field, enter a name for the filter group.
        
        This is an optional field. If you leave this field blank, a default name is used for the group.
        
    8.  In the **Logic** dropdown, select AND or OR, as required.
    9.  Click **Create Filter Group**.
        
        The filter group is added to the Selected Filters section.
        
    10.  Continue to add more filter groups, as required.
    11.  Continue to add more filters and add them to the required groups, as required.
6.  Add relationships to your query:
    
    1.  Click the **Includes** tab.
        
        This tab shows the relationships that belong to the selected entity type and bundle.
        
    2.  Click each of the relationships that you want to add to your query.
    
    For more information, visit [Adding relationships in a query](#adding-relationships).
    
7.  Add sort criteria to your query:
    1.  Click the **Sort** tab.
        
        This tab includes the **Add Sort Criterion** section.
        
    2.  In the **Field** dropdown, select the required field.
        
        This dropdown shows the fields that belong to the selected entity type and bundle.
        
    3.  In the **Direction** dropdown, select Ascending or Descending, as required.
    4.  Click **Add**.
        
        The criterion is added to the Selected Sort Criteria section.
        
    5.  Continue to add more sort criteria, as required.
8.  Copy the API code example:
    
    1.  Click the **</>** tab.
        
        This tab includes the **API Code Examples** section.
        
    2.  In the **Language** dropdown, select the required language.
    3.  Click **Copy Code**.
9.  Click **Copy URL** to copy the Request URL.
10.  Execute your query.
11.  In the **Response** section, review the response and click **Copy** to copy the response.

Selecting fields for a query
----------------------------

When creating a JSON:API query, you can restrict the fields included in the response by selecting specific fields. This reduces the payload size and improves performance.

Use the following steps to restrict the fields included in the response:

1.  [Start building a query.](#build-query)
2.  Navigate to the **Fields** tab.
    
    This tab shows the fields that belong to the selected entity type and bundle. For information about fields, visit [Fields](/acquia-source/fields "Fields").
    
3.  Click each of the fields that you want to add to your query.

Adding relationships in a query
-------------------------------

The following is an example of how to add relationships in a JSON:API query to fetch media images as part of the response:

1.  [Start building a query.](#build-query)
2.  In the **Entity Type** dropdown, select **media**.
3.  In the **Bundle** dropdown, select **image**.
4.  Click the **Includes** tab.
5.  In the **Includes (Relationships)** section, click **media\_image**.
    
    The media\_image relationship is added to the query in the **Request URL** section:
    
    ![acquia-source_include-relationships_request](https://acquia.widen.net/content/7b483d3c-9e01-4ce6-a6ca-13a186167cfe/web/d3073_acquia-source_include-relationships_request.png?w=720&itok=rLXNYmEv)
    
6.  Click **Execute Query**.
7.  In the **Response** section, expand the `included` node and its subnodes to verify that all media images of your site are included in the query:
    
    ![acquia-source_include-relationships_response](https://acquia.widen.net/content/bbab143d-e887-4660-b497-d3dca39609e1/web/53162_acquia-source_include-relationships_response.png?w=720&itok=jTGw9mL0)