Scout API

API Quick Start

  • Your account key is also an API key. See below to manage additional API keys.
  • To get recent alerts: curl
  • To disable notifications on a server: curl --data "notifications=false"

API Ground Rules

HTTP Verbs

Scout's API conforms to standard HTTP verbs where possible:

GET Used for retrieving resources.
POST Used for creating resources or performing custom actions. Example: adding roles to a server
PATCH Used for partially updating resources with one or more fields. While PATCH is preferred for these cases, endpoints will also accept POST requests.
DELETE Used for deleting resources.

HTTP Return Codes

HTTP 200 OK The request succeeded.
HTTP 404 Not Found A resource you have specified can't be found. The most common cause is a bad hostname.
HTTP 422 Unprocessable Entity The resource is found, but there's something wrong with the parameters you've provided.

JSON Result Hash

Every endpoint returns a JSON hash. The hash will have a message field at a minimum. If the endpoint returns results, it will be under a results field:

{"message":"See here for error messages, etc.", "results":"these are the results you're looking for."}


Scout uses key-based authentication. The key must be included with every request as a part of the base URL:

You already have one API key that is the same as your account key. You can add and remove API keys at any time. If you are using an API key in a 3rd-party application, we recommend creating a separate key — distinct from your account key — in case you need to de-authorize it later.

Fetch Alerts



  • lifecycle=start: returns only open alerts
  • lifecycle=end: returns only closed alerts
  • lifecycle=oneoff: returns only alerts that are simple messages, without an open/closed state. Alerts generated internally by plugins are one-offs
  • lifecycle=all: returns all alerts. DEFAULT


  • Standard HTTP status code.
  • {"message":"human-readable message here", "results":[]}. results is an array of alerts, with each member a hash of attributes:
  "id": 999999,
  "time": "2012-03-05T15:36:51Z",
  "server_name": "Blade",
  "server_hostname": "blade",
  "lifecycle": "start", // can be [start|end|oneoff]  -- "oneoff" is for alerts generated internally by plugins
  "title": "Last minute met or exceeded 3.00 , increasing to 3.50 at 01:06AM",
  "plugin_name": "Load Average",
  "metric_name": "last_minute", // will be nil for alerts generated internally by plugins
  "metric_value": 3.5, // will be nil for alerts generated internally by plugins
  "url": "",

This endpoint will return up to 50 alerts created within the last 30 days.

Add Roles

curl -X POST --data "roles=role1,role2"


  • roles=role1,role2,...: a comma-separated list of role names


For each role:

  • if the server already belongs to the role, nothing changes
  • if the role exists but the server doesn't belong to it, add the server to the role
  • if the role doesn't exist yet, create the empty role and add the server to it.


  • Standard HTTP status code.
  • {"message":"human-readable message here"}

Enable/Disable Notifications on a Server

curl -X POST --data "notifications=[true|false]"


  • notifications=[true|false]: whether you want notifications on or off


  • Standard HTTP status code.
  • {"message":"human-readable message here"}

Delete a Server

curl -X DELETE


  • none


  • Standard HTTP status code.
  • {"message":"human-readable message here"}

Add a Marker

Markers appear on charts. Use them to note significant events like production deploys, performance enhancements, etc. Example:

curl -X POST --data "notes=your text"


  • notes=your text: the text you want to display with the marker


  • Standard HTTP status code.
  • {"message":"human-readable message here"}

Need Something More?

If there's something not listed here you would like to do with the API, send us a message at

HomeFeaturesPricing & SignupPluginsAPIHelpBlogTwitterAbout