--- title: "Search for issues using JQL enhanced search (POST)" method: POST path: "/rest/api/3/search/jql" tags: ["Issue search"] --- # Search for issues using JQL enhanced search (POST) `POST /rest/api/3/search/jql` Searches for issues using [JQL](https://confluence.atlassian.com/x/egORLQ). Recent updates might not be immediately visible in the returned search results. If you need [read-after-write](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/) consistency, you can utilize the `reconcileIssues` parameter to ensure stronger consistency assurances. This operation can be accessed anonymously. **[Permissions](#permissions) required:** Issues are included in the response where the user has: * *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the issue. * If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission to view the issue. ## Request body - SearchAndReconcileRequestBean - `expand` string — Use [expand](#expansion) 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. - `fields` string[] — 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](#api-rest-api-3-issue-issueIdOrKey-get) where the default is all fields. - `fieldsByKeys` boolean — Reference fields by their key (rather than ID). The default is `false`. - `jql` string — A [JQL](https://confluence.atlassian.com/x/egORLQ) 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. - `maxResults` integer — 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. - `nextPageToken` string — 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. - `properties` string[] — A list of up to 5 issue properties to include in the results. This parameter accepts a comma-separated list. - `reconcileIssues` integer[] — 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 `200` Returned if the request is successful. - SearchAndReconcileResults — The result of a JQL search with issues reconsilation. - `isLast` boolean — Indicates whether this is the last page of the paginated response. - `issues` IssueBean[] — The list of issues found by the search or reconsiliation. - `changelog` PageOfChangelogs — A page of changelogs. - `histories` Changelog[] — The list of changelogs. - `author` UserDetails — User details permitted by the user's Atlassian Account privacy settings. However, be aware of these exceptions: * User record deleted from Atlassian: This occurs as the result of a right to be forgotten request. In this case, `displayName` provides an indication and other parameters have default values or are blank (for example, email is blank). * User record corrupted: This occurs as a results of events such as a server import and can only happen to deleted users. In this case, `accountId` returns *unknown* and all other parameters have fallback values. * User record unavailable: This usually occurs due to an internal service outage. In this case, all parameters have fallback values. - `accountId` string — The account ID of the user, which uniquely identifies the user across all Atlassian products. For example, *5b10ac8d82e05b22cc7d4ef5*. - `accountType` string — The type of account represented by this user. This will be one of 'atlassian' (normal users), 'app' (application user) or 'customer' (Jira Service Desk customer user) - `active` boolean — Whether the user is active. - `avatarUrls` AvatarUrlsBean - `16x16` string, uri — The URL of the item's 16x16 pixel avatar. - `24x24` string, uri — The URL of the item's 24x24 pixel avatar. - `32x32` string, uri — The URL of the item's 32x32 pixel avatar. - `48x48` string, uri — The URL of the item's 48x48 pixel avatar. - `displayName` string — The display name of the user. Depending on the user’s privacy settings, this may return an alternative value. - `emailAddress` string — The email address of the user. Depending on the user’s privacy settings, this may be returned as null. - `key` string — This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. - `name` string — This property is no longer available and will be removed from the documentation soon. See the [deprecation notice](https://developer.atlassian.com/cloud/jira/platform/deprecation-notice-user-privacy-api-migration-guide/) for details. - `self` string — The URL of the user. - `timeZone` string — The time zone specified in the user's profile. Depending on the user’s privacy settings, this may be returned as null. - `created` string, date-time — The date on which the change took place. - `historyMetadata` HistoryMetadata — Details of issue history metadata. - `activityDescription` string — The activity described in the history record. - `activityDescriptionKey` string — The key of the activity described in the history record. - `actor` HistoryMetadataParticipant — Details of user or system associated with a issue history metadata item. - `avatarUrl` string — The URL to an avatar for the user or system associated with a history record. - `displayName` string — The display name of the user or system associated with a history record. - `displayNameKey` string — The key of the display name of the user or system associated with a history record. - `id` string — The ID of the user or system associated with a history record. - `type` string — The type of the user or system associated with a history record. - `url` string — The URL of the user or system associated with a history record. - `cause` HistoryMetadataParticipant — Details of user or system associated with a issue history metadata item. - `avatarUrl` string — The URL to an avatar for the user or system associated with a history record. - `displayName` string — The display name of the user or system associated with a history record. - `displayNameKey` string — The key of the display name of the user or system associated with a history record. - `id` string — The ID of the user or system associated with a history record. - `type` string — The type of the user or system associated with a history record. - `url` string — The URL of the user or system associated with a history record. - `description` string — The description of the history record. - `descriptionKey` string — The description key of the history record. - `emailDescription` string — The description of the email address associated the history record. - `emailDescriptionKey` string — The description key of the email address associated the history record. - `extraData` object — Additional arbitrary information about the history record. - `generator` HistoryMetadataParticipant — Details of user or system associated with a issue history metadata item. - `avatarUrl` string — The URL to an avatar for the user or system associated with a history record. - `displayName` string — The display name of the user or system associated with a history record. - `displayNameKey` string — The key of the display name of the user or system associated with a history record. - `id` string — The ID of the user or system associated with a history record. - `type` string — The type of the user or system associated with a history record. - `url` string — The URL of the user or system associated with a history record. - `type` string — The type of the history record. - `id` string — The ID of the changelog. - `items` ChangeDetails[] — The list of items changed. - `field` string — The name of the field changed. - `fieldId` string — The ID of the field changed. - `fieldtype` string — The type of the field changed. - `from` string — The details of the original value. - `fromString` string — The details of the original value as a string. - `to` string — The details of the new value. - `toString` string — The details of the new value as a string. - `maxResults` integer — The maximum number of results that could be on the page. - `startAt` integer — The index of the first item returned on the page. - `total` integer — The number of results on the page. - `editmeta` IssueUpdateMetadata — A list of editable field details. - `fields` object - `expand` string — Expand options that include additional issue details in the response. - `fields` object - `fieldsToInclude` IncludedFields - `actuallyIncluded` string[] - `excluded` string[] - `included` string[] - `id` string — The ID of the issue. - `key` string — The key of the issue. - `names` object — The ID and name of each field present on the issue. - `operations` Operations — Details of the operations that can be performed on the issue. - `linkGroups` LinkGroup[] — Details of the link groups defining issue operations. - `groups` LinkGroup[] - `header` SimpleLink — Details about the operations available in this version. - `href` string - `iconClass` string - `id` string - `label` string - `styleClass` string - `title` string - `weight` integer - `id` string - `links` SimpleLink[] - `href` string - `iconClass` string - `id` string - `label` string - `styleClass` string - `title` string - `weight` integer - `styleClass` string - `weight` integer - `properties` object — Details of the issue properties identified in the request. - `renderedFields` object — The rendered value of each field present on the issue. - `schema` object — The schema describing each field present on the issue. - `self` string, uri — The URL of the issue details. - `transitions` IssueTransition[] — The transitions that can be performed on the issue. - `expand` string — Expand options that include additional transition details in the response. - `fields` object — Details of the fields associated with the issue transition screen. Use this information to populate `fields` and `update` in a transition request. - `hasScreen` boolean — Whether there is a screen associated with the issue transition. - `id` string — The ID of the issue transition. Required when specifying a transition to undertake. - `isAvailable` boolean — Whether the transition is available to be performed. - `isConditional` boolean — Whether the issue has to meet criteria before the issue transition is applied. - `isGlobal` boolean — Whether the issue transition is global, that is, the transition is applied to issues regardless of their status. - `isInitial` boolean — Whether this is the initial issue transition for the workflow. - `looped` boolean - `name` string — The name of the issue transition. - `to` StatusDetails — A status. - `description` string — The description of the status. - `iconUrl` string — The URL of the icon used to represent the status. - `id` string — The ID of the status. - `name` string — The name of the status. - `scope` Scope — The projects the item is associated with. Indicated for items associated with [next-gen projects](https://confluence.atlassian.com/x/loMyO). - `project` ProjectDetails — Details about a project. - `avatarUrls` AvatarUrlsBean - … - `id` string — The ID of the project. - `key` string — The key of the project. - `name` string — The name of the project. - `projectCategory` UpdatedProjectCategory — A project category. - … - `projectTypeKey` 'software' | 'service_desk' | 'business' — The [project type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes) of the project. - `self` string — The URL of the project details. - `simplified` boolean — Whether or not the project is simplified. - `type` 'PROJECT' | 'TEMPLATE' — The type of scope. - `self` string — The URL of the status. - `statusCategory` StatusCategory — A status category. - `colorName` string — The name of the color used to represent the status category. - `id` integer — The ID of the status category. - `key` string — The key of the status category. - `name` string — The name of the status category. - `self` string — The URL of the status category. - `versionedRepresentations` object — The versions of each field on the issue. - `names` object — The ID and name of each field in the search results. - `nextPageToken` string — 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. - `schema` object — The schema describing the field types in the search results. - `warnings` SearchWarning[] — Experimental. Warnings generated during the search, e.g. when a JQL clause exceeded its argument limit or when the result set was truncated due to an ingestion limit. This field is currently rolling out behind a feature flag and may be absent, empty, or change shape without notice until generally available. - `details` SearchWarningLimitDetails — Experimental. Structured details about a JQL clause exceeding its argument limit. - `actual` integer — The actual number of arguments supplied that exceeded the limit. - `arguments` string — The arguments passed to the JQL clause. - `clause` string — The JQL clause that triggered the limit, e.g. issueHistory(). - `limit` integer — The maximum number of arguments allowed for the clause. - `message` string — A human-readable explanation of the warning suitable for surfacing to end users. - `type` string — The type of warning, e.g. CLAUSE\_LIMIT\_EXCEEDED. ## Other responses - `400` — Returned if the search request is invalid - `401` — Returned if the authentication credentials are incorrect or missing. --- [API](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2.md) · [All operations](https://skmtc.net/atlassian/apis/the-jira-cloud-platform-rest-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/atlassian/the-jira-cloud-platform-rest-api-2/versions/ec7f275dfee5/schema)