API

Introduction

The Scout APM API is currently fairly narrow in scope. It is intended to support 3rd party dashboards, exporting summary data from your applications.

If you have ideas on API enhancements, please contact us at support@scoutapm.com

Authorization

Obtaining a token

  1. Log into the Scout APM website
  2. Go to your organization’s settings
  3. Enter a name (for your use), and obtain a token

Sending Authorization

The key must be provided with every request, via one of several methods:

Response Format

Every endpoint returns a JSON object. The object will at the minimum, have a "header" field with embedded status and message fields. If the endpoint returned results, it will be under a results keys.

{
  "header": {
    "status": {
      "code": 200,
      "message": "OK"
    },
    "apiVersion": "0.1"
  },
  "results": { ... }
}

API Endpoints

Applications

Applications List

/api/v0/apps - returns a list of applications and their ids

Request:

 curl -H "X-SCOUT-API: 8bea3e976f0fa7a40398117dd1e1fe36" "https://scoutapm.com/api/v0/apps"

Results:

"results": {
  "apps": [
    {
      "name": "MyApp Staging",
      "id": 100
    },
    {
      "name": "MyApp Production",
      "id": 101
    }
  ]
}

Application Detail

/api/v0/apps/:id - returns information about a specific application

Request:

 curl -H "X-SCOUT-API: 8bea3e976f0fa7a40398117dd1e1fe36" "https://scoutapm.com/api/v0/apps/101"

Results:

"results": {
  "app": {
    "id": 101,
    "name": "MyApp Production"
  }
}

Metrics

Known Metric List

/api/v0/apps/:id/metrics returns a list of known metric types

Request:

 curl -H "X-SCOUT-API: 8bea3e976f0fa7a40398117dd1e1fe36" "https://scoutapm.com/api/v0/apps/101/metrics"

Results:

"results": {
  "availableMetrics": [
    "response_time",
    "response_time_95th",
    "errors",
    "throughput",
    "queue_time"
  ]
}

Metric Data

/api/v0/apps/:id/metrics/:metric_type - will return a time series dataset for the metric.

Parameters:

These two times must not be more than 2 weeks apart

Request:

 curl -H "X-SCOUT-API: 8bea3e976f0fa7a40398117dd1e1fe36" "https://scoutapm.com/api/v0/apps/101/metrics/response_time?from=2021-03-20T22:00:00Z&to=2021-03-27T21:00:00Z"

Results:

"results": {
  "series": {
    "response_time": [
      [
        "2021-03-20T22:00:00Z",
        90.33333333333333
      ],
      [
        "2021-03-20T23:00:00Z",
        86.87233333333333
      ],
      ...
      [
        "2021-03-27T21:00:00Z",
         112.931111111111
      ]
    ]
  }
}

Time Steps:

When using different durations, we will return different time steps.

In the example above, when looking at a 1 week duration (from=2021-03-20T22:00:00Z, to=2021-03-27T21:00:00Z), we return data in an hourly timestep

Here’s a list of our various durations and timesteps. Once a duration has exceeded a specific time duration, say 90 minutes, we will use the next largest available time duration (3 hours):

Time Step Example
30 min 1 minute from=2021-06-14T01:00:00Z&to=2021-06-14T01:30:00Z
60 min 1 minute from=2021-06-14T02:00:00Z&to=2021-06-14T03:00:00Z
3 hrs 2 minutes from=2021-06-14T03:00:00Z&to=2021-06-14T06:00:00Z
6 hrs 5 minutes from=2021-06-14T07:00:00Z&to=2021-06-14T13:00:00Z
12 hrs 5 minutes from=2021-06-14T14:00:00Z&to=2021-06-15T02:00:00Z
1 day 10 minutes from=2021-06-15T03:00:00Z&to=2021-06-16T03:00:00Z
3 days 30 minutes from=2021-06-16T04:00:00Z&to=2021-06-19T04:00:00Z
7 days 1 hour from=2021-06-19T05:00:00Z&to=2021-06-26T05:00:00Z
14 days 2 hours from=2021-06-26T06:00:00Z&to=2021-07-10T06:00:00Z