Help Docs ~ Scout Server Monitoring

API

Scout has a cURL-friendly REST API.

API overview

Quickstart

  • Your account key is also an API key. See the authentication section below to manage additional API keys.
  • To get recent alerts: curl https://scoutapp.com/api/v2/KEY/alerts.json
  • To disable notifications on a server: curl --data "notifications=false" https://scoutapp.com/api/v2/KEY/servers/HOSTNAME

HTTP Verbs

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

HTTP Verb
Description

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 Response Codes

Response Code
Description

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."}

Authentication

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

https://scoutapp.com/api/v2/YOUR_KEY_HERE/...

You can find your API keys via the settings area in the Scout UI Navbar:

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 deauthorize it later.

Fetch alerts

curl https://scoutapp.com/api/v2/KEY/alerts.json[?lifecycle=start|end|all]

Parameters

  • lifecycle=[start|end|all]
    • start returns only open alerts
    • end: returns only closed alerts
    • all: returns open and closed alerts. DEFAULT
  • offset=0: results are limited to 50 records, but you can retrieve more by specifying this offset. Specify offset=50 to retrieve the 2nd page.

Results

  • 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|all]
  "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": "https://scoutapp.com/a/999999",
  "sparkline_url":"https://scoutapp.com/alert_sparkline.png"
}

This endpoint will return up to 50 alerts created within the last 30 days. Alerts are restricted to those generated by triggers.

Delete a server

curl -X DELETE https://scoutapp.com/api/v2/KEY/servers/HOSTNAME

Parameters

  • none

Results

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

Add roles

curl -X POST --data "roles=role1,role2" https://scoutapp.com/api/v2/KEY/servers/HOSTNAME/roles/add

Parameters

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

Behavior

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.

Results

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

Enable/disable notifications on a server

curl -X POST --data "notifications=[true|false]" https://scoutapp.com/api/v2/KEY/servers/HOSTNAME

Parameters

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

Results

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

Enable/disable notifications account-wide

Use with care! If you turn notifications off, ensure you turn them back on again, so you don't miss critical notifications.

curl -X POST --data "notifications=[true|false]" https://scoutapp.com/api/v2/KEY/account

Parameters

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

Results

  • 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"  https://scoutapp.com/api/v2/KEY/markers

Parameters

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

Results

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

Adding a marker after a Capistrano deploy

Here's an example of a simple hook to create a marker after a deploy if you are using Capistrano:

after "deploy:restart", "deploy:mark_release_via_api"

task :mark_release_via_api, hosts:"app1.acme.com" do
  run_locally %Q(curl --data "notes=deployed production" https://scoutapp.com/api/v2/API_KEY/markers)
end

Fetching Metrics

You can export data via curl:

curl https://scoutapp.com/api/v2/KEY/metrics.json?server=..&metric_name=..&metric_type=..&metric_source_name=..&display=breakout

Example - fetching a CPU metric

Copy-paste this into your terminal for an example (this will fetch the CPU User % metric across your servers over the past day):

curl "https://scoutapp.com/api/v2/KEY/metrics.json?metric_type=cpu&metric_name=user&display=breakout&duration=1+day"

Example - fetching a StatsD Metric (custom metric)

curl "https://scoutapp.com/api/v2/KEY/metrics.json?metric_type=custom_metric&metric_name=user_signups&metric_source_name=user_signups&display=breakout&duration=1+day"

Parameters

  • environment = environment name (exact match required). DEFAULT: no filtering by environment
  • role = role name (exact match required.) DEFAULT: no filtering by role
  • server = server hostname (exact match, wildcard, or regex ok)
  • duration = one of: "5 hours", "12 hours", "1 day", "1 week", "2 weeks", "1 month", "3 months", "6 months", "1 year". DEFAULT: 5 hours
  • (REQUIRED) metric_name = the non-humanized metric name
  • (REQUIRED)metric_type = cpu|disk|memory|network|process|plugin|custom_metric
  • (REQUIRED) metric_source_name.
    • if plugin, the plugin name.
    • If process, the process name.
    • if disk|network, the volume/interface name
    • if a custom metric, the metric name.
      display = # range|breakout. DEFAULT: range

Results

Results are returned in the following JSON structure:

{
  "timestamps": [1407332100000, 1407332160000, 1407332220000, ...],   # Epoc time with milliseconds. There will be one timestamp for each point below
  "metrics": [{ # it's an array because results can be returned from multiple servers. There will be one hash in this 'metrics' array for each server returning results
    "label": "app1", # the name of the server this metrics block is for
    "units": "",    # units for the metric, if any
    "precision": 1, # preferred precision to display the metric
    "points": [     # there will be one element in this array for each of the timestamps above. Points are correlated to timestamp by position. Each element is a subarray with three elements representing the min, average, and max for that point in time.
      [1.0, 3.5, 6.0],
      [2.0, 19.0, 36.0],
      [1.0, 2.0, 3.0],
      ...
    ]
  }]
}

Examples

Get memory used over the last year for servers matching the regex /app[12].*/:

server=/app[12].*/&metric_type=memory&metric_name=used&display=breakout&duration=1+year

Get network bytes_out metric (eth0 interface only), for servers in the production environment and database role:

metric_type=network&metric_source_name=eth0&metric_name=bytes_out&environment=production&role=database

Get the busy_workers metric from the Apache Load plugin for one specific server:

server=app1.scout.managedmachine.com&metric_name=busy_workers&metric_type=plugin&metric_source_name=Apache+Load&display=breakout

Fetch triggers

You can export data via curl:

curl https://scoutapp.com/api/v2/KEY/triggers.json

Results

  • Standard HTTP status code.
  • {"message":"human-readable message here", "results":[]}. results is an array of triggers, with each member a hash of attributes:
{
  "id":99999999999999999,
  "condition":" when Seconds meets or exceeds 10.0 .",
  "metric":"Seconds",
  "max_value":10.0,
  "low_value":null,
  "duration_in_seconds":0
}

Fetch roles

curl https://scoutapp.com/api/v2/KEY/roles.json

Results

  • Standard HTTP status code.
  • {"message":"human-readable message here", "result":{}}. results is an hash with the role name as key and an array of server hostnames as value:
{
  "All Servers": ["app1", "db1"]
}

API

Scout has a cURL-friendly REST API.