REST API

Tier: Premium, Ultimate
Offering: GitLab.com
Status: Beta

The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

The GitLab Orbit REST API lets you query the graph directly from scripts, CI pipelines, or custom tooling.

Authentication

All endpoints require a GitLab personal access token with read_api scope, passed as a Bearer token:

--header "Authorization: Bearer <your_token>"

Results are scoped to entities the token owner can access in GitLab.

Billing

During the beta, API calls do not consume GitLab Credits.

When GitLab Orbit is generally available, each call to POST /api/v4/orbit/query consumes GitLab Credits from your subscription. The other endpoints stay free. Credit rates are published in GitLab Credits and usage billing before charging begins.

Endpoints

Method	Endpoint	Description
`POST`	`/api/v4/orbit/query`	Execute a graph query
`GET`	`/api/v4/orbit/schema`	Fetch the current schema
`GET`	`/api/v4/orbit/status`	Check indexing status
`GET`	`/api/v4/orbit/tools`	List available MCP tool definitions

Query endpoint

Execute a graph query. The instance decides the query language: a JSON Query DSL object by default, or read-only GQL text when GitLab has enabled GQL for you.

The request body contains:

query: A JSON Query DSL object, or a text string when GQL is enabled. A query whose shape does not match the enabled language is rejected.
response_format: Optional response format. Use raw for structured JSON, or llm for compact text optimized for AI agents. Default: raw.

The GitLab Orbit CLI explicitly sends llm by default.

For example:

curl --request POST \
  --header "Authorization: Bearer <your_token>" \
  --header "Content-Type: application/json" \
  --data '{"query": <query_json>, "response_format": "raw"}' \
  "https://gitlab.com/api/v4/orbit/query"

See the query language reference for the full DSL.

The per-user orbit_gql_queries feature flag in Rails selects the mode. It is off by default, which accepts only JSON objects. With the flag on, the query endpoint, the named-query catalog, and the dashboard editor all use GQL text. JSON queries then reject, including requests from existing JSON callers. There is no public language selector. Rails sets the protobuf language for GitLab Orbit to JSON or GQL. Raw or named query kind is separate; named queries render and compile in that selected language. Agents and public REST callers do not send a language selector.

To send read-only query text or inspect its ontology with the flag on:

curl --request POST \
  --header "Authorization: Bearer <your_token>" \
  --header "Content-Type: application/json" \
  --data '{"query":"MATCH (u:User {id: 1}) RETURN u.username LIMIT 1","response_format":"llm"}' \
  "https://gitlab.com/api/v4/orbit/query"

curl --request POST \
  --header "Authorization: Bearer <your_token>" \
  --header "Content-Type: application/json" \
  --data '{"query":"CALL db.schema(\"MergeRequest\")","response_format":"raw"}' \
  "https://gitlab.com/api/v4/orbit/query"

The CLI accepts GQL text directly, without a language option:

glab orbit query 'CALL db.schema()'
glab orbit query 'MATCH (u:User {id: 1}) RETURN u'

To send a JSON request envelope, pass --file <path>, or --file - to read it from stdin.

The query text language, based on openCypher 9 syntax, is documented in the GitLab Orbit query frontend design document.

Example request

For example, a request to find projects with the most pipeline failures:

Put the request body in request.json:

{
  "query": {
    "query_type": "aggregation",
    "nodes": [
      {"id": "pl", "entity": "Pipeline", "filters": {"status": "failed"}},
      {"id": "p", "entity": "Project", "columns": ["name", "full_path"]}
    ],
    "relationships": [
      {"type": "IN_PROJECT", "from": "pl", "to": "p"}
    ],
    "group_by": ["p"],
    "aggregations": [
      {
        "count": "pl",
        "as": "failed_pipelines"
      }
    ],
    "aggregation_sort": "-failed_pipelines",
    "limit": 10
  },
  "response_format": "raw"
}

curl --request POST \
  --header "Authorization: Bearer <your_token>" \
  --header "Content-Type: application/json" \
  --data @request.json \
  "https://gitlab.com/api/v4/orbit/query"

An example response:

{
  "result": {
    "format_version": "2.0.0",
    "query_type": "aggregation",
    "nodes": [],
    "edges": [],
    "group_columns": [
      {
        "name": "p",
        "kind": "node",
        "node": "p",
        "entity": "Project"
      }
    ],
    "columns": [
      {
        "name": "failed_pipelines",
        "function": "count",
        "target": "pl"
      }
    ],
    "rows": [
      {
        "p": {
          "type": "Project",
          "id": "1",
          "properties": {
            "name": "payments-api",
            "full_path": "my-org/payments-api"
          }
        },
        "failed_pipelines": 47
      }
    ]
  },
  "query_type": "aggregation",
  "raw_query_strings": null,
  "row_count": 1
}

Schema endpoint

Returns the current ontology: all node types, their properties and types, and all relationship types.

curl --header "Authorization: Bearer <your_token>" \
  "https://gitlab.com/api/v4/orbit/schema"

Use this to discover available entity types and properties before writing queries.

Status endpoint

Returns the indexing status for groups where GitLab Orbit is enabled.

curl --header "Authorization: Bearer <your_token>" \
  "https://gitlab.com/api/v4/orbit/status"

An example response:

{
  "status": "indexed",
  "domains": {
    "sdlc": {"indexed": true, "last_updated": "2026-05-05T14:22:00Z"},
    "code": {"indexed": true, "last_updated": "2026-05-05T14:18:00Z"}
  },
  "projects": {
    "total": 847,
    "indexed": 847
  }
}

Tools endpoint

Returns the MCP tool definitions for list_commands and invoke_command in a format compatible with MCP clients.

curl --header "Authorization: Bearer <your_token>" \
  "https://gitlab.com/api/v4/orbit/tools"