> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apitraffic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Spans

> Aggregate APM operations, chart one of them over time, and drill back to the requests that ran it

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](https://docs.apitraffic.io/api-reference/apm.md).

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

<api-endpoint method="GET" url="https://api.apitraffic.io/v1/accounts/{accountSid}/spans/reports" />

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

### Path Parameters

**accountSid** `string` *required*

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

### Query Parameters

**groupBy** `string` *required*

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

**startTime** `string` *required*

Start of the window (ISO 8601, UTC)

**endTime** `string` *required*

End of the window (ISO 8601, UTC)

**bucketSid** `string`

Limit to one bucket

**environmentSid** `string`

Limit to one environment

**endpoint** `string`

Limit to one normalized endpoint

**type** `string`

Limit to one span type

**fingerprint** `string`

Limit to one span fingerprint

**limit** `number`

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

### Response

**groupBy** `string`

The field the results are grouped by.

**total** `number`

Number of groups matched.

**points** `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](https://docs.apitraffic.io/apm/capture-settings.md#code-location) was on when the spans were
recorded). `sampleCallStack` holds the caller chain innermost first, one `file:line:col|function`
frame per line.

> [!NOTE]
>
> Durations are microseconds (`_us`) here, unlike the millisecond fields on the request-level
> [APM endpoints](https://docs.apitraffic.io/api-reference/apm.md) — spans are frequently sub-millisecond.

```bash cURL theme={null}
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"
```

```javascript Node.js theme={null}
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();
```

```json Response theme={null}
{
  "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

<api-endpoint method="GET" url="https://api.apitraffic.io/v1/accounts/{accountSid}/spans/timeseries" />

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

**startTime** `string` *required*

Start of the window (ISO 8601, UTC)

**endTime** `string` *required*

End of the window (ISO 8601, UTC)

**fingerprint** `string`

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

**type** `string`

Limit to one span type

**endpoint** `string`

Limit to one normalized endpoint

**bucketSid** `string`

Limit to one bucket

**environmentSid** `string`

Limit to one environment

### Response

**points** `array`

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

```bash cURL theme={null}
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"
```

```json Response theme={null}
{
  "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

<api-endpoint method="GET" url="https://api.apitraffic.io/v1/accounts/{accountSid}/spans" />

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

**fingerprint** `string` *required*

Span fingerprint to drill back from

**startTime** `string` *required*

Start of the window (ISO 8601, UTC)

**endTime** `string` *required*

End of the window (ISO 8601, UTC)

**endpoint** `string`

Limit to one normalized endpoint

**bucketSid** `string`

Limit to one bucket

**environmentSid** `string`

Limit to one environment

**limit** `number`

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

### Response

**fingerprint** `string`

The fingerprint that was queried.

**points** `array`

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

```bash cURL theme={null}
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"
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.