Pivot alerts API

You can use the Pivot alerts API to create, read, modify, and delete alerts.

Pivot must be running in native users mode.

Get all alerts

Returns details of all alerts.

URL

GET /api/v1/alerts

Success response

Code	Description
200	`"status": "ok"`

Sample request

curl -X GET 'http://PIVOT_URL/api/v1/alerts' \
--header 'x-imply-api-token:<token>'

Sample response

Show sample response

{
  "alerts":[
    {
      "name":"KTTM",
      "owner":"admin@example.com",
      "title":"KTTM daily alert",
      "dataCube":"kttm784e",
      "checkFrequency":"PT1M",
      "timeFrame":"PT1M",
      "filter":{
        
      },
      "conditions":[
        {
          "type":"value",
          "measure":"count",
          "condition":"lessThan",
          "value":121
        }
      ],
      "readAccess":{
        "access":"specific"
      },
      "recipients":{
        "access":"single",
        "users":[
          "admin@example.com"
        ]
      },
      "admins":{
        "access":"single",
        "users":[
          "admin@example.com"
        ]
      },
      "webhooks":[
        
      ],
      "latestDataStrategyOverride":"query-floored-P1D",
      "exampleQuery":"SELECT\n(COUNT(*)) AS \"__VALUE__\"\nFROM \"kttm\" AS t\nWHERE (TIMESTAMP '2024-08-15 09:48:49.320'<=CAST(t.\"__time\" AS TIMESTAMP) AND CAST(t.\"__time\" AS TIMESTAMP)<TIMESTAMP '2024-08-15 09:49:49.320')\nGROUP BY ()"
    },
    {
      "name":"Wikipedia",
      "owner":"admin@example.com",
      "title":"Wikipedia alert",
      "dataCube":"wikipedia6e62",
      "checkFrequency":"PT1M",
      "type":"overall",
      "timeFrame":"PT1M",
      "filter":{
        "clauses":[
          {
            "dimension":"__time",
            "action":"overlap",
            "dynamic":{
              "op":"timeRange",
              "operand":{
                "op":"ref",
                "name":"m"
              },
              "duration":"P1D",
              "step":-1,
              "bounds":"[)"
            }
          },
          {
            "dimension":"channel",
            "action":"overlap",
            "values":{
              "setType":"STRING",
              "elements":[
                "#en.wikipedia"
              ]
            },
            "exclude":false,
            "mvFilterOnly":false
          },
          {
            "dimension":"cityName",
            "action":"overlap",
            "values":{
              "setType":"STRING",
              "elements":[
                "New York"
              ]
            },
            "exclude":false,
            "mvFilterOnly":false
          }
        ]
      },
      "splits":[
        {
          "dimension":"added",
          "bucketAction":{
            "op":"numberBucket",
            "size":10
          },
          "sortType":"dimension",
          "direction":"ascending"
        }
      ],
      "conditions":[
        {
          "type":"percent-delta",
          "measure":"count",
          "condition":"greaterThan",
          "value":"1"
        }
      ],
      "severity":"warning",
      "readAccess":{
        "access":"specific"
      },
      "recipients":{
        "access":"specific",
        "users":[
          "admin@example.com"
        ],
        "roles":[
          "data-manager"
        ]
      },
      "admins":{
        "access":"single",
        "users":[
          "admin@example.com"
        ]
      },
      "webhooks":[
        {
          "type":"slack",
          "url":"https://hooks.slack.com/services/T000/B000",
          "payload":"{\n    \"attachments\": [\n      {\n        \"fallback\": \"%title%\",\n        \"color\": \"%color%\",\n        \"title\": \"%title%\",\n        \"title_link\": \"%link%\",\n        \"text\": \"%summary%\",\n        \"summaryData\": %summaryData%,\n        \"ts\": %triggerDate%,\n        \"footer\": \"%footer%\",\n        \"footer_icon\": \"https://imply.io/favicon/apple-touch-icon.png\",\n        \"checkFrequency\": \"%checkFrequency%\",\n        \"timeFrame\": \"%timeFrame%\"\n      }\n    ]\n}"
        }
      ],
      "compare":{
        "type":"relative",
        "duration":"PT1M"
      },
      "latestDataStrategyOverride":"inherit",
      "exampleQuery":"SELECT\n(COUNT(*) FILTER (WHERE (TIMESTAMP '2024-08-15 10:08:47.240'<=CAST(t.\"__time\" AS TIMESTAMP) AND CAST(t.\"__time\" AS TIMESTAMP)<TIMESTAMP '2024-08-15 10:09:47.240'))) AS \"count\",\n(COUNT(*) FILTER (WHERE (TIMESTAMP '2024-08-15 10:07:47.240'<=CAST(t.\"__time\" AS TIMESTAMP) AND CAST(t.\"__time\" AS TIMESTAMP)<TIMESTAMP '2024-08-15 10:08:47.240'))) AS \"_cmp_count\"\nFROM \"wikipedia\" AS t\nWHERE (((TIMESTAMP '2024-08-15 10:07:47.240'<=CAST(t.\"__time\" AS TIMESTAMP) AND CAST(t.\"__time\" AS TIMESTAMP)<TIMESTAMP '2024-08-15 10:09:47.240') AND (CAST(t.\"channel\" AS VARCHAR)='#en.wikipedia')) AND (CAST(t.\"cityName\" AS VARCHAR)='New York'))\nGROUP BY ()"
    }
  ]
}

Alert example query

exampleQuery in the response evaluates to true or false. This allows you to copy an example query, customize it, and run it to determine whether it would trigger the alert (true) or not (false).

Get an alert

Returns details of an alert with a specified name.

URL

GET /api/v1/alerts/{name}

Success response

Code	Description
200	`"status": "ok"`

Sample error response

Code	Example body
404 Not Found	`"error": "This alert does not exist."`

Sample request

curl -X GET 'http://PIVOT_URL/api/v1/alerts/KTTM' \
--header 'x-imply-api-token:<token>'

Sample response

Show sample response

{
  "alert":{
    "name":"KTTM",
    "owner":"admin@example.com",
    "title":"KTTM daily alert",
    "dataCube":"kttm784e",
    "checkFrequency":"PT1M",
    "timeFrame":"PT1M",
    "filter":{
      
    },
    "conditions":[
      {
        "type":"value",
        "measure":"count",
        "condition":"lessThan",
        "value":121
      }
    ],
    "readAccess":{
      "access":"specific"
    },
    "recipients":{
      "access":"single",
      "users":[
        "admin@example.com"
      ]
    },
    "admins":{
      "access":"single",
      "users":[
        "admin@example.com"
      ]
    },
    "webhooks":[
      
    ],
    "latestDataStrategyOverride":"query-floored-P1D",
    "exampleQuery":"SELECT\n(COUNT(*)) AS \"__VALUE__\"\nFROM \"kttm\" AS t\nWHERE (TIMESTAMP '2024-08-15 09:48:49.320'<=CAST(t.\"__time\" AS TIMESTAMP) AND CAST(t.\"__time\" AS TIMESTAMP)<TIMESTAMP '2024-08-15 09:49:49.320')\nGROUP BY ()"
  }
}

Create an alert

Creates an alert with a specified name.

URL

POST /api/v1/alerts

Sample request

Show sample request

curl -X POST 'http://PIVOT_URL/api/v1/alerts' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "alert":{
    "name":"Wikipedia",
    "owner":"admin@example.com",
    "title":"Wikipedia monthly alert",
    "dataCube":"wikipedia",
    "checkFrequency":"P1M",
    "type":"within-split",
    "timeFrame":"P1M",
    "filter":{
      
    },
    "splits":[
      {
        "dimension":"isAnonymous",
        "sortType":"measure",
        "direction":"descending"
      }
    ],
    "conditions":[
      {
        "type":"percent-delta",
        "measure":"sum_added",
        "condition":"lessThan",
        "value":121
      }
    ],
    "severity":"warning",
    "readAccess":{
      "access":"specific"
    },
    "recipients":{
      "access":"single",
      "users":[
        "analyst@example.com"
      ]
    },
    "admins":{
      "access":"all"
    },
    "webhooks":[
      {
        "type":"slack",
        "url":"https://hooks.slack.com/services/T000/B000",
        "payload":"{\n    \"attachments\": [\n      {\n        \"fallback\": \"%title%\",\n        \"color\": \"%color%\",\n        \"title\": \"%title%\",\n        \"title_link\": \"%link%\",\n        \"text\": \"%summary%\",\n        \"summaryData\": %summaryData%,\n        \"ts\": %triggerDate%,\n        \"footer\": \"%footer%\",\n        \"footer_icon\": \"https://imply.io/favicon/apple-touch-icon.png\"\n      }\n    ]\n}"
      }
    ],
    "compare":{
      "type":"relative",
      "duration":"P30D"
    }
  }
}'

Success response

Code	Description
200	`"status": "ok"`

Sample error response

Code	Example body
400 Bad Request	`"error": "name must be defined"`

Sample response

Show sample response

{
  "status":"ok",
  "message":"Created successfully",
  "alert":{
    "name":"Wiki",
    "owner":"admin@example.com",
    "title":"Wikipedia monthly alert",
    "dataCube":"wikipedia",
    "checkFrequency":"P1M",
    "type":"within-split",
    "timeFrame":"P1M",
    "filter":{
      
    },
    "splits":[
      {
        "dimension":"isAnonymous",
        "sortType":"measure",
        "direction":"descending"
      }
    ],
    "conditions":[
      {
        "type":"percent-delta",
        "measure":"sum_added",
        "condition":"lessThan",
        "value":121
      }
    ],
    "severity":"warning",
    "readAccess":{
      "access":"specific"
    },
    "recipients":{
      "access":"single",
      "users":[
        "analyst@example.com"
      ]
    },
    "admins":{
      "access":"all"
    },
    "webhooks":[
      {
        "type":"slack",
        "url":"https://hooks.slack.com/services/T000/B000",
        "payload":"{\n    \"attachments\": [\n      {\n        \"fallback\": \"%title%\",\n        \"color\": \"%color%\",\n        \"title\": \"%title%\",\n        \"title_link\": \"%link%\",\n        \"text\": \"%summary%\",\n        \"summaryData\": %summaryData%,\n        \"ts\": %triggerDate%,\n        \"footer\": \"%footer%\",\n        \"footer_icon\": \"https://imply.io/favicon/apple-touch-icon.png\"\n      }\n    ]\n}"
      }
    ],
    "compare":{
      "type":"relative",
      "duration":"P30D"
    }
  }
}

Update an alert

Updates the details of an alert with a specified name.

URL

POST /api/v1/alerts/{name}

Sample request

The following request updates the owner and title properties of the alert object with name KTTM. The name in the request body must match the {name} in the URL. You can't update the name field.

At a minimum, you must provide dataCube, checkFrequency, and conditions in the alert body. You must provide all alert properties you want to retain in the alert, even if you don't want to update them. Pivot recreates the alert with the details you specify in the request.

curl -X POST 'http://PIVOT_URL/api/v1/alerts/KTTM' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "alert":{
    "name":"KTTM",
    "owner":"my-user@example.com",
    "title":"KTTM daily alert - July 2024+",
    "dataCube":"kttm784e",
    "checkFrequency":"PT1M",
    "timeFrame":"PT1M",
    "filter":{
      
    },
    "conditions":[
      {
        "type":"value",
        "measure":"count",
        "condition":"lessThan",
        "value":121
      }
    ],
    "readAccess":{
      "access":"specific"
    },
    "recipients":{
      "access":"single",
      "users":[
        "admin@example.com"
      ]
    },
    "admins":{
      "access":"single",
      "users":[
        "admin@aexample.com"
      ]
    }
  }
}'

Success response

Code	Description
200	`"status": "ok"`

Sample error response

Code	Example body
400 Bad Request	`"error": "the name you entered does not match"`

Sample response

{
  "status":"ok",
  "message":"Updated successfully",
  "alert":{
    "name":"KTTM",
    "owner":"my-user@example.com",
    "title":"KTTM daily alert - July 2024+",
    "dataCube":"kttm784e",
    "checkFrequency":"PT1M",
    "timeFrame":"PT1M",
    "filter":{
      
    },
    "conditions":[
      {
        "type":"value",
        "measure":"count",
        "condition":"lessThan",
        "value":121
      }
    ],
    "readAccess":{
      "access":"specific"
    },
    "recipients":{
      "access":"single",
      "users":[
        "admin@example.com"
      ]
    },
    "admins":{
      "access":"single",
      "users":[
        "admin@example.com"
      ]
    }
  }
}

Delete an alert

Deletes an alert with a specified name.

URL

DELETE /api/v1/alerts/{name}

Sample request

curl -X DELETE 'http://PIVOT_URL/api/v1/alerts/KTTM' \
--header 'x-imply-api-token:<token>'

Success response

Code	Description
200	`"status": "ok"`

Sample error response

Code	Example body
404 Not Found	`"error": "This alert does not exist. Please check the name again."`

Sample response

{
    "status": "ok",
    "message": "Deleted successfully"
}

Get all alerts​

URL​

Success response​

Sample request​

Sample response​

Alert example query​

Get an alert​

URL​

Success response​

Sample error response​

Sample request​

Sample response​

Create an alert​

URL​

Sample request​

Success response​

Sample error response​

Sample response​

Update an alert​

URL​

Sample request​

Success response​

Sample error response​

Sample response​

Delete an alert​

URL​

Sample request​

Success response​

Sample error response​

Sample response​

Get all alerts

URL

Success response

Sample request

Sample response

Alert example query

Get an alert

URL

Success response

Sample error response

Sample request

Sample response

Create an alert

URL

Sample request

Success response

Sample error response

Sample response

Update an alert

URL

Sample request

Success response

Sample error response

Sample response

Delete an alert

URL

Sample request

Success response

Sample error response

Sample response