<!-- BusyBot node reference — https://busybot.net/tools/graphql/ -->

> Node: GraphQL (`graphql`) · Action · v1
> Category: Data & Storage · Credentials: Basic Auth (`httpBasicAuth`), Header Auth (`httpHeaderAuth`), Query Auth (`httpQueryAuth`)
> Updated: 2026-08-16

# GraphQL

> Execute GraphQL queries and mutations against any endpoint with configurable auth and response handling.

## Overview

A generic GraphQL client that sends queries and mutations to any GraphQL endpoint. It supports HTTP-level authentication (none, basic auth, header auth, query auth) — for OAuth2-protected endpoints, obtain a Bearer token from the auth provider and use Header Auth with `Authorization: Bearer <token>`. Both GET and POST are supported, along with JSON and raw GraphQL request formats, custom headers, and configurable response parsing (JSON or string).

Every parameter is evaluated per item, so each input item can target a different endpoint with a different query, variables and headers.

**Category:** Data & Storage  
**Tool Name:** `graphql`  
**Version:** 1

**Appearance:** Icon: `lucide-Braces` | Color: `#E10098`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Basic Auth**, **Header Auth**, **Query Auth** credentials.
See the [Credentials Guide](https://busybot.net/credentials/) for setup instructions.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Authentication | `options` | No | `none` | The authentication method to use. Select "None" for public GraphQL APIs. For OAuth2-protected endpoints, get a Bearer token from your auth provider and use Header Auth with name="Authorization" and value="Bearer <token>". |
| | | | | Options: `none`, `basicAuth`, `headerAuth`, `queryAuth` |
| HTTP Request Method | `options` | No | `POST` | The underlying HTTP method to use. POST is standard for GraphQL; GET is supported by some servers for queries. |
| | | | | Options: `GET`, `POST` |
| Endpoint | `string` | Yes | — | The GraphQL endpoint URL. Supports expressions like {{ $json.apiUrl }}. |
| Request Format | `options` | No | `json` | The request format for the query payload. JSON is recommended for best compatibility. _(shown when HTTP Request Method is `POST`)_ |
| | | | | Options: `json` (JSON object with query, variables and operationName properties — the standard and most widely supported format), `graphql` (raw GraphQL query string; not all servers support it) |
| Query | `string` | Yes | — | The GraphQL query or mutation string. Supports expressions. |
| Variables | `json` | No | — | Query variables as a JSON object. For example: {"userId": "123", "limit": 10} _(shown when Request Format is `json` and HTTP Request Method is `POST`)_ |
| Operation Name | `string` | No | — | Name of the operation to execute. Required when the query contains multiple named operations. _(shown when Request Format is `json` and HTTP Request Method is `POST`)_ |
| Response Format | `options` | No | `json` | How to parse the response data. JSON parses the response body; String returns the raw body. |
| | | | | Options: `json`, `string` |
| Response Data Property Name | `string` | Yes | `data` | The property name under which to store the raw response string. _(shown when Response Format is `string`)_ |
| Headers | `fixedCollection` | No | `{}` | Additional HTTP headers to send with the request. |
| — Name | `string` | No | — | Header name. |
| — Value | `string` | No | — | Header value. Supports expressions. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |
| Request Timeout (ms) | `number` | No | `60000` | Per-request timeout in milliseconds. |

## Output Data

One output item per input item. The GraphQL response replaces the item's JSON — the incoming fields do not pass through — while binary data on the input item is forwarded unchanged.

With **Response Format `json`** the parsed response body becomes the item JSON, so the payload sits under `data` exactly as the server returned it:

```json
{
  "data": {
    "user": {
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    }
  }
}
```

Reference the result downstream with expressions such as `{{ $json.data.user.name }}`.

With **Response Format `string`** the raw, unparsed response body is stored as a string under the property you name in Response Data Property Name (default `data`):

```json
{
  "data": "{\"data\":{\"user\":{\"name\":\"Ada Lovelace\"}}}"
}
```

If the server replies with a populated `errors` array, the item fails with a `GraphQL Error:` message listing those messages rather than emitting a successful item — so GraphQL-level failures are routed by your error mode just like transport failures. A response body that is not valid JSON also fails, with a message suggesting you switch Response Format to `string`.

## Usage Examples

- Query a GraphQL API to fetch user data
- Execute a GraphQL mutation to create a record
- Fetch data from a GraphQL endpoint with variables
- Query a GitHub GraphQL API with OAuth2 authentication
- Send a raw GraphQL query string to a custom server

## Example Configuration

A basic query with variables:

```json
{
  "type": "graphql",
  "parameters": {
    "endpoint": "https://api.example.com/graphql",
    "query": "query GetUser($id: ID!) { user(id: $id) { name email } }",
    "variables": "{ \"id\": \"{{ $json.userId }}\" }",
    "requestMethod": "POST",
    "requestFormat": "json",
    "responseFormat": "json"
  }
}
```

A mutation sent with an Authorization header:

```json
{
  "type": "graphql",
  "parameters": {
    "endpoint": "https://api.example.com/graphql",
    "query": "mutation CreateUser($input: UserInput!) { createUser(input: $input) { id name } }",
    "variables": "{ \"input\": { \"name\": \"{{ $json.name }}\", \"email\": \"{{ $json.email }}\" } }",
    "requestMethod": "POST",
    "requestFormat": "json",
    "responseFormat": "json",
    "headerParametersUi": {
      "parameter": [
        { "name": "Authorization", "value": "Bearer {{ $json.token }}" }
      ]
    }
  }
}
```

A public endpoint queried over GET:

```json
{
  "type": "graphql",
  "parameters": {
    "endpoint": "https://countries.trevorblades.com/",
    "query": "{ countries { code name } }",
    "authentication": "none",
    "requestMethod": "GET",
    "responseFormat": "json"
  }
}
```

Keeping the raw response body as a string:

```json
{
  "type": "graphql",
  "parameters": {
    "endpoint": "https://api.example.com/graphql",
    "query": "{ status }",
    "requestMethod": "POST",
    "requestFormat": "json",
    "responseFormat": "string",
    "dataPropertyName": "rawResponse"
  }
}
```

Selecting one of several named operations in a single query document:

```json
{
  "type": "graphql",
  "parameters": {
    "endpoint": "https://api.example.com/graphql",
    "query": "query GetUser($id: ID!) { user(id: $id) { name } } query GetPosts { posts { title } }",
    "operationName": "GetUser",
    "variables": "{ \"id\": \"{{ $json.userId }}\" }",
    "requestMethod": "POST",
    "requestFormat": "json",
    "responseFormat": "json"
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Sends GraphQL queries and mutations to any endpoint with configurable auth, variables, and response parsing.

- **POST is the safe default.** Request Format, Variables and Operation Name only apply to POST; with GET the query is appended to the URL as a `query` string parameter and variables cannot be sent.
- **Prefer the JSON request format.** Raw `graphql` bodies are not accepted by every server; JSON is the widely supported form.
- **Operation Name is only needed for multi-operation documents.** If your query text defines more than one named operation, name the one to run.
- **A `200 OK` can still be a failure.** GraphQL servers return errors inside the response body; this node surfaces them as item errors so they do not pass silently downstream.
- **Custom headers cover token auth.** For a Bearer token, add a `Authorization` header rather than picking one of the built-in authentication methods.
- **Endpoints must be reachable public URLs.** In production, plaintext `http:` endpoints are rejected unless the credential explicitly opts in.