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:

• An HTTP Header named X-SCOUT-API
• As part of the JSON request body, as the top level key: key
• A URL query string argument named key

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 key.

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

Application endpoints

/api/v0/apps/:id/endpoints - returns information on an application’s endpoint performance.

Parameters:

• from - start time, ISO8601 formatted
• to - end time, ISO8601 formatted

These two times must not be more than 2 weeks apart. See time steps below.

Request:

 curl -H "X-SCOUT-API: 8bea3e976f0fa7a40398117dd1e1fe36" "https://scoutapm.com/api/v0/apps/101/endpoints?from=2025-02-11T22:00:00Z&to=2025-02-11T23:00:00Z"

Results:

"results": [
  {
    "name":"api/yourendpoint/index",
    "percentage_of_total":20.0,
    "response_time":40.0,
    "throughput":60.0,
    "max_allocations":7000.0,
    "error_rate":0,
    "formatted_method_name":"Api::YourEndpoint#index",
    "link":"/apps/101/endpoints/L2FwaS95b3VyZW5kcG9pbnQvaW5kZXg=",
    "95th_percentile":45.0
    },
]

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",
    "apdex",
  ]
}

Metric Data

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

Parameters:

• from - start time, ISO8601 formatted
• to - end time, ISO8601 formatted

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
      ]
    ]
  }
}

Endpoint Metric Data

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

In this case, :endpoint_id is the base64-encoded value of the endpoint name, which can be obtained from the /apps/:id/endpoints endpoint. It is also the last path-part of the link field in the endpoint results. Time series data is returned in the same format as the /metrics/:metric_type endpoint.

Parameters:

• from - start time, ISO8601 formatted
• to - end time, ISO8601 formatted

These two times must not be more than 2 weeks apart.

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):