JIRA 7.6.1

Search for issues using JQL (GET)

GET

/rest/api/3/search

Issue search

Searches for issues using JQL.

If the JQL query expression is too large to be encoded as a query parameter, use the POST version of this resource.

This operation can be accessed anonymously.

Permissions required: Issues are included in the response where the user has:

Browse projects project permission for the project containing the issue.

If issue-level security is configured, issue-level security permission to view the issue.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'http://jira.local:8080/jira/rest//rest/api/3/search'

Response Example

200 - Success

{
  "expand": "names,schema",
  "startAt": 0,
  "maxResults": 50,
  "total": 1,
  "issues": [
    {
      "expand": "",
      "id": "10002",
      "self": "https://your-domain.atlassian.net/rest/api/3/issue/10002",
      "key": "ED-1",
      "fields": {
        "watcher": {
          "self": "https://your-domain.atlassian.net/rest/api/3/issue/EX-1/watchers",
          "isWatching": false,
          "watchCount": 1,
          "watchers": [
            {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "accountId": "5b10a2844c20165700ede21g",
              "displayName": "Mia Krystof",
              "active": false
            }
          ]
        },
        "attachment": [
          {
            "id": 10000,
            "self": "https://your-domain.atlassian.net/rest/api/3/attachments/10000",
            "filename": "picture.jpg",
            "author": {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "key": "",
              "accountId": "5b10a2844c20165700ede21g",
              "accountType": "atlassian",
              "name": "",
              "avatarUrls": {
                "48x48": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=48&s=48",
                "24x24": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=24&s=24",
                "16x16": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=16&s=16",
                "32x32": "https://avatar-management--avatars.server-location.prod.public.atl-paas.net/initials/MK-5.png?size=32&s=32"
              },
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2023-07-12T06:03:00.833+0000",
            "size": 23123,
            "mimeType": "image/jpeg",
            "content": "https://your-domain.atlassian.net/jira/rest/api/3/attachment/content/10000",
            "thumbnail": "https://your-domain.atlassian.net/jira/rest/api/3/attachment/thumbnail/10000"
          }
        ],
        "sub-tasks": [
          {
            "id": "10000",
            "type": {
              "id": "10000",
              "name": "",
              "inward": "Parent",
              "outward": "Sub-task"
            },
            "outwardIssue": {
              "id": "10003",
              "key": "ED-2",
              "self": "https://your-domain.atlassian.net/rest/api/3/issue/ED-2",
              "fields": {
                "status": {
                  "iconUrl": "https://your-domain.atlassian.net/images/icons/statuses/open.png",
                  "name": "Open"
                }
              }
            }
          }
        ],
        "description": {
          "type": "doc",
          "version": 1,
          "content": [
            {
              "type": "paragraph",
              "content": [
                {
                  "type": "text",
                  "text": "Main order flow broken"
                }
              ]
            }
          ]
        },
        "project": {
          "self": "https://your-domain.atlassian.net/rest/api/3/project/EX",
          "id": "10000",
          "key": "EX",
          "name": "Example",
          "avatarUrls": {
            "48x48": "https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000",
            "24x24": "https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000",
            "16x16": "https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000",
            "32x32": "https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000"
          },
          "projectCategory": {
            "self": "https://your-domain.atlassian.net/rest/api/3/projectCategory/10000",
            "id": "10000",
            "name": "FIRST",
            "description": "First Project Category"
          },
          "simplified": false,
          "style": "classic",
          "insight": {
            "totalIssueCount": 100,
            "lastIssueUpdateTime": "2023-07-12T06:03:00.831+0000"
          }
        },
        "comment": [
          {
            "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/comment/10000",
            "id": "10000",
            "author": {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "accountId": "5b10a2844c20165700ede21g",
              "displayName": "Mia Krystof",
              "active": false
            },
            "body": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas at posuere augue semper."
                    }
                  ]
                }
              ]
            },
            "updateAuthor": {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "accountId": "5b10a2844c20165700ede21g",
              "displayName": "Mia Krystof",
              "active": false
            },
            "created": "2021-01-17T12:34:00.000+0000",
            "updated": "2021-01-18T23:45:00.000+0000",
            "visibility": {
              "type": "role",
              "value": "Administrators",
              "identifier": "Administrators"
            }
          }
        ],
        "issuelinks": [
          {
            "id": "10001",
            "type": {
              "id": "10000",
              "name": "Dependent",
              "inward": "depends on",
              "outward": "is depended by"
            },
            "outwardIssue": {
              "id": "10004L",
              "key": "PR-2",
              "self": "https://your-domain.atlassian.net/rest/api/3/issue/PR-2",
              "fields": {
                "status": {
                  "iconUrl": "https://your-domain.atlassian.net/images/icons/statuses/open.png",
                  "name": "Open"
                }
              }
            }
          },
          {
            "id": "10002",
            "type": {
              "id": "10000",
              "name": "Dependent",
              "inward": "depends on",
              "outward": "is depended by"
            },
            "inwardIssue": {
              "id": "10004",
              "key": "PR-3",
              "self": "https://your-domain.atlassian.net/rest/api/3/issue/PR-3",
              "fields": {
                "status": {
                  "iconUrl": "https://your-domain.atlassian.net/images/icons/statuses/open.png",
                  "name": "Open"
                }
              }
            }
          }
        ],
        "worklog": [
          {
            "self": "https://your-domain.atlassian.net/rest/api/3/issue/10010/worklog/10000",
            "author": {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "accountId": "5b10a2844c20165700ede21g",
              "displayName": "Mia Krystof",
              "active": false
            },
            "updateAuthor": {
              "self": "https://your-domain.atlassian.net/rest/api/3/user?accountId=5b10a2844c20165700ede21g",
              "accountId": "5b10a2844c20165700ede21g",
              "displayName": "Mia Krystof",
              "active": false
            },
            "comment": {
              "type": "doc",
              "version": 1,
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "I did some work here."
                    }
                  ]
                }
              ]
            },
            "updated": "2021-01-18T23:45:00.000+0000",
            "visibility": {
              "type": "group",
              "value": "jira-developers",
              "identifier": "276f955c-63d7-42c8-9520-92d01dca0625"
            },
            "started": "2021-01-17T12:34:00.000+0000",
            "timeSpent": "3h 20m",
            "timeSpentSeconds": 12000,
            "id": "100028",
            "issueId": "10002"
          }
        ],
        "updated": 1,
        "timetracking": {
          "originalEstimate": "10m",
          "remainingEstimate": "3m",
          "timeSpent": "6m",
          "originalEstimateSeconds": 600,
          "remainingEstimateSeconds": 200,
          "timeSpentSeconds": 400
        }
      }
    }
  ],
  "warningMessages": [
    "The value 'bar' does not exist for the field 'foo'."
  ]
}

Request

Query Params

jql

string

optional

The JQL that defines the search. Note:

If no JQL expression is provided, all issues are returned.

username and userkey cannot be used as search terms due to privacy reasons. Use accountId instead.

If a user has hidden their email address in their user profile, partial matches of the email address will not find the user. An exact match is required.

startAt

integer

optional

The index of the first item to return in a page of results (page offset).

maxResults

integer

optional

The maximum number of items to return per page. To manage page size, Jira may return fewer items per page where a large number of fields are requested. The greatest number of items returned per page is achieved when requesting id or key only.

validateQuery

string

optional

Determines how to validate the JQL query and treat the validation results. Supported values are:

strict Returns a 400 response code if any errors are found, along with a list of all errors (and warnings).

warn Returns all errors as warnings.

none No validation is performed.

true Deprecated A legacy synonym for strict.

false Deprecated A legacy synonym for warn.

Note: If the JQL is not correctly formed a 400 response code is returned, regardless of the validateQuery value.

fields

array[string]

optional

A list of fields to return for each issue, use it to retrieve a subset of fields. This parameter accepts a comma-separated list. Expand options include:

*all Returns all fields.

*navigable Returns navigable fields.

Any issue field, prefixed with a minus to exclude.

Examples:

summary,comment Returns only the summary and comments fields.

-description Returns all navigable (default) fields except description.

*all,-comment Returns all fields except comments.

This parameter may be specified multiple times. For example, fields=field1,field2&fields=field3.

Note: All navigable fields are returned by default. This differs from GET issue where the default is all fields.

expand

string

optional

Use expand to include additional information about issues in the response. This parameter accepts a comma-separated list. Expand options include:

renderedFields Returns field values rendered in HTML format.

names Returns the display name of each field.

schema Returns the schema describing a field type.

transitions Returns all possible transitions for the issue.

operations Returns all possible operations for the issue.

editmeta Returns information about how each field can be edited.

changelog Returns a list of recent updates to an issue, sorted by date, starting from the most recent.

versionedRepresentations Instead of fields, returns versionedRepresentations a JSON array containing each version of a field's value, with the highest numbered item representing the most recent version.

properties

array[string]

optional

A list of issue property keys for issue properties to include in the results. This parameter accepts a comma-separated list. Multiple properties can also be provided using an ampersand separated list. For example, properties=prop1,prop2&properties=prop3. A maximum of 5 issue property keys can be specified.

fieldsByKeys

string

optional

Reference fields by their key (rather than ID).

Responses

🟢200Returned if the request is successful.

application/json

Body

The result of a JQL search.

expand

string

read-onlyoptional

Expand options that include additional search result details in the response.

issues

array[object (IssueBean) {15}]

read-onlyoptional

The list of issues found by the search.

changelog

object

read-onlyoptional

Details of changelogs associated with the issue.

editmeta

object

read-onlyoptional

The metadata for the fields on the issue that can be amended.

expand

string

read-onlyoptional

Expand options that include additional issue details in the response.

fields

object

optional

fieldsToInclude

object (IncludedFields)

optional

string

read-onlyoptional

The ID of the issue.

key

string

read-onlyoptional

The key of the issue.

names

object

read-onlyoptional

The ID and name of each field present on the issue.

operations

allOf {1}

read-onlyoptional

The operations that can be performed on the issue.

properties

object

read-onlyoptional

Details of the issue properties identified in the request.

renderedFields

object

read-onlyoptional

The rendered value of each field present on the issue.

schema

object

read-onlyoptional

The schema describing each field present on the issue.

self

string <uri>

read-onlyoptional

The URL of the issue details.

transitions

array[object (IssueTransition) {12}]

read-onlyoptional

The transitions that can be performed on the issue.

versionedRepresentations

object

read-onlyoptional

The versions of each field on the issue.

maxResults

integer <int32>

read-onlyoptional

The maximum number of results that could be on the page.

names

object

read-onlyoptional

The ID and name of each field in the search results.

Additional properties

string

read-onlyoptional

schema

object

read-onlyoptional

The schema describing the field types in the search results.

Additional properties

object (JsonTypeBean)

optional

The schema of a field.

startAt

integer <int32>

read-onlyoptional

The index of the first item returned on the page.

total

integer <int32>

read-onlyoptional

The number of results on the page.

warningMessages

array[string]

read-onlyoptional

Any warnings related to the JQL query.

🟠400Returned if the JQL query is invalid.

🟠401Returned if the authentication credentials are incorrect or missing.

Modified at 2023-07-13 03:27:27

Check issues against JQL

Search for issues using JQL (POST)