Issue search

Search for issues using JQL enhanced search (POST)

Changed on

Searches for issues using JQL. Recent updates might not be immediately visible in the returned search results. If you need read-after-write consistency, you can utilize the reconcileIssues parameter to ensure stronger consistency assurances. This operation can be accessed anonymously.

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

post/rest/api/2/search/jql

Request

  • Base URL: https://your-domain.atlassian.net
  • URL: https://your-domain.atlassian.net/rest/api/2/search/jql
  • Auth: one of:
    • HTTP basic
    • OAuth 2 (authorization code, authorization URL https://auth.atlassian.com/authorize, token URL https://auth.atlassian.com/oauth/token, scopes: read:jira-work)
    • none

Request body

expandstring

Use expand to include additional information about issues in the response. Note that, unlike the majority of instances where expand is specified, expand is defined as a comma-delimited string of values. The expand options are:

  • 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.

Examples: "names,changelog" Returns the display name of each field as well as a list of recent updates to an issue.

fieldsstring[]

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.
  • id Returns only issue IDs.
  • Any issue field, prefixed with a dash to exclude.

The default is id.

Examples:

  • summary,comment Returns the summary and comments fields only.
  • *all,-comment Returns all fields except comments.

Multiple fields parameters can be included in a request.

Note: By default, this resource returns IDs only. This differs from GET issue where the default is all fields.

fieldsByKeysboolean

Reference fields by their key (rather than ID). The default is false.

includeArchivedProjectsboolean

Whether to also return issues that belong to archived projects. Archived projects are excluded by default. Requires Browse projects permission on the archived project. The default is false.

jqlstring

A JQL expression. For performance reasons, this parameter requires a bounded query. A bounded query is a query with a search restriction.

  • Example of an unbounded query: order by key desc.
  • Example of a bounded query: assignee = currentUser() order by key.

Additionally, orderBy clause can contain a maximum of 7 fields.

maxResultsinteger

The maximum number of items to return per page. To manage page size, API 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. It returns max 5000 issues.

nextPageTokenstring

The token for a page to fetch that is not the first page. The first page has a nextPageToken of null. Use the nextPageToken to fetch the next page of issues.

propertiesstring[]

A list of up to 5 issue properties to include in the results. This parameter accepts a comma-separated list.

reconcileIssuesinteger[]

Strong consistency issue ids to be reconciled with search results. Accepts max 50 ids. This list of ids should be consistent with each paginated request across different pages.

Response

Returned if the request is successful.

isLastboolean

Indicates whether this is the last page of the paginated response.

namesobject

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

nextPageTokenstring

Continuation token to fetch the next page. If this result represents the last or the only page this token will be null. This token will expire in 7 days.

schemaobject

The schema describing the field types in the search results.

Changes

  • 40fd882d2209Revision changes
    • info

      added the new optional request property

  • 38a98954789eRevision changes
    • warning

      added the new product_discovery enum value to the /////////////////// response property for the response status