Use this API to search across GitLab in an instance, a group, or a project, and to retrieve information about advanced search migrations.

Every call to this API requires authentication. Retrieving advanced search migrations requires administrator access.

Some scopes are available for basic search. When advanced search or exact code search is enabled, additional scopes become available. To use basic search instead, see specify a search type.

These endpoints support offset-based pagination.

Search on GitLab within a group

GET /api/v4/groups/{id}/(-/)search

This feature was introduced in GitLab 10.5.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the group
search
Query, required		StringSearch query
scope
Query, required		StringScope of the search
Allowed values: projects, groups, issues, work_items, merge_requests, milestones, users
Minimum length: 1
state
Query		StringFilter results by state. Applies only to the issues, work_items, and merge_requests scopes
Allowed values: all, opened, closed, merged
confidential
Query		BooleanIf true, returns only confidential results. If false, returns only non-confidential results. Applies only to the issues and work_items scopes
type
Query		Array of stringsFilter work items by type. Only applies to work_items scope. Available types: issue, task, incident, ticket
include_archived
Query		BooleanIf true, includes archived projects in the search. Introduced in GitLab 18.7
Default: false
fields
Query		Array of stringsArray of fields to search. Only “title” is supported (work_items / issues scope)
language
Query		Array of stringsArray of languages to filter blobs by language
label_name
Query		Array of stringsArray of labels to filter work_items / issues / merge_requests by label
source_branch
Query		StringFilter merge requests by source branch
Maximum length: 255
target_branch
Query		StringFilter merge requests by target branch
Maximum length: 255
not_source_branch
Query		StringExclude merge requests by source branch
Maximum length: 255
not_target_branch
Query		StringExclude merge requests by target branch
Maximum length: 255
author_username
Query		StringFilter merge requests by author username
Maximum length: 255
not_author_username
Query		StringExclude merge requests by author username
Maximum length: 255
exclude_forks
Query		BooleanExclude forked projects from search results. Only supported for work_items / issues scope
num_context_lines
Query		IntegerNumber of context lines around each match. Only supported for blobs scope
Maximum: 20
Minimum: 0
page
Query		IntegerPage number of results to retrieve
Default: 1
Example: 1
per_page
Query		IntegerNumber of items to list per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
404Not Found—

Search a project

GET /api/v4/projects/{id}/(-/)search

Searches for content in a specified project.

Parameters

NameTypeDescription
id
Path, required		String or integerID or URL-encoded path of the project
search
Query, required		StringSearch query
scope
Query, required		StringScope of the search
Allowed values: issues, work_items, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users
Minimum length: 1
ref
Query		StringName of the repository branch or tag. If omitted, uses the default branch
state
Query		StringFilter results by state. Applies only to the issues, work_items, and merge_requests scopes
Allowed values: all, opened, closed, merged
confidential
Query		BooleanIf true, returns only confidential results. If false, returns only non-confidential results. Applies only to the issues and work_items scopes
type
Query		Array of stringsFilter work items by type. Only applies to work_items scope. Available types: issue, task, incident, ticket
fields
Query		Array of stringsArray of fields to search. Only “title” is supported (work_items / issues scope)
language
Query		Array of stringsArray of languages to filter blobs by language
label_name
Query		Array of stringsArray of labels to filter work_items / issues / merge_requests by label
source_branch
Query		StringFilter merge requests by source branch
Maximum length: 255
target_branch
Query		StringFilter merge requests by target branch
Maximum length: 255
not_source_branch
Query		StringExclude merge requests by source branch
Maximum length: 255
not_target_branch
Query		StringExclude merge requests by target branch
Maximum length: 255
author_username
Query		StringFilter merge requests by author username
Maximum length: 255
not_author_username
Query		StringExclude merge requests by author username
Maximum length: 255
num_context_lines
Query		IntegerNumber of context lines around each match. Only supported for blobs scope
Maximum: 20
Minimum: 0
page
Query		IntegerPage number of results to retrieve
Default: 1
Example: 1
per_page
Query		IntegerNumber of items to list per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
404Not Found—

Search an instance

GET /api/v4/search

Searches for a term across the entire GitLab instance. The response depends on the requested scope.

Parameters

NameTypeDescription
search
Query, required		StringSearch query
scope
Query, required		StringScope of the search
Allowed values: projects, groups, issues, work_items, merge_requests, milestones, snippet_titles, users
Minimum length: 1
state
Query		StringFilter results by state. Applies only to the issues, work_items, and merge_requests scopes
Allowed values: all, opened, closed, merged
confidential
Query		BooleanIf true, returns only confidential results. If false, returns only non-confidential results. Applies only to the issues and work_items scopes
type
Query		Array of stringsFilter work items by type. Only applies to work_items scope. Available types: issue, task, incident, ticket
include_archived
Query		BooleanIf true, includes archived projects in the search. Introduced in GitLab 18.7
Default: false
fields
Query		Array of stringsArray of fields to search. Only “title” is supported (work_items / issues scope)
language
Query		Array of stringsArray of languages to filter blobs by language
label_name
Query		Array of stringsArray of labels to filter work_items / issues / merge_requests by label
source_branch
Query		StringFilter merge requests by source branch
Maximum length: 255
target_branch
Query		StringFilter merge requests by target branch
Maximum length: 255
not_source_branch
Query		StringExclude merge requests by source branch
Maximum length: 255
not_target_branch
Query		StringExclude merge requests by target branch
Maximum length: 255
author_username
Query		StringFilter merge requests by author username
Maximum length: 255
not_author_username
Query		StringExclude merge requests by author username
Maximum length: 255
exclude_forks
Query		BooleanExclude forked projects from search results. Only supported for work_items / issues scope
num_context_lines
Query		IntegerNumber of context lines around each match. Only supported for blobs scope
Maximum: 20
Minimum: 0
page
Query		IntegerPage number of results to retrieve
Default: 1
Example: 1
per_page
Query		IntegerNumber of items to list per page
Default: 20
Example: 20

Responses

CodeDescriptionSchema
200OK—
400Bad Request—
←
REST API / Runners
REST API / Secure files
→