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 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 ”.
				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:

{
  "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):

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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.