GraphQL Playground

Send GraphQL queries and mutations to any endpoint with JSON variables and auth headers, and read the data and errors the server returns.

The interactive tool loads here when JavaScript runs.

About this tool

What is the GraphQL Playground?

The GraphQL Playground posts a query or mutation to a GraphQL endpoint you choose and shows the JSON the server returns. You write the operation in the Query Editor, put variables in the Variables tab as JSON, add headers such as Authorization in the Headers tab, and press Run.

It sends the standard GraphQL-over-HTTP request: a POST with a JSON body of query, variables and, when the document has more than one operation, an operationName. Results with data, errors or both are shown as they arrive, and you can copy or download them as JSON.

The request goes straight from your browser to the endpoint, so the endpoint has to allow CORS for this site. It is a lightweight runner, not a full IDE: there is no schema introspection or autocomplete, so keep the schema or the API docs open alongside it.

  • Runs real POST requests from your browser
  • JSON variables and custom headers with one-click formatting
  • Sends operationName automatically for multi-operation documents
  • Readable errors for non-JSON and network failures
  • Copy or download the result as JSON
Read the guide: GraphQL Schemas and Queries: Validation, Types and Query Cost

Updated

How to use the GraphQL Playground

  1. Enter the endpoint URL in GraphQL Endpoint, for example https://your-api.example.com/graphql.
  2. Write the operation in the Query Editor. Declare variables in the operation signature, such as query GetUser($id: ID!).
  3. Open the Variables tab and enter a JSON object with values for those variables. Use Format to tidy it.
  4. Open the Headers tab and add any auth headers as JSON, for example {"Authorization": "Bearer <token>"}.
  5. Press Run and read the Query Result panel. Copy or download the JSON when you need it elsewhere.

Worked examples

A query with variables

Input

query GetUsers($first: Int = 10) {
  users(first: $first) { edges { node { id name } } }
}
Variables: {"first": 5}

Output

POST body: {"query":"query GetUsers($first: Int = 10) {...}","variables":{"first":5}}

The value 5 overrides the default of 10 declared in the operation. Load Sample fills in this shape; point it at an endpoint that has a users connection to run it.

An endpoint that answers with an HTML error page

Input

Endpoint returns 404 with <!doctype html>...

Output

{"errors":[{"message":"HTTP 404 Not Found: the endpoint did not return JSON. Response starts with: <!doctype html>..."}]}

Instead of a cryptic "Unexpected token <" parse error, you see the status and the start of the response, which usually reveals a wrong path or a login page.

Background and insight

GraphQL was built at Facebook in 2012 and published as an open specification in 2015. Since late 2018 it has been governed by the GraphQL Foundation, hosted by the Linux Foundation, and the current spec edition is October 2021. Over HTTP, almost every server accepts a POST with Content-Type: application/json and a body like {"query": "...", "variables": {...}}.

One thing surprises people coming from REST: a GraphQL server usually returns HTTP 200 even when the query fails validation or a resolver throws. The failure is in the "errors" array of the JSON body, sometimes alongside partial "data". So a green status code means the transport worked, not that your query did. Read the errors array first.

Variables are the other habit worth building. Inlining values into the query string makes each request a different document, which defeats server-side query caches and persisted queries, and invites injection bugs when strings are concatenated. Declare $variables in the operation and send their values separately.

Common use cases

  • Trying a public GraphQL API

    Run a query against GitHub, Shopify or another provider with your token in the Headers tab before writing client code.

  • Reproducing a client bug

    Paste the exact operation and variables from your app's network log and see the raw server response.

  • Testing mutations in staging

    Send a mutation with variables and check that the returned fields and errors match what the UI expects.

  • Checking auth and permissions

    Swap tokens in the Headers tab to see which fields come back null or as errors for each role.

Tips and limitations

  • If Run fails with a network error, the endpoint probably does not allow CORS from this site. Your server needs Access-Control-Allow-Origin and must allow the Content-Type and Authorization headers in its preflight.
  • HTTP 200 with an errors array is normal GraphQL behaviour. Check errors[].path to see which field failed.
  • Variables must be valid JSON: double-quoted keys and strings, no trailing commas, no comments.
  • When a document contains several operations, the first one is sent as operationName. Keep one operation per run to avoid surprises.
  • Validate the query's cost with the GraphQL Complexity Analyzer before running large nested queries against production.

Sources and further reading

  1. GraphQL Specification, October 2021 edition, GraphQL Foundation. The current edition of the language specification
  2. Serving over HTTP, GraphQL Foundation. POST requests with query and variables, and how responses report errors
  3. Queries, GraphQL Foundation. Operations, variables and operation names
  4. The Linux Foundation Announces Intent to Form New Foundation to Support GraphQL, Linux Foundation. The 2018 move from Facebook to the GraphQL Foundation

Frequently asked questions

Why does the GraphQL Playground show HTTP errors as "Failed to fetch"?

Failed to fetch means the browser could not complete the request, almost always because the endpoint does not allow cross-origin requests from this site. GraphQL POSTs with JSON bodies trigger a CORS preflight, so the server must answer OPTIONS with the right Access-Control headers.

How do I pass a bearer token to a GraphQL API?

Put it in the Headers tab as JSON: {"Authorization": "Bearer your-token"}. The headers are merged into the request after Content-Type, so you can also override Content-Type there if an API needs something unusual.

Why did my GraphQL query return 200 but no data?

GraphQL reports most failures inside the response body, not through the HTTP status. Look at the errors array: a validation error means the query does not match the schema, and a resolver error usually comes with a path showing which field failed.

Does this GraphQL client support subscriptions?

No. Subscriptions need a long-lived WebSocket or server-sent events connection, and this tool sends single HTTP POST requests. Queries and mutations work; for subscriptions use your server's own GraphiQL or a client library.

Is my GraphQL token stored anywhere?

No. The endpoint, query, variables and headers live in the page while it is open and are not saved to local storage or sent to RedBison. They do go to the endpoint you call, so only use tokens you trust that endpoint with.

Is there an in-depth guide to the GraphQL Playground?

Yes. “GraphQL Schemas and Queries: Validation, Types and Query Cost” covers the background, how it works, common pitfalls and worked examples. Read the full guide.