# Search labels

From **GitHub v3 REST API**.

`GET /search/labels`

Find labels in a repository with names or descriptions that match search keywords. Returns up to 100 results [per page](https://docs.github.com/enterprise-server@3.0/rest/overview/resources-in-the-rest-api#pagination).

When searching for labels, you can get text match metadata for the label **name** and **description** fields when you pass the `text-match` media type. For more details about how to receive highlighted search results, see [Text match metadata](https://docs.github.com/enterprise-server@3.0/rest/reference/search#text-match-metadata).

For example, if you want to find labels in the `linguist` repository that match `bug`, `defect`, or `enhancement`. Your query might look like this:

`q=bug+defect+enhancement&repository_id=64778136`

The labels that best match the query appear first in the search results.

## Parameters

### `repository_id`

- Location: query
- Required: true
- Type: `integer`

The id of the repository.

### `q`

- Location: query
- Required: true
- Type: `string`

The search keywords. This endpoint does not accept qualifiers in the query. To learn more about the format of the query, see [Constructing a search query](https://docs.github.com/enterprise-server@3.0/rest/reference/search#constructing-a-search-query).

### `sort`

- Location: query
- Required: false
- Type: `string`
- Allowed values: `"created"`, `"updated"`

Sorts the results of your query by when the label was `created` or `updated`. Default: [best match](https://docs.github.com/enterprise-server@3.0/rest/reference/search#ranking-search-results)

### `order`

- Location: query
- Required: false
- Type: `string`
- Default: `desc`
- Allowed values: `"desc"`, `"asc"`

Determines whether the first search result returned is the highest number of matches (`desc`) or lowest number of matches (`asc`). This parameter is ignored unless you provide `sort`.

### `per_page`

- Location: query
- Required: false
- Type: `integer`
- Default: `30`

Results per page (max 100)

### `page`

- Location: query
- Required: false
- Type: `integer`
- Default: `1`

Page number of the results to fetch.

## Responses

### `200`

Response

### `application/json`

- Type: `object`

```json
{
  "incomplete_results": false,
  "items": [
    {
      "color": "84b6eb",
      "default": true,
      "description": "New feature or request.",
      "id": 418327088,
      "name": "enhancement",
      "node_id": "MDU6TGFiZWw0MTgzMjcwODg=",
      "score": 1,
      "url": "https://api.github.com/repos/octocat/linguist/labels/enhancement"
    },
    {
      "color": "ee0701",
      "default": true,
      "description": "Something isn't working.",
      "id": 418327086,
      "name": "bug",
      "node_id": "MDU6TGFiZWw0MTgzMjcwODY=",
      "score": 1,
      "url": "https://api.github.com/repos/octocat/linguist/labels/bug"
    }
  ],
  "total_count": 2
}
```

```json
{"properties":{"incomplete_results":{"type":"boolean"},"items":{"items":{"$ref":"#/components/schemas/label-search-result-item"},"type":"array"},"total_count":{"type":"integer"}},"required":["total_count","incomplete_results","items"],"type":"object"}
```

### `304`

Not modified

### `403`

Forbidden

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `404`

Resource not found

### `application/json`

- Type: `object`

Basic Error

```json
{"description":"Basic Error","properties":{"documentation_url":{"type":"string"},"message":{"type":"string"},"status":{"type":"string"},"url":{"type":"string"}},"title":"Basic Error","type":"object"}
```

### `422`

Validation failed

### `application/json`

- Type: `object`

Validation Error

```json
{"description":"Validation Error","properties":{"documentation_url":{"type":"string"},"errors":{"items":{"properties":{"code":{"type":"string"},"field":{"type":"string"},"index":{"type":"integer"},"message":{"type":"string"},"resource":{"type":"string"},"value":{"oneOf":[{"nullable":true,"type":"string"},{"nullable":true,"type":"integer"},{"items":{"type":"string"},"nullable":true,"type":"array"}]}},"required":["code"],"type":"object"},"type":"array"},"message":{"type":"string"}},"required":["message","documentation_url"],"title":"Validation Error","type":"object"}
```

## Request examples

### cURL

```shell
curl --request GET \
  --url {protocol}://{hostname}/api/v3/search/labels
```