# Saved Queries

This resource lets you access and work with saved searches in YouTrack.
|  Resource  |     ```GENERIC /api/savedQueries ```    |
| --- | --- |
|  Returned entity  |  [SavedQuery](api-entity-SavedQuery.html). For the description of the entity attributes, see [Supported Fields](#SavedQuery-supported-fields) section.  |
|  Supported methods  |      * `GET`: [Read a List of SavedQueries](#get_all-SavedQuery-method).    * `POST`: [Add a New SavedQuery](#create-SavedQuery-method).    |

## SavedQuery attributes

Represents a saved search.

### Related Resources

Below you can find the list of resources that let you work with this entity.

* [Saved Queries]()

* [Saved Queries of a User](resource-api-users-userID-savedQueries.html)

Extends [WatchFolder](api-entity-WatchFolder.html)

### Attributes

This table describes attributes of the `SavedQuery` entity.

* To receive an attribute in the response from the server, specify it explicitly in the `fields` request parameter.

* To update an attribute, provide it in the body of a POST request.

|  Field  |  Type  |  Description  |
| --- | --- | --- |
|  id  |  String  |  The ID of the saved search. `Read-only`.  |
|  query  |  String  |  The query that is saved in this search. `Can be null`.  |
|  issues  |  [Array of Issues](api-entity-Issue.html)  |  The collection of issues that match this saved search. `Read-only`.  |
|  visibleFor  |  [UserGroup](api-entity-UserGroup.html)  |    Deprecated. Use the `readSharingSettings` attribute instead.  Group of users that can see this saved search. If the saved search is visible only to its owner, this property is null.   `Can be null`.  |
|  updateableBy  |  [UserGroup](api-entity-UserGroup.html)  |    Deprecated. Use the `updateSharingSettings` attribute instead.  Group of users that can update this saved search. If only the owner of the saved search can update it, this property is null.   `Can be null`.  |
|  readSharingSettings  |  [WatchFolderSharingSettings](api-entity-WatchFolderSharingSettings.html)  |  Users and groups that can see this saved search. If the saved search is visible only to its owner, this property contains an empty array. `Read-only`.  |
|  updateSharingSettings  |  [WatchFolderSharingSettings](api-entity-WatchFolderSharingSettings.html)  |  Users and groups that can update this saved search. If only the owner of the saved search can update it, this property contains an empty array. `Read-only`.  |
|  owner  |  [User](api-entity-User.html)  |  The user who created the watch folder. `Read-only`. `Can be null`.  |
|  name  |  String  |  The name of the issue folder.  |

## Read a List of SavedQueries

Get all saved searches that are visible to the current user.

### Request syntax

```GENERIC
GET /api/savedQueries?{fields}&{$top}&{$skip}
```

|  null  |  The database ID of SavedQuery  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of SavedQuery attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.  |
|  $skip  |  Int  |  Optional. Lets you set a number of returned entities to skip before returning the first one.  |
|  $top  |  Int  |     Optional. Lets you specify the maximum number of entries that are returned in the response. If you don't set the $top value, the server limits the maximum number of returned entries.       The server returns a maximum of 42 entries for most resources that return collections. For more information, see [Pagination](api-concept-pagination.html).     |

### Sample

#### Sample request

```CURL
https://example.youtrack.cloud/api/savedQueries?fields=id,name,query,owner(login,name),visibleFor(name,id),issues(idReadable,summary)&$skip=8&$top=3
```

#### Sample response body

```JSON
[
  {
    "issues": [
      {
        "summary": "Example for Get specific issue tag",
        "idReadable": "RAP-2",
        "$type": "Issue"
      },
      {
        "summary": "REST API lets you create issues!",
        "idReadable": "SP-46",
        "$type": "Issue"
      },
      {
        "summary": "Issue from REST #1",
        "idReadable": "SP-16",
        "$type": "Issue"
      },
      {
        "summary": "Issue from REST #1",
        "idReadable": "SP-7",
        "$type": "Issue"
      },
      {
        "summary": "New summary",
        "idReadable": "SP-38",
        "$type": "Issue"
      }
    ],
    "query": "for: me",
    "visibleFor": {
      "name": "All Users",
      "id": "3-0",
      "$type": "UserGroup"
    },
    "owner": {
      "login": "search_user_1918800649",
      "name": "system user",
      "$type": "User"
    },
    "name": "Assigned to me",
    "id": "51-15",
    "$type": "SavedQuery"
  },
  {
    "issues": [
      {
        "summary": "REST API lets you create issues!",
        "idReadable": "SP-34",
        "$type": "Issue"
      },
      {
        "summary": "Issue from REST #1",
        "idReadable": "SP-16",
        "$type": "Issue"
      },
      {
        "summary": "Issue from REST #1",
        "idReadable": "SP-7",
        "$type": "Issue"
      },
      {
        "summary": "Another issue created using REST API",
        "idReadable": "SP-32",
        "$type": "Issue"
      }
    ],
    "query": "commenter: me",
    "visibleFor": {
      "name": "All Users",
      "id": "3-0",
      "$type": "UserGroup"
    },
    "owner": {
      "login": "search_user_1918800649",
      "name": "system user",
      "$type": "User"
    },
    "name": "Commented by me",
    "id": "51-16",
    "$type": "SavedQuery"
  },
  {
    "issues": [],
    "query": "project: {Scrum project from REST} has: -{Board Scrum project from REST Project Development} #Unresolved -Epic",
    "visibleFor": null,
    "owner": {
      "login": "john.doe",
      "name": "John Doe",
      "$type": "User"
    },
    "name": "Scrum project from REST Scrum-Board-Backlog",
    "id": "51-17",
    "$type": "SavedQuery"
  }
]
```

## Add a New SavedQuery

Create a new saved search.

Required fields: `name`, `query`.

### Required permissions

Requires permissions: Create Watch Folder

### Request syntax

```GENERIC
POST /api/savedQueries?{fields}
```

|  null  |  The database ID of SavedQuery  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of SavedQuery attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.  |

### Sample

#### Sample request

```CURL
https://example.youtrack.cloud/api/savedQueries?fields=id,name,query,owner(login,name),visibleFor(name,id),issues(id,idReadable,summary)
```

#### Sample request body

```JSON
{
  "query": "Priority: Major, Critical, Show-stopper #Unresolved",
  "name": "Requires Attention"
}
```

#### Sample response body

```JSON
{
  "query": "Priority: Major, Critical, Show-stopper #Unresolved",
  "issues": [
    {
      "idReadable": "SP-47",
      "summary": "REST API lets you create issues!",
      "$type": "Issue"
    },
    {
      "idReadable": "SP-46",
      "summary": "REST API lets you create issues!",
      "$type": "Issue"
    },
    {
      "idReadable": "SP-45",
      "summary": "REST API lets you create issues!",
      "$type": "Issue"
    },
    {
      "idReadable": "SP-44",
      "summary": "REST API lets you create issues!",
      "$type": "Issue"
    },
    {
      "idReadable": "SP-39",
      "summary": "Huston!",
      "$type": "Issue"
    },
    {
      "idReadable": "SP-38",
      "summary": "New summary",
      "$type": "Issue"
    }
  ],
  "visibleFor": null,
  "owner": {
    "login": "john.doe",
    "name": "John Doe",
    "$type": "User"
  },
  "name": "Requires Attention",
  "id": "51-34",
  "$type": "SavedQuery"
}
```