Skip to main content
GET
/
projects
/
{projectId}
/
environments
/
{environmentId}
/
observability
/
server
/
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
  }
}

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

​
to
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"

​
transactions[]
string[]

Filter by transaction names

​
transactions_mode
enum<string>

Filter mode for transactions parameter. "1" (additive) includes only specified transactions. "-1" (subtractive, default) excludes specified transactions and includes all others.

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, default) excludes specified wt_slots and includes all others.

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, default) excludes specified pmu_slots and includes all others.

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, default) excludes specified http_status_codes and includes all others.

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, default) excludes specified http_hosts and includes all others.

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, default) excludes specified hosts and includes all others.

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, default) excludes specified frameworks and includes all others.

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, default) excludes specified languages and includes all others.

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, default) excludes specified methods and includes all others.

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, default) excludes specified runtimes and includes all others.

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, default) excludes specified operating systems and includes all others.

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

​
advanced_filters
object
required

Available filter values for refining queries

​
_contexts
string[] | null

Applied context filter values

​
_contexts_mode
enum<string> | null

Context 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 March 25, 2026