---
title: NerdGraph tutorial: Alerts destinations
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-api-notifications-destinations
---

In addition to managing your [alert destinations in the UI](https://docs.newrelic.com/docs/alerts-applied-intelligence/notifications/destinations), you can use our NerdGraph API.

> #### 💡 TIP
>
> For help getting started with NerdGraph, see [Introduction to NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph).

## List and filter destinations [#list-and-filter]

The `destinations` query allows you to paginate through all of your destinations per account. It also allows some filtering functionality.

**Listing all destinations for an account**

Here's an example:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        destinations {
          entities {
            id
            name
          }
          error {
            details
          }
        }
      }
    }
  }
}
```

````

**Paginating through destinations with cursor pagination**

In order to paginate through your destinations, you must request the `nextCursor` field on your initial query.

With cursor pagination, you continue to make a request through the result set until the `nextCursor` that is returned from the response comes back empty. This signifies that you reached the end of your results.

Here's an example:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        destinations(cursor: "") {
          nextCursor
          entities {
            id
            name
          }
          totalCount
        }
      }
    }
  }
}
```

The code above returns a set of results like this:

```json
{
  "data": {
    "actor": {
      "account": {
        "aiNotifications": {
          "destinations": {
            "nextCursor": "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM=",
            "entities": [
              {
                "id": "01c0cbe7-3d70-47c1-99e0-adf906eed6c2",
                "name": "Destination Name"
              },
              {
                "id": "05db0207-c137-4985-8cb5-f21e7e57b8cc",
                "name": "Another Destination Name"
              }
              // ... more destinations here in reality
            ],
            "totalCount": 807
          }
        }
      }
    }
  }
}
```

So, in your subsequent request, provide the cursor like so, until the cursor is empty:

```graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        destinations(cursor: "") {
          nextCursor
          entities {
            id
            name
          }
          totalCount
        }
      }
    }
  }
}
```

````

**Find all destinations by name**

The API allows destination queries by name. The `name` filter returns exact matches and partial matches. It is case insensitive. This will only return the information for the destinations that match the name supplied.

In this example, we want to find destinations with `"DevOps"` in the name:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        destinations(filters: {
          name: "DevOps"
        }) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}
```

````

**Find destination by ID**

The API lets you query by destination ID:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        destinations(filters: {id: YOUR_DESTINATION_ID}) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}
```

````

**Find all destinations by type**

The API lets you query by destination type. The following query will return all email destinations on the chosen account:

````graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        destinations(filters: {type: EMAIL}) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}
```

````

## Create a destination [#create-destination]

In order to create a destination, different inputs must be supplied for each destination type. An optional `two_way_integration` property is available for integrations that allow two-way integration.

**Atlassian Jira**

````graphql
mutation {
  aiNotificationsCreateDestination(accountId: YOUR_ACCOUNT_ID, destination: {
    type: JIRA,
    name: "Destination Name",
    auth: {
      type: BASIC,
      basic: {
        user: YOUR_EMAIL,
        password: YOUR_PASSWORD
      }
    },
    properties: [
      {
        key: "url",
        value: "https://YOUR_INSTANCE.atlassian.net"
      },
      {
        key: "two_way_integration",
        value: "true"
      }
    ]
  }) {
    destination {
      id
      name
    }
  }
}
```

````

**ServiceNow (Incident-Management)**

````graphql
mutation {
  aiNotificationsCreateDestination(accountId: YOUR_ACCOUNT_ID, destination: {
    type: SERVICE_NOW,
    name: "Destination Name",
    auth: {
      type: BASIC,
      basic: {
        user: YOUR_EMAIL,
        password: YOUR_PASSWORD
      }
    },
    properties: [
      {
        key: "url",
        value: "https://YOUR_INSTANCE.service-now.com"
      },
     {
       key: "two_way_integration",
       value: "true"
     }
    ]
  }) {
    destination {
      id
      name
    }
  }
}
```

````

**Slack**

Because our integration with slack is only available with OAuth2 authentication, the destination cannot be created with a mutation.

**Microsoft Teams**

> #### 💡 NOTE
>
> The Microsoft Teams integration is now available in the US, EU, and JP regions.

Before creating a New Relic destination that connects to Microsoft Teams, you must [install the New Relic for Microsoft Teams app](https://docs.newrelic.com/docs/alerts/get-notified/microsoft-teams-integrations/#add-new-relic-for-microsoft-team) in your Microsoft Teams workspace. After installation, you'll receive a security code that is required for this mutation.

````graphql
mutation {
  aiNotificationsCreateDestination(accountId: YOUR_ACCOUNT_ID, destination: {
    type: MICROSOFT_TEAMS,
    name: "Destination Name",
    properties: [
      {
        key: "securityCode",
        value: YOUR_SECURITY_CODE
      }
    ]
  }) {
    destination {
      id
      name
    }
  }
}
```

<Callout variant="important">
  After creating the New Relic destination, obtain the `destinationId` from the response. This ID is required to configure notification channels. See the [Microsoft Teams channel configuration section](/docs/apis/nerdgraph/examples/nerdgraph-api-notifications-channels/#microsoft-teams) for the complete workflow.
</Callout>

````

**Webhook**

In this example, `auth` is optional, depending on the service being integrated.

````graphql
mutation {
  aiNotificationsCreateDestination(accountId: YOUR_ACCOUNT_ID, destination: {
    type: WEBHOOK,
    name: "Destination Name",
    auth: {
      type: BASIC,
      basic: {
        user: YOUR_EMAIL,
        password: YOUR_PASSWORD
      }
    },
    properties: [
      {
        key: "url",
        value: YOUR_WEBHOOK
      },
     {
       key: "two_way_integration",
       value: "true"
     }
    ]
  }) {
    destination {
      id
      name
    }
  }
}
```

````

**Email**

````graphql
mutation {
  aiNotificationsCreateDestination(accountId: YOUR_ACCOUNT_ID, destination: {
    type: EMAIL,
    name: "Destination Name",
    properties: [
      {
        key: "email",
        value: YOUR_EMAIL
      }
    ]
  }) {
    destination {
      id
      name
    }
  }
}
```

````

**AWS EventBridge**

````graphql
mutation {
  aiNotificationsCreateDestination(accountId: YOUR_ACCOUNT_ID, destination: {
    type: EVENT_BRIDGE,
    name: "Destination Name",
    auth: {
      type: BASIC,
      basic: {
        user: YOUR_IAM_USER,
        password: YOUR_PASSWORD
      }
    },
    properties: [
      {
        key: "AWSAccountId",
        value:  YOUR_AWS_ACCOUNT_ID
      },
      {
        key: "AWSRegion",
        value:  YOUR_AWS_REGION
      }
    ]
  }) {
    destination {
      id
      name
    }
  }
}
```

````

**PagerDuty**

PagerDuty has two types of integrations, service level and account level. For more information see the [PagerDuty Integration Docs](https://docs.newrelic.com/docs/alerts-applied-intelligence/notifications/notification-integrations#pagerduty).

Service level:

````graphql
mutation {
  aiNotificationsCreateDestination(accountId: YOUR_ACCOUNT_ID, destination: {
    type: PAGERDUTY_SERVICE_INTEGRATION,
    name: "Destination Name",
    auth: {
      type: TOKEN,
      basic: {
        token: YOUR_INTEGRATION_TOKEN,
        prefix: "Token token="
      }
    },
    properties: []
  }) {
    destination {
      id
      name
    }
  }
}
```

Account level:

```graphql
mutation {
  aiNotificationsCreateDestination(accountId: YOUR_ACCOUNT_ID, destination: {
    type: PAGERDUTY_ACCOUNT_INTEGRATION,
    name: "Destination Name",
    auth: {
      type: TOKEN,
      basic: {
        token: YOUR_API_KEY,
        prefix: "Token token="
      }
    },
    properties: [
      {
        key: "two_way_integration",
        value: "true"
      }
    ]
  }) {
    destination {
      id
      name
    }
  }
}
```

````

## Update a destination [#update-destination]

When you update a destination, note that you don't need to supply all of the attributes on the destination. For example, you only need to supply the name if you only intend to update the name:

```graphql
mutation {
  aiNotificationsUpdateDestination(accountId: YOUR_ACCOUNT_ID, destinationId: YOUR_destination_ID, destination: {
    name: "Updated destination Name"
  }) {
    destination {
      id
      name
    }
  }
}
```

## Testing a destination [#test-destination]

You can test destinations via the NerdGraph API. This can be done before or after creating the destination.

```graphql
mutation {
  aiNotificationsTestDestination(accountId: YOUR_ACCOUNT_ID, destination: {
    type: EMAIL,
    name: "Destination Name",
    properties: [
      {
        key: "email",
        value: YOUR_EMAIL
      }
    ]
  }) {
    error {
      details
    }
    details
    result
  }
}
```

```graphql
mutation {
  aiNotificationsTestDestinationById(accountId: YOUR_ACCOUNT_ID, destinationId: YOUR_DESTINATION_ID) {
    error {
      details
    }
    details
    result
  }
}
```

## Delete a destination [#delete-destination]

You can delete destinations via the NerdGraph API.

```graphql
mutation {
  aiNotificationsDeleteDestination(accountId: YOUR_ACCOUNT_ID, destinationId: YOUR_DESTINATION_ID) {
    ids
    error {
      details
    }
  }
}
```

> #### ⚠️ IMPORTANT
>
> If you receive a failure message stating `Entity type channel is in use`, you will need to identify the channels used by the destination and delete them before proceeding. To accomplish this, first find all the channels associated with the destination, then delete each channel individually.

```graphql
{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      aiNotifications {
        channels(filters: {destinationId: YOUR_DESTINATION_ID}) {
          entities {
            id
            name
          }
        }
      }
    }
  }
}
```

```graphql
mutation {
aiNotificationsDeleteChannel(accountId: YOUR_ACCOUNT_ID, channelId: YOUR_CHANNEL_ID) {
ids
error {
  details
}
}
}
```