Platform
Salesforce GraphQL API: when it beats REST and SOQL, and when it doesn't
The GraphQL API is a wrapper over SOQL that returns exactly the fields you ask for across related objects in one round trip. Here's where that earns its place, the pagination and aggregate limits that bite, and the jobs you should still give to REST, Composite, and Bulk.
Open the network tab on a Lightning record page. One screen, and it fires a handful of calls to paint itself: the account, then its contacts, then the open cases, then a picklist describe, each on its own request, each waiting on the last. The page is slow, and the org’s API meter is spun by a UI that asks four questions where one would do.
The Salesforce GraphQL API was built for exactly that. My rule: reach for it when a single surface needs several related objects in one round trip, and leave your bulk loads on Bulk API 2.0 and your transactional writes on Composite. GraphQL is a read-shaped tool. It fits that shape well and substitutes poorly for the others.
What the GraphQL API is
GraphQL on Salesforce is a single versioned endpoint, /services/data/v68.0/graphql, that accepts a POST with a query and optional variables. You send the exact shape of the data you want, including fields on parent and child records, and you get back that shape and nothing else. No over-fetching a full sObject to read three fields, no second call to walk a relationship.
Under the hood it is a wrapper over SOQL: your GraphQL query is translated to SOQL at runtime, executed, and the result mapped back. That one fact explains most of its behaviour. GraphQL inherits SOQL’s relationship model, its selectivity rules, and most of its limits. The API has been available since v56.0, and the capabilities below each landed in a specific version, so the version you call matters.
Reads go through the uiapi root, which also means the response carries record-level data the Lightning Data Service already understands: field values, display values, and the metadata a component needs to render. Mutations are supported too, so you can create and update records through the same endpoint. In practice the API’s centre of gravity is reads, and that is where I’d point it first.
Where it earns its place
The case for GraphQL is round trips. A classic record-detail screen needs an account, its contacts, and its open opportunities. Over REST that is three requests at best, and if you query children per parent it degrades into the N+1 pattern that makes list views crawl. In GraphQL it is one request:
query AccountScreen($id: ID) {
uiapi {
query {
Account(where: { Id: { eq: $id } }) {
edges {
node {
Name { value }
Industry { value }
Contacts {
edges {
node {
LastName { value }
Email { value }
}
}
}
Opportunities(where: { IsClosed: { eq: false } }) {
edges {
node {
Name { value }
Amount { value displayValue }
}
}
}
}
}
}
}
}
}
One call paints the whole screen, filtered server-side, with the related children nested where the component needs them. The value and displayValue split is deliberate: you get the raw value for logic and the formatted value for display without computing it yourself.
Inside a Lightning web component you rarely hand-roll the HTTP call. The lightning/graphql module is the recommended adapter as of Winter ‘26; the older lightning/uiGraphQLApi has been GA since Winter ‘24. Both are @wire read paths with the same client-side caching as Lightning Data Service, so a record fetched by one component is served from cache to the next. If you are weighing that against imperative Apex, I wrote up the trade-off in wire service versus imperative Apex; GraphQL slots in where @wire belongs and the read spans more than one object.
Paging is cursor-based, with a wall at 4,000
GraphQL does not page by offset. It pages by cursor. You ask for the first N edges, read the pageInfo for endCursor and hasNextPage, and pass that cursor back as after to get the next slice. The default page is small, so you set first explicitly.
The limit that surprises people: with ordinary pagination you can walk up to 4,000 records total for a given connection, then the cursor stops. That is fine for a UI, where nobody scrolls 4,000 rows, and a problem the moment someone points GraphQL at a data-extract job. From v60.0 there is upper-bound pagination that lifts the ceiling for deeper reads, but if you find yourself reaching for it, ask whether the job belongs in Bulk API 2.0 instead. Cursor paging a UI and extracting a table are different jobs, and GraphQL is built for the first.
Aggregates exist, within SOQL’s rules
You can group and aggregate in GraphQL, and the feature grew up version by version. groupBy arrived in v58.0 and behaves like SOQL GROUP BY; orderBy for aggregate results arrived in v59.0. There are ROLLUP and CUBE variants for subtotals, with ROLLUP taking up to three fields.
The catch is the same catch SOQL has, because it is SOQL. To order by an aggregate you must group on it. Currency handling and the usual aggregate restrictions carry over unchanged. None of this makes GraphQL an analytics engine. If you need real cross-object analytics, that is a job for CRM Analytics or Tableau, not a wrapper that compiles to a GROUP BY.
The limits that decide the design
A few numbers set the boundary of what a single GraphQL query can do, and they are worth knowing before you design around it.
- A query can include up to 10 subqueries, each returning up to 2,000 records. That caps how wide one call goes.
- Child-to-parent traversal runs up to five levels, the same depth SOQL allows.
- Because it compiles to SOQL, a non-selective filter is non-selective here too. A
wherethat would make SOQL scan the whole object does not get faster because you asked in GraphQL. The selective-query discipline applies unchanged. - GraphQL requests count against your org’s daily API allowance like any other REST call. The API does not move work onto a cheaper meter the way Bulk or Platform Events do.
Read those together and the boundary is clear. One GraphQL call can efficiently assemble a bounded, related set of records for a screen or a sync unit. A bulk extract is beyond it, and was never the point.
What to give to something else
GraphQL is the wrong tool for three jobs that look tempting.
Large reads and extracts belong in Bulk API 2.0, where the meter is records, not calls, and a query job streams millions of rows without touching your API request allowance. Walking GraphQL cursors 4,000 rows at a time to export a table is work done in the wrong pattern.
Writes, especially dependent writes, belong in the Composite API. Creating an account and its contacts and an opportunity in one atomic unit is exactly what a composite request does, and it counts as one call. GraphQL mutations create one record at a time and give you none of that transaction boundary.
And analytics belongs in an analytics tool. A groupBy that compiles to SOQL is fine for a count on a dashboard tile, and no substitute for a semantic model.
If you are staring at an org burning its API allowance and trying to decide which of these to reach for, the budgeting view, which meter each channel spends and how to see where your calls go, is in Salesforce API limits, and the broader set of options is in our integration patterns guide.
What I’d do
If you are building Lightning components that read more than one object to render a view, default to the lightning/graphql adapter and collapse those round trips into one cached call. The page gets faster, the code gets shorter, and the API meter stops spinning on a UI.
If you are building an external integration, use GraphQL for the bounded, related reads a screen or a webhook handler needs, and route volume to Bulk and writes to Composite. The skill is not picking one API for everything. It is matching each unit of work to the channel built for its shape, and GraphQL’s shape is a tidy, nested, read-shaped request that used to cost you four calls.
Understanding the basics
What is the Salesforce GraphQL API used for?
The GraphQL API is a read-first endpoint at /services/data/vXX.0/graphql that returns exactly the fields you request across related records in a single round trip. Its main use is powering Lightning web components and external UIs that need an object and its related records without multiple REST calls, with client-side caching when you use the lightning/graphql wire adapter.
Is the Salesforce GraphQL API faster than REST?
For the right shape of request, yes, because it replaces several dependent round trips with one and returns only the fields you ask for. For a single flat record read it is no faster, where a plain REST call is simpler, and it does not speed up a non-selective query, because it compiles to the same SOQL underneath.
Can you create and update records with the GraphQL API?
Yes. The API supports mutations to create and update records through the same endpoint. Records are created one at a time, though, with no shared transaction boundary, so for dependent or atomic writes the Composite API is the better fit.
How many records can a GraphQL query return?
A single query can include up to 10 subqueries of up to 2,000 records each, and ordinary pagination walks up to 4,000 records per connection before the cursor stops. Upper-bound pagination, from API v60.0, raises that ceiling, but large extracts belong in Bulk API 2.0 rather than paged GraphQL reads.
Trying to work out which Salesforce API each part of your integration should use? Talk to us. Matching the channel to the work is what we do.