NerdGraph API: Alerts policies

You can manage your alerts policies using our GraphQL NerdGraph API. Here are some queries and mutations you can develop in our NerdGraph API explorer.

See the NerdGraph introduction for help getting started with NerdGraph API explorer.

List and filter policies

The policiesSearch query allows you to paginate through all of your policies per account. It also allows some filtering functionality on the account policies.

Listing all policies for an account

Here's an example:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        policiesSearch {
          policies {
            id
            name
            incidentPreference
          }
        }
      }
    }
  }
}
Paginating through policies with cursor pagination

In order to paginate through your policies, 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:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        policiesSearch {
          nextCursor
          policies {
            id
            name
            incidentPreference
          }
          totalCount
        }
      }
    }
  }
}

The code above returns a set of results like this:

{
  "data": {
    "actor": {
      "account": {
        "alerts": {
          "policiesSearch": {
            "nextCursor": "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM=",
            "policies": [
              {
                "id": "3455",
                "incidentPreference": "PER_POLICY",
                "name": "First Policy Name"
              },
              {
                "id": "2123",
                "incidentPreference": "PER_POLICY",
                "name": "Another Policy"
              },
              // ... more policies here in reality
            ],
            "totalCount": 745
          }
        }
      }
    }
  }
}

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

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        policiesSearch(cursor: "/8o0y2qiR54m6thkdgHgwg==:jZTXDFKbTkhKwvMx+CtsPVM=") {
          nextCursor
          policies {
            id
            name
            incidentPreference
          }
          totalCount
        }
      }
    }
  }
}
Find all policies by selected ids

The API allows policy queries by a sub-select of ids. This will only return the information for these policies that you provide.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        policiesSearch(searchCriteria: {
          ids: [A_POLICY_ID, ANOTHER_POLICY_ID]
        }) {
          policies {
            id
            name
            incidentPreference
          }
        }
      }
    }
  }
}
Find policy by id

The API lets you query by policy id:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      alerts {
        policy(id: YOUR_POLICY_ID) {
          id
          name
          incidentPreference
        }
      }
    }
  }
}

Create a policy

In order to create a policy, supply a name and an incidentPreference.

The incident preference will configure how incidents get created for each condition created in the policy. For more information, refer to the documentation about choosing your incident preference.

mutation {
  alertsPolicyCreate(accountId: YOUR_ACCOUNT_ID, policy: {
    name: "Your Policy Name"
    incidentPreference: PER_CONDITION
  }) {
    id
    name
    incidentPreference
  }
}

Update a policy

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

mutation {
  alertsPolicyUpdate(accountId: YOUR_ACCOUNT_ID, id: YOUR_POLICY_ID, policy: {
    name: "Updated Policy Name"
  }) {
    id
    name
    incidentPreference
  }
}

Delete a policy

You can delete policies via the NerdGraph API. Note that only the id may be requested back from a deleted resource:

mutation {
  alertsPolicyDelete(accountId: YOUR_ACCOUNT_ID, id: YOUR_POLICY_ID) {
    id
  }
}

For more help

If you need more help, check out these support and learning resources: