Get top spans

Error

A valid request URL is required to generate request examples

{
  "_grain": 60,
  "_from": 1771435023,
  "_to": 1771440423,
  "_agent": "a38f69ca-3b56-4ea6-beac-272b2568164a",
  "_contexts": [
    "web"
  ],
  "_contexts_mode": "additive",
  "_distribution_cost": "wt",
  "_project_id": "abc123def456",
  "_environment_id": "main",
  "_branch_machine_name": "main-bvxea6i",
  "_sort": "impact",
  "top_spans": {
    "data": [
      {
        "id": "sql.queries",
        "label": "SQL",
        "percentage": 0.98,
        "wt": 23400,
        "p_96": 45000,
        "count": 12,
        "request_wt": 120000,
        "metrics": [
          "sql.queries"
        ],
        "service_name": "sql",
        "impact": 0.452
      },
      {
        "id": "http.requests",
        "label": "HTTP",
        "percentage": 0.75,
        "wt": 45600,
        "p_96": 89000,
        "count": 8,
        "request_wt": 120000,
        "metrics": [
          "http.requests"
        ],
        "service_name": "http",
        "impact": 0.304
      }
    ]
  },
  "advanced_filters": {
    "fields": {
      "service": {
        "values": [
          {
            "value": "sql",
            "count": 1234
          },
          {
            "value": "http",
            "count": 567
          }
        ],
        "distinct_values": 2,
        "type": "string"
      }
    },
    "max_applicable_filters": 50
  }
}

{
  "type": "https://tools.ietf.org/html/rfc2616#section-1",
  "title": "Please ensure parameters are correct.",
  "status": 400,
  "violations": {
    "grain": [
      "Grain can not be larger than the selection windows."
    ],
    "from": [
      "The from timestamp must be in the past."
    ],
    "to": [
      "The to timestamp must be greater than the from timestamp."
    ]
  }
}

{
  "error": "Too much data fetched",
  "message": "Please reduce the time range or add more filters to narrow down the query"
}

GET

projects

{projectId}

environments

{environmentId}

observability

server

top-spans

Get top spans

curl --request GET \
  --url {schemes}://api.upsun.com/projects/{projectId}/environments/{environmentId}/observability/server/top-spans \
  --header 'Authorization: Bearer <token>'

import requests

url = "{schemes}://api.upsun.com/projects/{projectId}/environments/{environmentId}/observability/server/top-spans"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('{schemes}://api.upsun.com/projects/{projectId}/environments/{environmentId}/observability/server/top-spans', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "{schemes}://api.upsun.com/projects/{projectId}/environments/{environmentId}/observability/server/top-spans",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "{schemes}://api.upsun.com/projects/{projectId}/environments/{environmentId}/observability/server/top-spans"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("{schemes}://api.upsun.com/projects/{projectId}/environments/{environmentId}/observability/server/top-spans")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("{schemes}://api.upsun.com/projects/{projectId}/environments/{environmentId}/observability/server/top-spans")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "_grain": 60,
  "_from": 1771435023,
  "_to": 1771440423,
  "_agent": "a38f69ca-3b56-4ea6-beac-272b2568164a",
  "_contexts": [
    "web"
  ],
  "_contexts_mode": "additive",
  "_distribution_cost": "wt",
  "_project_id": "abc123def456",
  "_environment_id": "main",
  "_branch_machine_name": "main-bvxea6i",
  "_sort": "impact",
  "top_spans": {
    "data": [
      {
        "id": "sql.queries",
        "label": "SQL",
        "percentage": 0.98,
        "wt": 23400,
        "p_96": 45000,
        "count": 12,
        "request_wt": 120000,
        "metrics": [
          "sql.queries"
        ],
        "service_name": "sql",
        "impact": 0.452
      },
      {
        "id": "http.requests",
        "label": "HTTP",
        "percentage": 0.75,
        "wt": 45600,
        "p_96": 89000,
        "count": 8,
        "request_wt": 120000,
        "metrics": [
          "http.requests"
        ],
        "service_name": "http",
        "impact": 0.304
      }
    ]
  },
  "advanced_filters": {
    "fields": {
      "service": {
        "values": [
          {
            "value": "sql",
            "count": 1234
          },
          {
            "value": "http",
            "count": 567
          }
        ],
        "distinct_values": 2,
        "type": "string"
      }
    },
    "max_applicable_filters": 50
  }
}

{
  "type": "https://tools.ietf.org/html/rfc2616#section-1",
  "title": "Please ensure parameters are correct.",
  "status": 400,
  "violations": {
    "grain": [
      "Grain can not be larger than the selection windows."
    ],
    "from": [
      "The from timestamp must be in the past."
    ],
    "to": [
      "The to timestamp must be greater than the from timestamp."
    ]
  }
}

{
  "error": "Too much data fetched",
  "message": "Please reduce the time range or add more filters to narrow down the query"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

projectId

string

required

The unique identifier of the Upsun project

Pattern: [a-z0-9]+

Example:

"abc123def456"

environmentId

string

required

The environment identifier

Pattern: .+

Example:

"main"

Query Parameters

from

integer<int64>

required

Start timestamp for the time range (Unix timestamp in seconds)

Example:

1704067200

integer<int64>

required

End timestamp for the time range (Unix timestamp in seconds)

Example:

1704153600

grain

integer

Granularity of data points in seconds. Auto-calculated if omitted.

Example:

10

sort

enum<string>

Sort field for top spans.

Available options:

percentage,

p_96,

count,

wt,

exec-time,

impact

contexts[]

enum<string>[]

Filter by execution contexts. Defaults to ["web"] with additive mode when neither contexts nor contexts_mode is specified.

Available options:

web,

cli

contexts_mode

enum<string>

Filter mode for contexts parameter. "1" (additive, default) includes only specified contexts. "-1" (subtractive) excludes specified contexts and includes all others. When neither contexts nor contexts_mode is specified, defaults to "1" (additive) with contexts=["web"].

Available options:

1,

-1

Example:

"1"

applications[]

string[]

Filter by application names

applications_mode

enum<string>

Filter mode for applications parameter. "1" (additive) includes only specified applications. "-1" (subtractive) excludes specified applications and includes all others. When omitted: defaults to "-1" if no applications values are provided; defaults to "1" (additive) if at least one applications value is provided.

Available options:

1,

-1

Example:

"1"

instances[]

string[]

Filter by instance names

instances_mode

enum<string>

Filter mode for instances parameter. "1" (additive) includes only specified instances. "-1" (subtractive) excludes specified instances and includes all others. When omitted: defaults to "-1" if no instances values are provided; defaults to "1" (additive) if at least one instances value is provided.

Available options:

1,

-1

Example:

"1"

transactions[]

string[]

Filter by transaction names

transactions_mode

enum<string>

Filter mode for transactions parameter. "1" (additive) includes only specified transactions. "-1" (subtractive) excludes specified transactions and includes all others. When omitted: defaults to "-1" if no transactions values are provided; defaults to "1" (additive) if at least one transactions value is provided.

Available options:

1,

-1

Example:

"1"

wt_slots[]

string[]

Filter by wall-time distribution slots

wt_slots_mode

enum<string>

Filter mode for wt_slots parameter. "1" (additive) includes only specified wt_slots. "-1" (subtractive) excludes specified wt_slots and includes all others. When omitted: defaults to "-1" if no wt_slots values are provided; defaults to "1" (additive) if at least one wt_slots value is provided.

Available options:

1,

-1

Example:

"1"

pmu_slots[]

string[]

Filter by peak memory usage distribution slots

pmu_slots_mode

enum<string>

Filter mode for pmu_slots parameter. "1" (additive) includes only specified pmu_slots. "-1" (subtractive) excludes specified pmu_slots and includes all others. When omitted: defaults to "-1" if no pmu_slots values are provided; defaults to "1" (additive) if at least one pmu_slots value is provided.

Available options:

1,

-1

Example:

"1"

http_status_codes[]

string[]

Filter by HTTP status codes or ranges (e.g., 200, 5xx)

http_status_codes_mode

enum<string>

Filter mode for http_status_codes parameter. "1" (additive) includes only specified http_status_codes. "-1" (subtractive) excludes specified http_status_codes and includes all others. When omitted: defaults to "-1" if no http_status_codes values are provided; defaults to "1" (additive) if at least one http_status_codes value is provided.

Available options:

1,

-1

Example:

"1"

http_hosts[]

string[]

Filter by HTTP hosts

http_hosts_mode

enum<string>

Filter mode for http_hosts parameter. "1" (additive) includes only specified http_hosts. "-1" (subtractive) excludes specified http_hosts and includes all others. When omitted: defaults to "-1" if no http_hosts values are provided; defaults to "1" (additive) if at least one http_hosts value is provided.

Available options:

1,

-1

Example:

"1"

hosts[]

string[]

Filter by server hosts

hosts_mode

enum<string>

Filter mode for hosts parameter. "1" (additive) includes only specified hosts. "-1" (subtractive) excludes specified hosts and includes all others. When omitted: defaults to "-1" if no hosts values are provided; defaults to "1" (additive) if at least one hosts value is provided.

Available options:

1,

-1

Example:

"1"

frameworks[]

string[]

Filter by frameworks. Can be specified multiple times for multiple values (e.g., ?frameworks[]=symfony&frameworks[]=laravel). Use frameworks_mode to control inclusion/exclusion behavior.

frameworks_mode

enum<string>

Filter mode for frameworks parameter. "1" (additive) includes only specified frameworks. "-1" (subtractive) excludes specified frameworks and includes all others. When omitted: defaults to "-1" if no frameworks values are provided; defaults to "1" (additive) if at least one frameworks value is provided.

Available options:

1,

-1

Example:

"1"

languages[]

string[]

Filter by programming languages. Can be specified multiple times for multiple values (e.g., ?languages[]=php&languages[]=python). Use languages_mode to control inclusion/exclusion behavior.

languages_mode

enum<string>

Filter mode for languages parameter. "1" (additive) includes only specified languages. "-1" (subtractive) excludes specified languages and includes all others. When omitted: defaults to "-1" if no languages values are provided; defaults to "1" (additive) if at least one languages value is provided.

Available options:

1,

-1

Example:

"1"

methods[]

string[]

Filter by HTTP methods. Can be specified multiple times for multiple values (e.g., ?methods[]=get&methods[]=post). Use methods_mode to control inclusion/exclusion behavior.

methods_mode

enum<string>

Filter mode for methods parameter. "1" (additive) includes only specified methods. "-1" (subtractive) excludes specified methods and includes all others. When omitted: defaults to "-1" if no methods values are provided; defaults to "1" (additive) if at least one methods value is provided.

Available options:

1,

-1

Example:

"1"

runtimes[]

string[]

Filter by runtimes. Can be specified multiple times for multiple values (e.g., ?runtimes[]=PHP 8.4.17 (fpm-fcgi)). Use runtimes_mode to control inclusion/exclusion behavior.

runtimes_mode

enum<string>

Filter mode for runtimes parameter. "1" (additive) includes only specified runtimes. "-1" (subtractive) excludes specified runtimes and includes all others. When omitted: defaults to "-1" if no runtimes values are provided; defaults to "1" (additive) if at least one runtimes value is provided.

Available options:

1,

-1

Example:

"1"

oss[]

string[]

Filter by operating systems. Can be specified multiple times for multiple values (e.g., ?oss[]=Linux&oss[]=Darwin). Use oss_mode to control inclusion/exclusion behavior.

oss_mode

enum<string>

Filter mode for oss parameter. "1" (additive) includes only specified operating systems. "-1" (subtractive) excludes specified operating systems and includes all others. When omitted: defaults to "-1" if no oss values are provided; defaults to "1" (additive) if at least one oss value is provided.

Available options:

1,

-1

Example:

"1"

distribution_cost

enum<string>

Cost distribution dimension for server load distribution.

Available options:

wt,

pmu

Response

Top spans retrieved successfully

_grain

integer

required

Data granularity in seconds

Example:

5

_from

integer

required

Query start timestamp

Example:

1704067200

_to

integer

required

Query end timestamp

Example:

1704153600

_agent

string<uuid>

required

Blackfire Agent UUID

Example:

"a38f69ca-3b56-4ea6-beac-272b2568164a"

_project_id

string

required

Project identifier

Example:

"abc123def456"

_environment_id

string

required

Environment identifier

Example:

"main"

_branch_machine_name

string

required

Branch machine name

Example:

"main-bvxea6i"

_sort

enum<string> | null

required

Applied sort field for top spans

Available options:

percentage,

p_96,

count,

wt,

exec-time,

impact

top_spans

object

required

Top spans aggregated data

Show child attributes

advanced_filters

object

required

Available filter values for refining queries

Show child attributes

_contexts

string[] | null

Applied context filter values

_contexts_mode

enum<string> | null

Context filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_applications

string[] | null

Applied application filter values

_applications_mode

enum<string> | null

Application filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_instances

string[] | null

Applied instance filter values

_instances_mode

enum<string> | null

Instance filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_transactions

string[] | null

Applied transaction filter values

_transactions_mode

enum<string> | null

Transaction filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_wt_slot

string[] | null

Applied wall-time slot filter values

_wt_slot_mode

enum<string> | null

Wall-time slot filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_pmu_slot

string[] | null

Applied peak memory slot filter values

_pmu_slot_mode

enum<string> | null

Peak memory slot filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_http_status_codes

string[] | null

Applied HTTP status code filter values

_http_status_codes_mode

enum<string> | null

HTTP status code filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_http_hosts

string[] | null

Applied HTTP host filter values

_http_hosts_mode

enum<string> | null

HTTP host filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_hosts

string[] | null

Applied host filter values

_hosts_mode

enum<string> | null

Host filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_frameworks

string[] | null

Applied framework filter values

_frameworks_mode

enum<string> | null

Framework filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_languages

string[] | null

Applied language filter values

_languages_mode

enum<string> | null

Language filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_methods

string[] | null

Applied method filter values

_methods_mode

enum<string> | null

Method filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_runtimes

string[] | null

Applied runtime filter values

_runtimes_mode

enum<string> | null

Runtime filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_oss

string[] | null

Applied OS filter values

_oss_mode

enum<string> | null

OS filter mode (additive=include only, subtractive=exclude)

Available options:

additive,

subtractive

_distribution_cost

enum<string>

Applied distribution cost dimension (wt=wall time, pmu=peak memory usage)

Available options:

wt,

pmu

Last modified on June 16, 2026

⌘I

SDK

REST API

OpenAPI Reference

Authorizations

Path Parameters

Query Parameters

Response