GLQL API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to execute GitLab Query Language (GLQL) queries programmatically. GLQL provides a simplified query language for searching and filtering GitLab resources such as issues, merge requests, and epics across projects and groups.

Prerequisites:

The group or project must allow access to its data.
For private groups and projects, you must use a personal access token with appropriate permissions.

Execute a GLQL query

Executes a GLQL query to search and filter GitLab resources.

POST /glql

This endpoint rate-limits queries based on the query SHA. Identical queries that time out are tracked and might be temporarily blocked if executed too frequently.

Supported attributes:

Attribute	Type	Required	Description
`glql_yaml`	string	Yes	The GLQL query with optional YAML configuration. Maximum size: 10,000 bytes (10 KB). See Query formats for details.
`after`	string	No	Cursor for pagination. Use the `data.pageInfo.endCursor` value from a previous query to fetch the next page of results.

Query formats

The glql_yaml parameter accepts the YAML format with a query key:

yaml
fields: id,title,author
group: my-group
limit: 10
sort: created desc
query: state = opened

Configuration options

The following configuration options can be included in the YAML:

Option	Type	Required	Description
`fields`	string	No	Comma-separated list of fields to return. Default: `title`. See available fields.
`group`	string	No	Scope the query to a specific group. Cannot be used with `project`. If `group` is also specified in the query, the query value takes precedence.
`limit`	integer	No	Maximum number of results to return. Must be between 1 and 100. Default: `100`.
`project`	string	No	Scope the query to a specific project. Format: `group/project`. If `project` is also specified in the query, the query value takes precedence.
`sort`	string	No	Sort order for results. Format: `field direction` (for example, `created asc` or `created desc`).

Available fields

Set the fields configuration option to a comma-separated list of the available GLQL fields.

GLQL query syntax

The query syntax is defined by GLQL.

Response attributes

If successful, returns 200 OK and the following response attributes:

Attribute	Type	Description
`data`	object	Contains the query results.
`data.count`	integer	Total number of matching results.
`data.nodes`	array	Array of matching resources with requested fields.
`data.pageInfo`	object	Pagination information.
`data.pageInfo.endCursor`	string	Cursor for fetching the next page of results.
`data.pageInfo.hasNextPage`	boolean	Indicates if more results are available.
`data.pageInfo.hasPreviousPage`	boolean	Indicates if previous results are available.
`data.pageInfo.startCursor`	string	Cursor for fetching the previous page of results.
`error`	string	Error message if the query failed.
`fields`	array	Array of field definitions.
`fields[].field`	string	The base field name. For aliased parameterized fields, this is the underlying field name (for example, `durationQuantile`), while `key` is the alias (for example, `p50`). For standard fields, same as `key`.
`fields[].key`	string	The unique field identifier.
`fields[].label`	string	The human-readable field name.
`fields[].name`	string	The common field name that unifies similar fields. For example, `created` and `createdAt` keys have the name `createdAt`. For aliased parameterized fields, this is the generated response key (for example, `durationQuantile_quantile_0_d5`), not a common name.
`fields[].parameters`	object	Resolved parameter metadata for parameterized fields. Absent when the field has no parameters. Values are strings, or arrays of strings for list parameters. For example, `{"granularity": "weekly"}`, `{"quantile": "0.5"}`, or `{"thresholds": ["4", "25", "100"]}`.
`fields[].type`	string	Field classification: `dimension` or `metric` for analytics mode fields. Absent for standard fields.
`success`	boolean	Indicates if the query was successful.