Back to Details

scout-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scout APM API

Scout APM API

Query application performance monitoring data from Scout APM using the REST API.
使用REST API从Scout APM查询应用性能监控数据。

When to Use

适用场景

  • Investigating slow endpoints or response time regressions
  • Listing applications and their metrics (apdex, throughput, error rate, p95)
  • Fetching traces for a specific endpoint
  • Reviewing error groups and individual error stacktraces
  • Checking insights: N+1 queries, memory bloat, slow queries
Do not use for configuring Scout agents or instrumenting code — this is the read-only reporting API.
  • 排查慢端点或响应时间退化问题
  • 列出应用及其指标（apdex、吞吐量、错误率、p95）
  • 获取特定端点的链路追踪（traces）数据
  • 查看错误组和单个错误的堆栈跟踪
  • 查看性能洞察：N+1查询、内存膨胀、慢查询
请勿用于配置Scout Agent或代码插桩——这是一个只读的报表API。

Setup

配置步骤

API Key

API密钥

  1. Log into Scout APM
  2. Go to organization settings
  3. Create a named API token
  4. Export it in your shell profile:
bash
export SCOUT_API_KEY="your-token-here"
  1. 登录Scout APM
  2. 进入组织设置
  3. 创建一个命名的API令牌
  4. 在Shell配置文件中导出该令牌：
bash
export SCOUT_API_KEY="your-token-here"

Base URL

基础URL

https://scoutapm.com/api/v0
https://scoutapm.com/api/v0

Authentication

认证方式

Every request must include the key via one of:
  • Header: 
    X-SCOUT-API: $SCOUT_API_KEY
  • Query param: 
    ?key=$SCOUT_API_KEY
All examples below use the header approach.
每个请求必须通过以下任意一种方式携带密钥：
  • 请求头：
    X-SCOUT-API: $SCOUT_API_KEY
  • 查询参数：
    ?key=$SCOUT_API_KEY
以下所有示例均使用请求头方式。

Quick Reference

快速参考

bash
undefined
bash
undefined

List apps

List apps

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY" "https://scoutapm.com/api/v0/apps"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY" "https://scoutapm.com/api/v0/apps"

App details

App details

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY" "https://scoutapm.com/api/v0/apps/{id}"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY" "https://scoutapm.com/api/v0/apps/{id}"

Available metrics for an app

Available metrics for an app

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY" "https://scoutapm.com/api/v0/apps/{id}/metrics"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY" "https://scoutapm.com/api/v0/apps/{id}/metrics"

Metric time-series (requires from/to)

Metric time-series (requires from/to)

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/metrics/{metric_type}?from=2026-02-18T00:00:00Z&to=2026-02-19T00:00:00Z"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/metrics/{metric_type}?from=2026-02-18T00:00:00Z&to=2026-02-19T00:00:00Z"

List endpoints (requires from/to)

List endpoints (requires from/to)

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints?from=2026-02-18T00:00:00Z&to=2026-02-19T00:00:00Z"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints?from=2026-02-18T00:00:00Z&to=2026-02-19T00:00:00Z"

Endpoint metrics (endpoint is base64-url-encoded)

Endpoint metrics (endpoint is base64-url-encoded)

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints/{endpoint_b64}/metrics/{metric_type}?from=...&to=..."
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints/{endpoint_b64}/metrics/{metric_type}?from=...&to=..."

List traces for endpoint (max 100, within 7 days)

List traces for endpoint (max 100, within 7 days)

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints/{endpoint_b64}/traces?from=...&to=..."
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints/{endpoint_b64}/traces?from=...&to=..."

Trace detail (includes spans)

Trace detail (includes spans)

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/traces/{trace_id}"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/traces/{trace_id}"

Error groups (max 100, within 30 days)

Error groups (max 100, within 30 days)

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/error_groups?from=...&to=..."
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/error_groups?from=...&to=..."

Error group detail (includes latest_error with stacktrace)

Error group detail (includes latest_error with stacktrace)

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/error_groups/{error_id}"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/error_groups/{error_id}"

Individual errors in a group (max 100)

Individual errors in a group (max 100)

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/error_groups/{error_id}/errors"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/error_groups/{error_id}/errors"

All insights (cached 5 min)

All insights (cached 5 min)

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights"

Insights by type: n_plus_one | memory_bloat | slow_query

Insights by type: n_plus_one | memory_bloat | slow_query

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights/{type}?limit=20"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights/{type}?limit=20"

Insights history (cursor-paginated)

Insights history (cursor-paginated)

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights/history?from=...&to=...&limit=10"
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights/history?from=...&to=...&limit=10"

Insights history by type

Insights history by type

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights/history/{type}?from=...&to=...&limit=10"
undefined
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights/history/{type}?from=...&to=...&limit=10"
undefined

Endpoints Reference

端点参考

Applications

应用管理

MethodPathDescription
GET
/apps
List all apps
GET
/apps/{id}
Get app details
方法路径描述
GET
/apps
列出所有应用
GET
/apps/{id}
获取应用详情

Metrics

指标数据

MethodPathParamsDescription
GET
/apps/{id}/metrics
—List available metric types
GET
/apps/{id}/metrics/{metric_type}
from
, 
to
Time-series data for a metric
Metric types: 
apdex
, 
response_time
, 
response_time_95th
, 
errors
, 
throughput
, 
queue_time
方法路径参数描述
GET
/apps/{id}/metrics
—列出可用的指标类型
GET
/apps/{id}/metrics/{metric_type}
from
, 
to
获取指标的时间序列数据
Metric types: 
apdex
, 
response_time
, 
response_time_95th
, 
errors
, 
throughput
, 
queue_time

Endpoints

端点管理

MethodPathParamsDescription
GET
/apps/{id}/endpoints
from
, 
to
List endpoints with stats
GET
/apps/{id}/endpoints/{endpoint}/metrics/{metric_type}
from
, 
to
Metric data for one endpoint
Endpoint encoding: The 
{endpoint}
path segment must be Base64 URL-encoded.
bash
undefined
方法路径参数描述
GET
/apps/{id}/endpoints
from
, 
to
列出带有统计数据的端点
GET
/apps/{id}/endpoints/{endpoint}/metrics/{metric_type}
from
, 
to
获取单个端点的指标数据
Endpoint encoding: The 
{endpoint}
path segment must be Base64 URL-encoded.
bash
undefined

Encode "UsersController#index" → base64

Encode "UsersController#index" → base64

echo -n "UsersController#index" | base64
echo -n "UsersController#index" | base64

VXNlcnNDb250cm9sbGVyI2luZGV4

VXNlcnNDb250cm9sbGVyI2luZGV4

undefined
undefined

Traces

链路追踪（Traces）

MethodPathParamsDescription
GET
/apps/{id}/endpoints/{endpoint}/traces
from
, 
to
List traces (max 100, 7-day window)
GET
/apps/{id}/traces/{trace_id}
—Trace detail with spans
Trace detail includes: 
id
, 
time
, 
total_call_time
, 
mem_delta
, 
metric_name
, 
uri
, 
context
, 
git_sha
, 
allocations_count
, 
limited
, 
spans[]
. V2 traces also include 
transaction_id
and 
hostname
.
方法路径参数描述
GET
/apps/{id}/endpoints/{endpoint}/traces
from
, 
to
列出链路追踪数据（最多100条，时间窗口7天）
GET
/apps/{id}/traces/{trace_id}
—获取包含调用链（spans）的链路追踪详情
Trace detail includes: 
id
, 
time
, 
total_call_time
, 
mem_delta
, 
metric_name
, 
uri
, 
context
, 
git_sha
, 
allocations_count
, 
limited
, 
spans[]
. V2 traces also include 
transaction_id
and 
hostname
.

Errors

错误管理

MethodPathParamsDescription
GET
/apps/{id}/error_groups
from
, 
to
, 
endpoint
(optional, base64)		List error groups (max 100, 30-day window)
GET
/apps/{id}/error_groups/{error_id}
—Error group detail + latest error
GET
/apps/{id}/error_groups/{error_id}/errors
—Individual errors (max 100)
Each error includes: 
message
, 
created_at
, 
request_params
, 
request_uri
, 
location
, 
request_session
, 
trace
(stacktrace lines), 
context
.
方法路径参数描述
GET
/apps/{id}/error_groups
from
, 
to
, 
endpoint
（可选，Base64编码）		列出错误组（最多100条，时间窗口30天）
GET
/apps/{id}/error_groups/{error_id}
—获取错误组详情及最新错误
GET
/apps/{id}/error_groups/{error_id}/errors
—获取组内的单个错误（最多100条）
Each error includes: 
message
, 
created_at
, 
request_params
, 
request_uri
, 
location
, 
request_session
, 
trace
(stacktrace lines), 
context
.

Insights

性能洞察

MethodPathParamsDescription
GET
/apps/{id}/insights
limit
All insight types (cached 5 min)
GET
/apps/{id}/insights/{type}
limit
Single insight type
GET
/apps/{id}/insights/history
from
, 
to
, 
limit
, 
pagination_cursor
, 
pagination_direction
, 
pagination_page
Historical insights
GET
/apps/{id}/insights/history/{type}
(same as above)Historical insights by type
Insight types: 
n_plus_one
, 
memory_bloat
, 
slow_query
Pagination: Cursor-based. Response includes 
pagination.has_more
, 
pagination.pagination_cursor
, and 
pagination.next_pagination_page
. Pass 
pagination_direction=forward
(default) or 
backward
.
方法路径参数描述
GET
/apps/{id}/insights
limit
获取所有类型的性能洞察（缓存5分钟）
GET
/apps/{id}/insights/{type}
limit
获取单一类型的性能洞察
GET
/apps/{id}/insights/history
from
, 
to
, 
limit
, 
pagination_cursor
, 
pagination_direction
, 
pagination_page
获取历史性能洞察
GET
/apps/{id}/insights/history/{type}
（同上）获取指定类型的历史性能洞察
Insight types: 
n_plus_one
, 
memory_bloat
, 
slow_query
Pagination: Cursor-based. Response includes 
pagination.has_more
, 
pagination.pagination_cursor
, and 
pagination.next_pagination_page
. Pass 
pagination_direction=forward
(default) or 
backward
.

Time Steps

时间步长

Duration determines the resolution of returned time-series data:
DurationStep
≤ 60 min1 minute
≤ 3 hrs2 minutes
≤ 12 hrs5 minutes
≤ 1 day10 minutes
≤ 3 days30 minutes
≤ 7 days1 hour
≤ 14 days2 hours
时间范围决定了返回的时间序列数据的分辨率：
时间范围步长
≤ 60分钟1分钟
≤ 3小时2分钟
≤ 12小时5分钟
≤ 1天10分钟
≤ 3天30分钟
≤ 7天1小时
≤ 14天2小时

Response Format

响应格式

All responses follow a standard envelope:
json
{
  "header": {
    "status": { "code": 200, "message": "OK" },
    "apiVersion": "0.1"
  },
  "results": { ... }
}
Error responses use the same envelope with codes 
403
(bad key), 
404
(not found), or 
422
(bad params).
所有响应均遵循标准的封装格式：
json
{
  "header": {
    "status": { "code": 200, "message": "OK" },
    "apiVersion": "0.1"
  },
  "results": { ... }
}
Error responses use the same envelope with codes 
403
(bad key), 
404
(not found), or 
422
(bad params).

Workflow: Investigate a Slow Endpoint

工作流：排查慢端点

bash
undefined
bash
undefined

1. Find the app

1. Find the app

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY" "https://scoutapm.com/api/v0/apps" | jq '.results.apps[] | {id, name}'
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY" "https://scoutapm.com/api/v0/apps" | jq '.results.apps[] | {id, name}'

2. List endpoints sorted by response time (last 24h)

2. List endpoints sorted by response time (last 24h)

FROM=$(date -u -v-1d +%Y-%m-%dT%H:%M:%SZ) # macOS TO=$(date -u +%Y-%m-%dT%H:%M:%SZ) curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints?from=$FROM&to=$TO"
| jq '.results | sort_by(-.response_time) | .[:10] | .[] | {name, response_time, throughput, error_rate}'
FROM=$(date -u -v-1d +%Y-%m-%dT%H:%M:%SZ) # macOS TO=$(date -u +%Y-%m-%dT%H:%M:%SZ) curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints?from=$FROM&to=$TO"
| jq '.results | sort_by(-.response_time) | .[:10] | .[] | {name, response_time, throughput, error_rate}'

3. Get p95 response time series for the slowest endpoint

3. Get p95 response time series for the slowest endpoint

ENDPOINT_B64=$(echo -n "Controller#action" | base64) curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints/$ENDPOINT_B64/metrics/response_time_95th?from=$FROM&to=$TO"
ENDPOINT_B64=$(echo -n "Controller#action" | base64) curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints/$ENDPOINT_B64/metrics/response_time_95th?from=$FROM&to=$TO"

4. Pull traces to find the slow requests

4. Pull traces to find the slow requests

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints/$ENDPOINT_B64/traces?from=$FROM&to=$TO"
| jq '.results.traces | sort_by(-.total_call_time) | .[:5]'
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/endpoints/$ENDPOINT_B64/traces?from=$FROM&to=$TO"
| jq '.results.traces | sort_by(-.total_call_time) | .[:5]'

5. Inspect the slowest trace's spans

5. Inspect the slowest trace's spans

TRACE_ID=12345 curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/traces/$TRACE_ID"
| jq '.results.trace.spans'
undefined
TRACE_ID=12345 curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/traces/$TRACE_ID"
| jq '.results.trace.spans'
undefined

Workflow: Review Errors

工作流：查看错误

bash
undefined
bash
undefined

1. List error groups (last 7 days)

1. List error groups (last 7 days)

FROM=$(date -u -v-7d +%Y-%m-%dT%H:%M:%SZ) TO=$(date -u +%Y-%m-%dT%H:%M:%SZ) curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/error_groups?from=$FROM&to=$TO"
| jq '.results.error_groups | sort_by(-.errors_count) | .[:10] | .[] | {id, name, message, errors_count, last_error_at}'
FROM=$(date -u -v-7d +%Y-%m-%dT%H:%M:%SZ) TO=$(date -u +%Y-%m-%dT%H:%M:%SZ) curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/error_groups?from=$FROM&to=$TO"
| jq '.results.error_groups | sort_by(-.errors_count) | .[:10] | .[] | {id, name, message, errors_count, last_error_at}'

2. Get detail + latest stacktrace

2. Get detail + latest stacktrace

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/error_groups/{error_id}"
| jq '.results.error_group | {name, message, status, errors_count, latest_error}'
undefined
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/error_groups/{error_id}"
| jq '.results.error_group | {name, message, status, errors_count, latest_error}'
undefined

Workflow: Check Insights

工作流：查看性能洞察

bash
undefined
bash
undefined

Quick overview — are there N+1s, memory bloat, or slow queries?

Quick overview — are there N+1s, memory bloat, or slow queries?

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights"
| jq '.results.insights | to_entries[] | {type: .key, count: .value.count, new: .value.new_count}'
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights"
| jq '.results.insights | to_entries[] | {type: .key, count: .value.count, new: .value.new_count}'

Drill into N+1 queries

Drill into N+1 queries

curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights/n_plus_one?limit=10"
undefined
curl -sS -H "X-SCOUT-API: $SCOUT_API_KEY"
"https://scoutapm.com/api/v0/apps/{id}/insights/n_plus_one?limit=10"
undefined

Common Pitfalls

常见误区

  • Missing 
    from
    /
    to
    params     — most endpoints require ISO 8601 timestamps; omitting them returns 422
  • Endpoint encoding — the 
    {endpoint}
    path segment must be base64-encoded; raw strings like 
    Users#index
    will 404
  • Trace time window — traces endpoint is limited to a 7-day window
  • Error group time window — error_groups endpoint is limited to 30 days
  • Insights cache — current insights are cached for 5 minutes; don't poll more frequently
  • Max results — traces and error lists cap at 100 items; no built-in pagination for those endpoints
  • Time step granularity — you don't control it; it's determined by the duration of your 
    from
    /
    to
    window (see Time Steps table)
  • 缺少
    from
    /
    to
    参数    ——大多数端点需要ISO 8601格式的时间戳；省略这些参数会返回422错误
  • 端点编码问题——
    {endpoint}
    路径段必须进行Base64编码；直接使用
    Users#index
    这类原始字符串会返回404错误
  • 链路追踪时间窗口——traces端点的时间窗口限制为7天
  • 错误组时间窗口——error_groups端点的时间窗口限制为30天
  • 性能洞察缓存——当前性能洞察数据会缓存5分钟；请勿过于频繁地轮询
  • 最大结果数限制——链路追踪和错误列表最多返回100条数据；这些端点没有内置分页功能
  • 时间步长粒度——无法手动控制时间步长；它由
    from
    /
    to
    的时间范围决定（参见时间步长表格）