Spans

curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/spans/reports?groupBy=fingerprint&startTime=2024-01-15T00:00:00Z&endTime=2024-01-16T00:00:00Z&type=db.query" \
  -H "Authorization: Bearer your-jwt-token"

const params = new URLSearchParams({
  groupBy: 'fingerprint',
  type: 'db.query',
  startTime: '2024-01-15T00:00:00Z',
  endTime: '2024-01-16T00:00:00Z'
});

const response = await fetch(`https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/spans/reports?${params}`, {
  headers: { 'Authorization': 'Bearer your-jwt-token' }
});

const report = await response.json();

{
  "groupBy": "fingerprint",
  "total": 214,
  "points": [
    {
      "key": "d41d8cd98f00b204",
      "runs": 412000,
      "errorCount": 12,
      "avg_us": 5800,
      "p50_us": 3900,
      "p95_us": 18400,
      "p99_us": 42100,
      "total_us": 2389600000,
      "requests": 41200,
      "runsPerRequest": 10,
      "lastSeen": "2024-01-15T23:59:41Z",
      "sampleType": "db.query",
      "sampleName": "SELECT orders",
      "sampleSystem": "postgresql",
      "sampleHost": "db-primary.internal",
      "sampleDb": "orders",
      "sampleEndpoint": "GET /v1/orders/{id}",
      "sampleStatement": "select * from order_items where order_id = ?",
      "sampleCallSite": "src/services/orders.ts:142:9",
      "sampleCallSiteFn": "loadOrderItems",
      "sampleCallStack": "src/services/orders.ts:142:9|loadOrderItems\nsrc/routes/orders.ts:31:3|getOrder"
    }
  ]
}

curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/spans/reports?groupBy=fingerprint&startTime=2024-01-15T00:00:00Z&endTime=2024-01-16T00:00:00Z&type=db.query" \
  -H "Authorization: Bearer your-jwt-token"

const params = new URLSearchParams({
  groupBy: 'fingerprint',
  type: 'db.query',
  startTime: '2024-01-15T00:00:00Z',
  endTime: '2024-01-16T00:00:00Z'
});

const response = await fetch(`https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/spans/reports?${params}`, {
  headers: { 'Authorization': 'Bearer your-jwt-token' }
});

const report = await response.json();

{
  "groupBy": "fingerprint",
  "total": 214,
  "points": [
    {
      "key": "d41d8cd98f00b204",
      "runs": 412000,
      "errorCount": 12,
      "avg_us": 5800,
      "p50_us": 3900,
      "p95_us": 18400,
      "p99_us": 42100,
      "total_us": 2389600000,
      "requests": 41200,
      "runsPerRequest": 10,
      "lastSeen": "2024-01-15T23:59:41Z",
      "sampleType": "db.query",
      "sampleName": "SELECT orders",
      "sampleSystem": "postgresql",
      "sampleHost": "db-primary.internal",
      "sampleDb": "orders",
      "sampleEndpoint": "GET /v1/orders/{id}",
      "sampleStatement": "select * from order_items where order_id = ?",
      "sampleCallSite": "src/services/orders.ts:142:9",
      "sampleCallSiteFn": "loadOrderItems",
      "sampleCallStack": "src/services/orders.ts:142:9|loadOrderItems\nsrc/routes/orders.ts:31:3|getOrder"
    }
  ]
}

A span is one unit of work inside a request — a query, a cache call, an outbound request. These endpoints aggregate spans across requests, which is how you find the individual operation responsible for a slow endpoint. For request-level time, use the APM API. All span endpoints require a bearer token with metrics read access, and all times are ISO 8601 in UTC. Span types: db.query, redis, cache, http.out, queue, rpc, graphql, custom.

Operation Report

Summarize spans by fingerprint, type, endpoint, name, system, host, database, code location, bucket or environment, with per-group quantiles.

Path Parameters

string

required

Account identifier (format: acc_ followed by 27 alphanumeric characters)

Query Parameters

string

required

One of fingerprint, type, endpoint, name, system, host, db, call_site, bucket_sid, environment_sid

string

required

Start of the window (ISO 8601, UTC)

string

required

End of the window (ISO 8601, UTC)

string

Limit to one bucket

string

Limit to one environment

string

Limit to one normalized endpoint

string

Limit to one span type

string

Limit to one span fingerprint

number

Maximum groups to return (1–1000, default 50)

Response

string

The field the results are grouped by.

number

Number of groups matched.

array

Each entry carries key, runs, errorCount, avg_us, p50_us, p95_us, p99_us, total_us, requests (distinct requests the group ran in), runsPerRequest (high values indicate an N+1), lastSeen, and sample* fields describing a representative span (sampleType, sampleName, sampleSystem, sampleHost, sampleDb, sampleEndpoint, sampleStatement, plus sampleCallSite / sampleCallSiteFn / sampleCallStack, which are empty unless code location capture was on when the spans were recorded). sampleCallStack holds the caller chain innermost first, one file:line:col|function frame per line.

Durations are microseconds (_us) here, unlike the millisecond fields on the request-level APM endpoints — spans are frequently sub-millisecond.

curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/spans/reports?groupBy=fingerprint&startTime=2024-01-15T00:00:00Z&endTime=2024-01-16T00:00:00Z&type=db.query" \
  -H "Authorization: Bearer your-jwt-token"

const params = new URLSearchParams({
  groupBy: 'fingerprint',
  type: 'db.query',
  startTime: '2024-01-15T00:00:00Z',
  endTime: '2024-01-16T00:00:00Z'
});

const response = await fetch(`https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/spans/reports?${params}`, {
  headers: { 'Authorization': 'Bearer your-jwt-token' }
});

const report = await response.json();

{
  "groupBy": "fingerprint",
  "total": 214,
  "points": [
    {
      "key": "d41d8cd98f00b204",
      "runs": 412000,
      "errorCount": 12,
      "avg_us": 5800,
      "p50_us": 3900,
      "p95_us": 18400,
      "p99_us": 42100,
      "total_us": 2389600000,
      "requests": 41200,
      "runsPerRequest": 10,
      "lastSeen": "2024-01-15T23:59:41Z",
      "sampleType": "db.query",
      "sampleName": "SELECT orders",
      "sampleSystem": "postgresql",
      "sampleHost": "db-primary.internal",
      "sampleDb": "orders",
      "sampleEndpoint": "GET /v1/orders/{id}",
      "sampleStatement": "select * from order_items where order_id = ?",
      "sampleCallSite": "src/services/orders.ts:142:9",
      "sampleCallSiteFn": "loadOrderItems",
      "sampleCallStack": "src/services/orders.ts:142:9|loadOrderItems\nsrc/routes/orders.ts:31:3|getOrder"
    }
  ]
}

Operation Trend

Chart one operation over time — runs, distinct requests, errors and latency quantiles. The bucket width is derived from the requested window, so the series stays bounded for any range.

Query Parameters

string

required

Start of the window (ISO 8601, UTC)

string

required

End of the window (ISO 8601, UTC)

string

Span fingerprint to chart. Strongly recommended — it is what keeps the read narrow.

string

Limit to one span type

string

Limit to one normalized endpoint

string

Limit to one bucket

string

Limit to one environment

Response

array

Each entry carries bucket, runs, requests, errorCount, avg_us, p95_us, p99_us and total_us.

curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/spans/timeseries?fingerprint=d41d8cd98f00b204&startTime=2024-01-15T00:00:00Z&endTime=2024-01-16T00:00:00Z" \
  -H "Authorization: Bearer your-jwt-token"

{
  "points": [
    {
      "bucket": "2024-01-15T00:00:00Z",
      "runs": 17200,
      "requests": 1720,
      "errorCount": 0,
      "avg_us": 5400,
      "p95_us": 17800,
      "p99_us": 39000,
      "total_us": 92880000
    }
  ]
}

Drill Back To Requests

The requests a span fingerprint ran in, so you can go from a slow query to a real request and inspect its whole waterfall.

Query Parameters

string

required

Span fingerprint to drill back from

string

required

Start of the window (ISO 8601, UTC)

string

required

End of the window (ISO 8601, UTC)

string

Limit to one normalized endpoint

string

Limit to one bucket

string

Limit to one environment

number

Maximum requests to return (1–1000, default 50)

Response

string

The fingerprint that was queried.

array

Each entry carries request_sid, endpoint, spanCount (times the operation ran in that request), total_us and lastSeen.

curl -X GET "https://api.apitraffic.io/v1/accounts/acc_abc123def456ghi789jkl012/spans?fingerprint=d41d8cd98f00b204&startTime=2024-01-15T00:00:00Z&endTime=2024-01-16T00:00:00Z" \
  -H "Authorization: Bearer your-jwt-token"

{
  "fingerprint": "d41d8cd98f00b204",
  "points": [
    {
      "request_sid": "req_abc123def456ghi789jkl012mno",
      "endpoint": "GET /v1/orders/{id}",
      "spanCount": 42,
      "total_us": 243600,
      "lastSeen": "2024-01-15T23:59:41Z"
    }
  ]
}

API Documentation

Core Resources

Data Management

Automation

Operation Report

Path Parameters

Query Parameters

Response

Operation Trend

Query Parameters

Response

Drill Back To Requests

Query Parameters

Response

​Operation Report

​Path Parameters

​Query Parameters

​Response

​Operation Trend

​Query Parameters

​Response

​Drill Back To Requests

​Query Parameters

​Response

Operation Report

Path Parameters

Query Parameters

Response

Operation Trend

Query Parameters

Response

Drill Back To Requests

Query Parameters

Response