---
title: NerdGraph tutorial: Run NRQL queries asynchronously
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/async-queries-nrql-tutorial
---

You can [use NerdGraph to run NRQL queries](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-nrql-tutorial). In addition, you can also use NerdGraph to run an asynchronous NRQL query. Asynchronous queries run in the background, and you can make follow-up requests to retrieve query results or the query status. This type of query avoids a query being interrupted by issues like browser timeouts or HTTP connection timeouts. It's especially useful for running queries that may take a long time to complete.

## Requirements [#requirements]

If you have [Data Plus](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-pricing-billing/data-ingest-billing#data-plus), you can run asynchronous queries with a 10-minute max duration using either NerdGraph or the query builder UI.

For more on query limits, see [Query limits](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/rate-limits-nrql-queries/#query-duration).

## Asynchronous query example [#example]

Here's an example of an asynchronous query NerdGraph call. The `async: true` is what makes the query asynchronous. This query will return results if it completes within the default timeout of 5 seconds; otherwise it will return `queryProgress` data for use in follow-up queries to the `nrqlQueryProgress` field.

```graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      nrql(query: "SELECT * FROM Transaction", async: true) {
        results
        queryProgress {
          queryId
          completed
          retryAfter
          retryDeadline
          resultExpiration
        }
      }
    }
  }
}
```

## Getting the results or status of an async query [#example-query-results]

If your query exceeds the default timeout, it will return a query ID. You can take that ID and run a second query to get the query results, if it's finished, or else the status of that query.

```graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      nrqlQueryProgress(queryId: "YOUR_QUERY_ID") {
        results
        queryProgress {
          queryId
          completed
          retryAfter
          retryDeadline
          resultExpiration
        }
      }
    }
  }
}
```

Some important details about this query:

-   The `queryId` comes from the `queryProgress` data returned by the original asynchronous query.
-   The `account` argument must match the `account` argument from the original query.
-   This query will return results if asynchronous execution has completed; otherwise it will return `queryProgress` data.
-   The query can be repeated verbatim until results or an error are returned.

## Cancel an async query [#example-cancel-query]

You can cancel an asynchronous query by using the `nrqlCancelQuery` mutation. This mutation takes the `queryId` of the
query you want to cancel. It will either return an `ACCEPTED` status, or `REJECTED` status with a reason for rejection.

```graphql
mutation {
  nrqlCancelQuery(queryId: "YOUR_QUERY_ID") {
    queryId
    requestStatus
    rejectionReason
  }
}
```