---
title: Schedule NRQL searches
source: https://docs.newrelic.com/docs/nrql/using-nrql/schedule-nrql-searches
---

As a New Relic user, you may run the same NRQL queries over and over again to monitor critical patterns, check for specific conditions, or generate regular reports. For example, you need to check daily for failed transactions, monitor weekly error rates, or track hourly performance metrics across your applications. This manual process is time-consuming and makes it easy to miss important insights when you're not actively monitoring.

Scheduled NRQL searches solve this problem by automating your repetitive queries. You can schedule queries to run automatically and receive results via email, so you'll stay informed about critical patterns without constant manual monitoring.

## What you can do [#features]

Scheduled NRQL searches let you:

-   **Automate repetitive queries**: Convert manual queries into automated workflows that run on your schedule.
-   **Start from anywhere**: Create a scheduled search from Administration or directly from the Logs UI.
-   **Stay informed proactively**: Receive email notifications with query results delivered directly to your inbox.
-   **Set notification conditions**: Choose to get notified on every run, or only when your results meet a condition you define based on the number of results in your query.
-   **Schedule flexibly**: Use custom cron expression schedules to define when queries run.
-   **Choose your output format**: Export results as CSV or JSON files attached to email notifications.
-   **Collaborate with your team**: Send scheduled search results to multiple email recipients.
-   **Manage everything centrally**: View, edit, and manage all your scheduled searches from a single location in the Administration UI, regardless of where you created them.

## Pricing [#pricing]

Scheduled NRQL searches have no separate pricing. You pay only the standard query cost of running the underlying NRQL query, based on your account's pricing model.

## Prerequisites [#prerequisites]

To use scheduled NRQL searches, you need:

-   **Account access**: Access to the account where you want to schedule searches.
-   **Data access**: Appropriate permissions to query the data you want to schedule. For example, if scheduling a query against log data, you need access to that log data.

### Permissions [#permissions]

By default, the **All product admin** and **Standard user** standard roles already include **Read** and **Modify** access to scheduled searches, and only **All product admin** includes **Delete** access. These roles also already include the **User API Keys (for self)** > **Modify** capability (`account.create.own_api_keys`), which a scheduled search needs to run successfully.

If you want to [create a custom role](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/account-user-mgmt-tutorial/#roles) and assign specific **Scheduled Search** capabilities to it, use either of the following methods:

-   **NerdGraph**: [Create an account-scoped custom role via NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-manage-groups/#account-scoped-role), and add the permission IDs from the following table to the `permissionIds` array.
-   **UI**: [Create a new custom role](https://docs.newrelic.com/docs/accounts/accounts-billing/new-relic-one-user-management/account-user-mgmt-tutorial/#roles), or edit an existing one, to add the **Scheduled Search** capability from the **Scheduled Search and Reports** section.

> #### ⚠️ IMPORTANT
>
> Some capabilities grant broader access than others. For example, **Delete** also grants read and modify access. If you only want to grant a narrower capability, select that specific capability instead of **Delete**.

The following table lists each capability, its permission IDs, and what it grants:

| Capability                                | Permission ID                                                                                          | Description                                                                                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Scheduled Search** > **Read**           | `scheduled_search.read.schedule`                                                                       | View scheduled searches                                                                                                                                  |
| **Scheduled Search** > **Modify**         | `scheduled_search.modify.schedule` `scheduled_search.read.schedule`                                    | View, create, and edit scheduled searches                                                                                                                |
| **Scheduled Search** > **Delete**         | `scheduled_search.delete.schedule` `scheduled_search.read.schedule` `scheduled_search.modify.schedule` | View, create, edit, and delete scheduled searches                                                                                                        |
| **User API Keys (for self)** > **Modify** | `account.create.own_api_keys`                                                                          | Required to run a scheduled search. New Relic uses it to create a user API key on your behalf, to maintain your user context. Without it, the run fails. |

## Schedule a new search [#create-schedule]

New Relic guides you through this flow directly in the product. Each step below covers what needs to happen there and anything that isn't obvious from the screen.

1.  **Access the scheduled search creation flow**:
    Choose the entry point that fits your workflow. Both lead to the same configuration flow.
    ### From Administration
    Go to **[one.newrelic.com](https://one.newrelic.com) > Administration > Scheduled Searches** and click **Schedule a search**.
    ### From the Logs UI
    From the [logs UI](https://docs.newrelic.com/docs/logs/ui-data/use-logs-ui/#workflow-search), use either of these options:
    -   At the top-right corner, click the  menu and select **Schedule a search**.
    -   Under the query trend chart, click the clock icon.

        If you already composed and ran a query, it carries over into the configuration flow. Otherwise, you can draft your query in the next step.
    > #### 💡 TIP
    >
    > You can create a scheduled search from Administration or the Logs UI, but you can only view, edit, or delete existing scheduled searches from **Administration > Scheduled Searches**.
2.  **Configure your query**:
    Draft and test your NRQL query, then continue.
3.  **Set up notification**:
    Set up the following:
    -   Name the search, then set a destination for the results. You can only send results to email destinations.
        -   If the destination exists, select it from the list.
        -   If it doesn't exist, add one or more email recipients and name the destination.
    -   Choose a subject, message, and output format for the email.
    -   Set the notification condition under **Send notification**. It defaults to **Always**. To send only when your results meet a count you define, customize it here.
    > #### ⚠️ CAUTION
    >
    > Scheduled search results are attached to email as CSV or JSON files and may contain sensitive data. Review your email destinations to confirm only intended recipients are included.
4.  **Set a schedule**:
    Choose the following:
    -   Choose a frequency: hourly, daily, weekly, or a custom cron expression.
    -   Select a time zone for the schedule.
    If you use a cron expression, the following are some common patterns for reference:
    -   `0 * * * *` - Every hour at the top of the hour
    -   `0 9 * * *` - Every day at 9:00 AM
    -   `0 9 * * 1` - Every Monday at 9:00 AM
    -   `0 0 1 * *` - First day of every month at midnight
    -   `*/15 * * * *` - Every 15 minutes
    -   `0 9 * * 1-5` - Every weekday at 9:00 AM
    > #### 💡 TIP
    >
    > The shortest supported interval is every 10 minutes.
    If you set a notification condition instead of sending on every run, New Relic checks the condition at the exact scheduled run time. It doesn't track fluctuations between runs, so if your results drop below the condition's threshold before the next run, you won't get a notification for that run.
5.  **Review, confirm, and schedule the search**:
    Review your configuration, then schedule the search. It appears on the **Scheduled searches** page.

## Manage scheduled searches [#manage]

The **Scheduled searches** page in the Administration UI lists all your automated searches, including any you created from the Logs UI. From the  menu, you can view, edit, or delete a search based on your [permissions](#permissions).

## Related topics [#related-topics]

For related information, see:

-   [Learn more about NRQL queries](https://docs.newrelic.com/docs/nrql/get-started/introduction-nrql-new-relics-query-language) to create more sophisticated automated searches.
-   [Configure alert email destinations](https://docs.newrelic.com/docs/alerts-applied-intelligence/notifications/destinations) to expand your notification options.
-   [Explore workflow automation](https://docs.newrelic.com/docs/alerts/get-notified/alert-event-workflows) for more advanced automation possibilities.