GraphQL API All tiers All offerings
GraphQL is a query language for APIs. You can use it to request the exact data you need, and therefore limit the number of requests you need.
GraphQL data is arranged in types, so your client can use client-side GraphQL libraries to consume the API and avoid manual parsing.
The GraphQL API is versionless.
Getting started
If you’re new to the GitLab GraphQL API, see Get started with GitLab GraphQL API.
You can view the available resources in the GraphQL API reference.
The GitLab GraphQL API endpoint is located at /api/graphql
.
Interactive GraphQL explorer
Explore the GraphQL API using the interactive GraphQL explorer, either:
- On GitLab.com.
- On your self-managed GitLab instance on
https://<your-gitlab-site.com>/-/graphql-explorer
.
For more information, see GraphiQL.
View GraphQL examples
You can work with sample queries that pull data from public projects on GitLab.com:
The get started page includes different methods to customize GraphQL queries.
Global IDs
In the GitLab GraphQL API, an id
field is nearly always a Global ID
and never a database primary key ID. A Global ID in the GitLab GraphQL API
begins with "gid://gitlab/"
. For example, "gid://gitlab/Issue/123"
.
Global IDs are a convention used for caching and fetching in some client-side libraries.
GitLab Global IDs are subject to change. If changed, the use of the old Global ID as an argument is deprecated and supported according to the deprecation and breaking change process. You should not expect that a cached Global ID will be valid beyond the time of a GitLab GraphQL deprecation cycle.
Available top-level queries
The top-level entry points for all queries are defined in the Query
type in the
GraphQL reference.
Multiplex queries
GitLab supports batching queries into a single request. For more information, see Multiplex.
Breaking changes
The GitLab GraphQL API is versionless and changes to the API are primarily backward-compatible.
However, GitLab sometimes changes the GraphQL API in a way that is not backward-compatible. These changes are considered breaking changes, and can include removing or renaming fields, arguments, or other parts of the schema. When creating a breaking change, GitLab follows a deprecation and removal process.
To avoid having a breaking change affect your integrations, you should:
- Familiarize yourself with the deprecation and removal process.
- Frequently verify your API calls against the future breaking-change schema.
For more information, see Deprecating GitLab features.
Breaking change exemptions
Schema items labeled as Experiments in the GraphQL API reference are exempt from the deprecation process. These items can be removed or changed at any time without notice.
Fields behind a feature flag and disabled by default do not follow the deprecation and removal process. These fields can be removed at any time without notice.
Verify against the future breaking-change schema
Introduced in GitLab 15.6.
You can make calls against the GraphQL API as if all deprecated items were already removed. This way, you can verify API calls ahead of a breaking-change release before the items are actually removed from the schema.
To make these calls, add a
remove_deprecated=true
query parameter to the GraphQL API endpoint. For example,
https://gitlab.com/api/graphql?remove_deprecated=true
for GraphQL on GitLab.com.
Deprecation and removal process
The deprecation and removal process for the GitLab GraphQL API aligns with the wider GitLab deprecation process.
Parts of the schema marked for removal from the GitLab GraphQL API are first
deprecated
but still available for at least six releases. They are then removed
entirely during the next XX.0
major release.
Items are marked as deprecated in:
- The schema.
- The GraphQL API reference.
- The deprecation feature removal schedule, which is linked from release posts.
- Introspection queries of the GraphQL API.
The deprecation message provides an alternative for the deprecated schema item, if applicable.
To avoid experiencing breaking changes, you should remove the deprecated schema from your GraphQL API calls as soon as possible. You should verify your API calls against the schema without the deprecated schema items.
Deprecation example
The following fields are deprecated in different minor releases, but both removed in GitLab 14.0:
Field deprecated in | Reason |
---|---|
12.7 | GitLab traditionally has 12 minor releases per major release. To ensure the field is available for 6 more releases, it is removed in the 14.0 major release (and not 13.0). |
13.6 | The removal in 14.0 allows for 6 months of availability. |
List of removed items
View the list of items removed in previous releases.
Limits
The following limits apply to the GitLab GraphQL API.
Limit | Default |
---|---|
Maximum page size | 100 records (nodes) per page. Applies to most connections in the API. Particular connections may have different max page size limits that are higher or lower. |
Maximum query complexity | 200 for unauthenticated requests and 250 for authenticated requests. |
Request timeout | 30 seconds. |
Maximum query size | 10,000 characters per query or mutation. If this limit is reached, use variables and fragments to reduce the query or mutation size. Remove white spaces as last resort. |
Maximum query complexity
The GitLab GraphQL API scores the complexity of a query. Generally, larger queries have a higher complexity score. This limit is designed to protecting the API from performing queries that could negatively impact its overall performance.
You can query the complexity score of a query and the limit for the request.
If a query exceeds the complexity limit, an error message response is returned.
In general, each field in a query adds 1
to the complexity score, although
this can be higher or lower for particular fields. Sometimes, adding
certain arguments may also increase the complexity of a query.
Resolve mutations detected as spam
GraphQL mutations can be detected as spam. If a mutation is detected as spam and:
-
A CAPTCHA service is not configured, a GraphQL top-level error is raised. For example:
{ "errors": [ { "message": "Request denied. Spam detected", "locations": [ { "line": 6, "column": 7 } ], "path": [ "updateSnippet" ], "extensions": { "spam": true } } ], "data": { "updateSnippet": { "snippet": null } } }
- A CAPTCHA service is configured, you receive a response with:
-
needsCaptchaResponse
set totrue
. - The
spamLogId
andcaptchaSiteKey
fields set.
For example:
{ "errors": [ { "message": "Request denied. Solve CAPTCHA challenge and retry", "locations": [ { "line": 6, "column": 7 } ], "path": [ "updateSnippet" ], "extensions": { "needsCaptchaResponse": true, "captchaSiteKey": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI", "spamLogId": 67 } } ], "data": { "updateSnippet": { "snippet": null, } } }
-
- Use the
captchaSiteKey
to obtain a CAPTCHA response value using the appropriate CAPTCHA API. Only Google reCAPTCHA v2 is supported. - Resubmit the request with the
X-GitLab-Captcha-Response
andX-GitLab-Spam-Log-Id
headers set.
--data-binary
is used to properly handle escaped double quotes
in the JSON-embedded query.export CAPTCHA_RESPONSE="<CAPTCHA response obtained from CAPTCHA service>"
export SPAM_LOG_ID="<spam_log_id obtained from initial REST response>"
curl --header "Authorization: Bearer $PRIVATE_TOKEN" --header "Content-Type: application/json" --header "X-GitLab-Captcha-Response: $CAPTCHA_RESPONSE" --header "X-GitLab-Spam-Log-Id: $SPAM_LOG_ID" --request POST --data-binary '{"query": "mutation {createSnippet(input: {title: \"Title\" visibilityLevel: public blobActions: [ { action: create filePath: \"BlobPath\" content: \"BlobContent\" } ] }) { snippet { id title } errors }}"}' "https://gitlab.example.com/api/graphql"