---
title: "Evaluate Jira expression using enhanced search API"
method: POST
path: "/rest/api/3/expression/evaluate"
tags: ["Jira expressions"]
---

# Evaluate Jira expression using enhanced search API

`POST /rest/api/3/expression/evaluate`

Evaluates a Jira expression and returns its value. The difference between this and `eval` is that this endpoint uses the enhanced search API when evaluating JQL queries. This API is eventually consistent, unlike the strongly consistent `eval` API. This allows for better performance and scalability. In addition, this API's response for JQL evaluation is based on a scrolling view (backed by a `nextPageToken`) instead of a paginated view (backed by `startAt` and `totalCount`).

This resource can be used to test Jira expressions that you plan to use elsewhere, or to fetch data in a flexible way. Consult the [Jira expressions documentation](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/) for more details.

#### Context variables ####

The following context variables are available to Jira expressions evaluated by this resource. Their presence depends on various factors; usually you need to manually request them in the context object sent in the payload, but some of them are added automatically under certain conditions.

 *  `user` ([User](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user)): The current user. Always available and equal to `null` if the request is anonymous.
 *  `app` ([App](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#app)): The [Connect app](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps) that made the request. Available only for authenticated requests made by Connect apps (read more here: [Authentication for Connect apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)).
 *  `issue` ([Issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)): The current issue. Available only when the issue is provided in the request context object.
 *  `issues` ([List](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#list) of [Issues](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)): A collection of issues matching a JQL query. Available only when JQL is provided in the request context object.
 *  `project` ([Project](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#project)): The current project. Available only when the project is provided in the request context object.
 *  `sprint` ([Sprint](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#sprint)): The current sprint. Available only when the sprint is provided in the request context object.
 *  `board` ([Board](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#board)): The current board. Available only when the board is provided in the request context object.
 *  `serviceDesk` ([ServiceDesk](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#servicedesk)): The current service desk. Available only when the service desk is provided in the request context object.
 *  `customerRequest` ([CustomerRequest](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#customerrequest)): The current customer request. Available only when the customer request is provided in the request context object.

In addition, you can pass custom context variables along with their types. You can then access them from the Jira expression by key. You can use the following variables in a custom context:

 *  `user`: A [user](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user) specified as an Atlassian account ID.
 *  `issue`: An [issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue) specified by ID or key. All the fields of the issue object are available in the Jira expression.
 *  `json`: A JSON object containing custom content.
 *  `list`: A JSON list of `user`, `issue`, or `json` variable types.

This operation can be accessed anonymously.

**[Permissions](#permissions) required**: None. However, an expression may return different results for different users depending on their permissions. For example, different users may see different comments on the same issue.  
Permission to access Jira Software is required to access Jira Software context variables (`board` and `sprint`) or fields (for example, `issue.sprint`).

## Query parameters

- `expand` string

## Request body

- JiraExpressionEvaluateRequestBean — The request to evaluate a Jira expression. This bean will be replacing `JiraExpressionEvaluateRequest` as part of new `evaluate` endpoint
  - `context` JiraExpressionEvaluateContextBean
    - `board` integer — The ID of the board that is available under the `board` variable when evaluating the expression.
    - `custom` CustomContextVariable[] — Custom context variables and their types. These variable types are available for use in a custom context: * `user`: A [user](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user) specified as an Atlassian account ID. * `issue`: An [issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue) specified by ID or key. All the fields of the issue object are available in the Jira expression. * `json`: A JSON object containing custom content. * `list`: A JSON list of `user`, `issue`, or `json` variable types.
      - union
        - object — A [user](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user) specified as an Atlassian account ID.
          - `accountId` string, required — The account ID of the user.
          - `type` string, required — Type of custom context variable.
        - object — An [issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue) specified by ID or key. All the fields of the issue object are available in the Jira expression.
          - `id` integer — The issue ID.
          - `key` string — The issue key.
          - `type` string, required — Type of custom context variable.
        - object — A JSON object with custom content.
          - `type` string, required — Type of custom context variable.
          - `value` object — A JSON object containing custom content.
    - `customerRequest` integer — The ID of the customer request that is available under the `customerRequest` variable when evaluating the expression. This is the same as the ID of the underlying Jira issue, but the customer request context variable will have a different type.
    - `issue` IdOrKeyBean
      - `id` integer — The ID of the referenced item.
      - `key` string — The key of the referenced item.
    - `issues` JexpEvaluateCtxIssues — The JQL specifying the issues available in the evaluated Jira expression under the `issues` context variable. This bean will be replacing `JexpIssues` bean as part of new `evaluate` endpoint
      - `jql` JexpEvaluateCtxJqlIssues — The JQL specifying the issues available in the evaluated Jira expression under the `issues` context variable. Not all issues returned by the JQL query are loaded, only those described by the `nextPageToken` and `maxResults` properties. This bean will be replacing JexpJqlIssues bean as part of new `evaluate` endpoint
        - `maxResults` integer — The maximum number of issues to return from the JQL query. max results value considered may be lower than the number specific here.
        - `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.
        - `query` string — The JQL query, required to be bounded. Additionally, `orderBy` clause can contain a maximum of 7 fields
    - `project` IdOrKeyBean
      - `id` integer — The ID of the referenced item.
      - `key` string — The key of the referenced item.
    - `serviceDesk` integer — The ID of the service desk that is available under the `serviceDesk` variable when evaluating the expression.
    - `sprint` integer — The ID of the sprint that is available under the `sprint` variable when evaluating the expression.
  - `expression` string, required — The Jira expression to evaluate.

## Response `200`

Returned if the evaluation results in a value. The result is a JSON primitive value, list, or object.

- JExpEvaluateJiraExpressionResultBean — The result of evaluating a Jira expression.This bean will be replacing `JiraExpressionResultBean` bean as part of new evaluate endpoint
  - `meta` JExpEvaluateMetaDataBean — Contains information about the expression evaluation. This bean will be replacing `JiraExpressionEvaluationMetaDataBean` bean as part of new `evaluate` endpoint
    - `complexity` JiraExpressionsComplexityBean
      - `beans` JiraExpressionsComplexityValueBean, required
        - `limit` integer, required — The maximum allowed complexity. The evaluation will fail if this value is exceeded.
        - `value` integer, required — The complexity value of the current expression.
      - `expensiveOperations` JiraExpressionsComplexityValueBean, required
        - `limit` integer, required — The maximum allowed complexity. The evaluation will fail if this value is exceeded.
        - `value` integer, required — The complexity value of the current expression.
      - `primitiveValues` JiraExpressionsComplexityValueBean, required
        - `limit` integer, required — The maximum allowed complexity. The evaluation will fail if this value is exceeded.
        - `value` integer, required — The complexity value of the current expression.
      - `steps` JiraExpressionsComplexityValueBean, required
        - `limit` integer, required — The maximum allowed complexity. The evaluation will fail if this value is exceeded.
        - `value` integer, required — The complexity value of the current expression.
    - `issues` JExpEvaluateIssuesMetaBean — Meta data describing the `issues` context variable.This bean will be replacing IssuesMetaBean bean as part of new `evaluate` endpoint
      - `jql` JExpEvaluateIssuesJqlMetaDataBean — The description of the page of issues loaded by the provided JQL query.This bean will be replacing IssuesJqlMetaDataBean bean as part of new `evaluate` endpoint
        - `isLast` boolean — Indicates whether this is the last page of the paginated response.
        - `nextPageToken` string, required — Next Page token for the next page of issues.
  - `value` unknown, required

## Other responses

- `400` — Returned if: * the request is invalid, that is: * invalid data is provided, such as a request including issue ID and key. * the expression is invalid and can not be parsed. * evaluation fails at runtime. This may happen for various reasons. For example, accessing a property on a null object (such as the expression `issue.id` where `issue` is `null`). In this case an error message is provided. * If jql is unbounded or empty. * If nextPageToken is invalid
- `401` — Returned if the authentication credentials are incorrect or missing.
- `404` — Returned if any object provided in the request context is not found or the user does not have permission to view it.

---

[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)