Developer · Guide
How to Query WordPress With WPGraphQL

Short answer
To query WordPress with WPGraphQL, install and activate the plugin, set permalinks to anything except Plain, then open the GraphiQL IDE. Ask for posts with a posts query naming the fields you want, or fetch one post with the post field and an idType such as SLUG or DATABASE_ID.
Key takeaways
- WPGraphQL is a free, open-source plugin that adds a GraphQL API to WordPress.
- The endpoint sits at /graphql unless permalinks are set to Plain.
- GraphiQL IDE lets you explore the schema and run queries from the dashboard.
- Ask for posts with nodes and name only the fields you need.
- A single post can be fetched by global ID, database ID, URI, or slug.
- Mutations follow WordPress access rules, so only users with the right role can change content.
What is WPGraphQL?
WPGraphQL is a free, open-source WordPress plugin that adds a GraphQL API to any WordPress site.
WPGraphQL states that it is a free, open-source WordPress plugin that provides an extendable GraphQL schema and API for any WordPress site (checked November 2026).
With it installed, a JavaScript front end can ask WordPress for exactly the data it needs in one request. The site stays the content store, while the front end can live anywhere.
GraphQL differs from the REST API in how a request is shaped. A REST call returns a fixed set of fields for a post, while a GraphQL query names the fields it wants and gets only those fields back.
The core REST route for posts is GET /wp/v2/posts. Developer.WordPress.org states that you can query that endpoint to retrieve a collection of posts (checked November 2026).
WPGraphQL states that with GraphQL, the client makes declarative queries, asking for the exact data needed, and exactly what was asked for is given in response (checked November 2026).
A guide on how to create a custom REST API endpoint in WordPress shows the REST side, so you can compare the two approaches.
What do you need before you start?
You need a WordPress site you can edit, admin access to install plugins, and a front end or client that can send HTTP requests.
WPGraphQL needs WordPress 6.0 or higher. WPGraphQL states that the minimum is WordPress 6.0, and that the plugin is actively tested against the latest WordPress version and one major version back (checked November 2026).
It also needs PHP 7.4 or higher. WPGraphQL states that the minimum is PHP 7.4 or higher, and that the latest stable PHP version is recommended (checked November 2026).
The plugin has more than 30,000 active installs. WordPress.org lists WPGraphQL with 30,000+ active installations (checked November 2026).
Work on a staging copy first when the site is live. A headless front end reads from the same content, so a schema change can affect it at once.
How do you install WPGraphQL?
Install it from the WordPress dashboard, activate it, and set permalinks to anything except Plain so the endpoint sits at /graphql.
WPGraphQL states that after install you will find a new menu item named GraphQL, and a GraphiQL IDE item in the top admin bar (checked November 2026).
Follow these steps:
- Log in to the WordPress dashboard.
- Open Plugins, then click Add New.
- Search for WPGraphQL.
- Click Install Now on the WPGraphQL plugin.
- Click Activate.
- Open Settings, then Permalinks, and pick any structure except Plain.
The permalink step matters. WPGraphQL states that WordPress defaults to the Plain permalink structure, which exposes GraphQL at /index.php?graphql, and that picking another setting exposes it at the /graphql endpoint (checked November 2026).
From the command line, the same install is one WP-CLI call: wp plugin install wp-graphql --activate.
A guide on how to create a custom post type in WordPress helps when your content types must appear in the schema too.
How do you write your first query in GraphiQL?
Open the GraphiQL IDE from the admin bar, paste a query in the left pane, and click Play to run it against your site.
WPGraphQL states that GraphiQL IDE is a tool that lets you explore your GraphQL schema and run GraphQL queries and mutations (checked November 2026).
Open it by clicking the GraphiQL IDE button in the WordPress admin bar. That takes you to the GraphiQL IDE page in the dashboard.
Paste this query to list posts with their titles:
query {
posts {
nodes {
id
title
}
}
}
WPGraphQL states that the query is sent to your site WPGraphQL API endpoint and returns results that match the data you asked for (checked November 2026).
Use the Docs button at the top right to explore the schema. WPGraphQL states that the Documentation Explorer shows the types and fields available in the WPGraphQL schema (checked November 2026).
Search the schema for posts to see every field a post can return. That list is the fastest way to learn what your site can answer.
How do you query a list of posts?
Query the posts field, ask for nodes, and name the fields you want on each post.
WPGraphQL states that WPGraphQL supports querying posts and pages, as well as custom post types that are registered to show in the GraphQL schema (checked November 2026).
A named query for recent posts looks like this:
query GetPosts {
posts {
nodes {
id
title
date
}
}
}
Name your operations, such as GetPosts, instead of using the short form. WPGraphQL states that named operations help with debugging, logging, code organization, and query reuse, and that they are required for variables (checked November 2026).
Add first to limit the count, and where to filter the list. This query returns the 10 most recent published posts:
query GetPublishedPosts {
posts(where: { status: PUBLISH }, first: 10) {
nodes {
id
title
date
}
}
}
You can also ask for related data in the same query. WPGraphQL states that GraphQL queries access many root resources and follow references between connected ones in a single request (checked November 2026).
A guide on how to create a WordPress plugin shows where server-side code for a custom schema field would live.
How do you query a single post?
Query the post field with an id and an idType that says how to read that ID.
WPGraphQL accepts four ways to name one post: a global ID, a database ID, a URI, or a slug. Pick the one your front end already has.
By database ID, with idType set to DATABASE_ID:
{
post(id: 333, idType: DATABASE_ID) {
id
databaseId
title
}
}
WPGraphQL states that in addition to passing a value for id, you declare the idType to be DATABASE_ID (checked November 2026).
By slug, with idType set to SLUG:
{
post(id: "hello-world", idType: SLUG) {
id
databaseId
title
uri
}
}
Slugs are safe only for post types where they are unique. WPGraphQL states that slugs are only unique identifiers for non-hierarchical post types, because two pages can share the same slug under different parents (checked November 2026).
By global ID, pass the base64 value as id with no idType. That value is the one the id field returns in a list query, so you can copy it straight from a list result.
| idType | What to pass | Best for |
|---|---|---|
| Global ID | Base64 ID from a list query | Links built from list results |
DATABASE_ID | Post ID number | Admin tools and imports |
SLUG | Post slug | Public URLs for posts |
URI | Full path to the post | Routing from a URL |
How do you filter and paginate results?
Filter with the where argument, paginate with first and after, and use variables so the same query can run with different values.
Filter by author with the author database ID:
{
posts(where: {author: 1}) {
nodes {
id
title
}
}
}
WPGraphQL states that queries for connections can be filtered with the where argument, and that there are many filter options to explore in GraphiQL (checked November 2026).
Filter sticky posts with isSticky. WPGraphQL states that you pass true to return only sticky posts, or false to exclude them (checked November 2026).
For pagination, WPGraphQL uses the Relay connection shape. Ask for nodes for the simple case, or edges with a cursor when you need page markers.
A query with variables takes the values outside the query text:
query GetPost($id: ID!) {
post(id: $id) {
title
date
}
}
WPGraphQL states that variables are passed separately from the query, and that both are sent together when the request is made (checked November 2026).
Send the request as a POST to /graphql with a JSON body. WPGraphQL states that the request uses fetch('/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json' } }) with the query and variables in the body (checked November 2026).
Learn WordPress states that the WordPress REST API provides a uniform interface for interacting with the data in a WordPress site (checked November 2026).
How do you expose custom post types and fields?
Register a custom post type with show_in_graphql set to true, and give it singular and plural GraphQL names.
WPGraphQL states that custom post types must be registered to show in the GraphQL schema before they can be queried (checked November 2026).
A registration for a press release type looks like this:
register_post_type( 'press_release', array(
'public' => true,
'show_in_graphql' => true,
'graphql_single_name' => 'pressRelease',
'graphql_plural_name' => 'pressReleases',
) );
Without show_in_graphql, the post type stays out of the schema. Your front end will get an error when it asks for the type by name.
Custom fields need an extension to appear. The WPGraphQL for Advanced Custom Fields extension adds ACF field groups to the schema, so fields built in ACF can be queried like core fields.
Check the schema in GraphiQL after each change. If the type is missing, check that the post type is registered on init and that show_in_graphql is set.
A guide on how to fix the REST API error in Site Health helps when an API on the same site stops answering.
How do mutations and permissions work?
Mutations change data, and WPGraphQL only lets them run for users who have the right to make that change.
WPGraphQL states that WPGraphQL provides mutations for posts, pages, and custom post types that are configured to show in the GraphQL schema (checked November 2026).
A mutation to create a post needs a clientMutationId and a title:
mutation CREATE_POST {
createPost(input: {
clientMutationId: "CreatePost"
title: "New Post Title"
}) {
post {
id
title
date
}
}
}
WPGraphQL states that there are two required input fields to create a post, which are clientMutationId and title (checked November 2026).
Published content needs no login to read. Drafts, private posts, and mutations need an authenticated user with the right role.
WPGraphQL states that WPGraphQL follows core access control rights, so data can only be created, updated, or deleted by users with proper permission to do so (checked November 2026).
When a mutation fails, check the login first. WPGraphQL states that when the user running the mutation is not authenticated, or does not have proper rights, the post will not be created and an error will be returned (checked November 2026).
A guide on how to check a plugin for vulnerabilities covers how to review a plugin that opens a write path on your site.
What mistakes should you avoid?
Avoid Plain permalinks, asking for fields you do not need, and leaving draft content open to anonymous requests.
Plain permalinks hide the /graphql endpoint. Set permalinks to Post name or another non-Plain structure right after install, and re-check the endpoint after any permalink change.
Do not ask for every field on every post. A query that asks for content, excerpt, author, categories, tags, and featured image on 100 posts returns a large reply. Ask for the fields the page actually shows.
Do not expose a custom post type by accident. A post type with show_in_graphql set to true appears in the schema, so check that internal types stay hidden.
Do not send mutations without auth. A mutation that runs as an anonymous user will fail, and a token with too much power can change content you did not mean to change.
Do not cache a GraphQL reply forever. A cached reply can keep showing a post that was edited or deleted, so tie the cache life to the content it holds.
A guide on how to find slow plugins in WordPress helps when a slow query behind the schema is the real cause of a slow page.
How do you check that WPGraphQL works?
Check that the endpoint answers, that a list query returns posts, and that a single-post query returns the right post.
Open the /graphql path on your own site domain in a browser or a request tool and confirm it answers. Then run the GetPosts query in GraphiQL and confirm the titles match the posts on your site.
Run the single-post query with a slug you know, and confirm the title, date, and URI match the post in the dashboard.
If the endpoint returns a 404, check the permalink setting first. Plain permalinks expose GraphQL at /index.php?graphql instead of /graphql.
If a field is missing from the reply, check the schema in GraphiQL. A field that is not in the schema cannot be queried, and a custom post type that is not registered for GraphQL will not appear there.
If a mutation fails, check the login and the user role. An anonymous request cannot create a post, and a role without the publish right cannot publish one.
Frequently asked questions
Is WPGraphQL free to use?
Yes. WPGraphQL is a free, open-source plugin on WordPress.org, and the GraphQL API it adds costs nothing to use. Paid extensions exist for some integrations, such as WooCommerce, but the core plugin covers posts, pages, and custom post types.
When should I use WPGraphQL instead of the REST API?
Use the REST API when a simple HTTP call with a fixed set of fields is enough, such as fetching a list of posts. Use WPGraphQL when the front end needs only some fields, or when one request must pull posts plus their authors, categories, and images together.
Do visitors need to log in to read content through WPGraphQL?
No. Published content needs no login to read through WPGraphQL. Drafts, private posts, and mutations need an authenticated user with the right role, and WPGraphQL follows the same access rules as WordPress core.
Why does the /graphql endpoint return a 404 error?
Check the permalink setting first. Plain permalinks expose GraphQL at /index.php?graphql instead of /graphql. Pick any other permalink structure, save it, and try the /graphql endpoint again.
Can WPGraphQL query custom post types?
Yes. Register the post type with show_in_graphql set to true and give it singular and plural GraphQL names. Custom fields need an extension, such as WPGraphQL for Advanced Custom Fields, before they appear in the schema.
What is the difference between nodes and edges in a query?
Use nodes for the simple case, when you only need the list of posts. Use edges when you need the cursor for each item, such as for cursor-based pagination in a front end that loads more posts on demand.
Sources
- WPGraphQL WPGraphQL
- Quick Start WPGraphQL
- Posts and Pages WPGraphQL
- Querying with GraphQL WPGraphQL
- Compatibility Guide WPGraphQL
- WPGraphQL plugin WordPress.org
- Posts - REST API Handbook WordPress Developer Resources
- Using the WordPress REST API Learn WordPress
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


