Aggregate a dataset's spans

Aggregations of the dataset's spans whose start time is in [from, to) and that match every filter, grouped by up to two fields, per time bucket and in total. Functions: count, rate (count per second), countDistinct (approximate, uniqCombined), sum, avg, min, max, p50, p90, p95 and p99 (t-digest estimates), plus errors and errorRate (status error). Numeric fields are duration (nanoseconds) or span or resource attributes, parsed as numbers; spans whose value doesn't parse are skipped. Groups are ranked by the first aggregation's total; those past groupLimit add up into other, computed from their rows. Group values longer than 256 bytes are cut and the group is marked keyTruncated. A value is null where a group has no rows in a bucket, or no value parses. With no groupBy there is exactly one group. series false answers totals only (bucketSeconds null, starts empty). 422 query_too_expensive: narrow the time range or filters. 429 too_many_requests: too many console reads are running in the organization; retry after Retry-After. 503 source_unavailable: some of the data can't be read right now; there is never a partial answer. Not recorded in Trails; not idempotent and nothing is kept.

POST

https://obs.ezghcloud.com/v1/organizations/{orgId}/projects/{projectId}/obs/datasets/{datasetId}/traces/aggregate

View as Markdown

Authorization

apiKeyoptionalHTTP
oauthoptionalHTTP
sessionCookieoptionalAPI key in cookie

Path parameters

orgIdstringrequired
format: uuid
projectIdstringrequired
format: uuid
datasetIdstringrequired
format: uuid

Request bodyJSONrequired

aggregationsarray ofobjectrequired
2 properties
- fncountorrateorcountDistinctorsumoravgormin+7 morerequired
- fieldoptionalstringorAggregateAttributeField
  2 variants
  One of the following:
  string
  AggregateAttributeField
  View AggregateAttributeField schema →
  2 properties
  keystringrequired
  maxLength: 256, minLength: 1
  scopeoptionalrecordorresource
  Default: "record"
fromstringrequired
UTC, millisecond precision: 2026-10-02T10:20:00.000Z.

format: date-time
tostringrequired
At most a day ahead; the window spans at most 400 days.

format: date-time
bucketSecondsoptionalinteger
Only with series. Rounded up to 10, 30, 60, 120, 300, 600, 1800, 3600, 7200, 10800, 21600, 43200 or 86400 seconds, and raised until the window has at most 1,440 buckets. Absent: chosen for at most 72.

maximum: 86400, minimum: 1
filtersoptionalobject
10 properties
- applicationsoptionalarray ofstring
  maxLength: 256, minLength: 1
- attributesoptionalarray ofobject
  5 properties
  keystringrequired
  maxLength: 256, minLength: 1
  opequalsornotEqualsorinorexistsrequired
  notEquals: the key is absent, or holds another value. in: the key is present and holds one of values. notEquals and in are accepted once console reads are on (otherwise 400).
  
  scopeoptionalrecordorresource
  record is the span's attributes; resource is its resource attributes.
  
  Default: "record"
  valueoptionalstring
  Required with equals and notEquals.
  
  maxLength: 1024
  valuesoptionalarray ofstring
  Required with in, and only with it.
  
  maxLength: 1024
- kindsoptionalarray ofunspecifiedorinternalorserverorclientorproducerorconsumer
- maxDurationNanosoptionalinteger
  maximum: 9007199254740991, minimum: 0
- minDurationNanosoptionalinteger
  maximum: 9007199254740991, minimum: 0
- rootOnlyoptionalboolean
- servicesoptionalarray ofstring
  maxLength: 256, minLength: 1
- spanNamesoptionalarray ofstring
  maxLength: 256, minLength: 1
- statusesoptionalarray ofunsetorokorerror
- traceIdoptionalstring
  pattern: ^[0-9a-fA-F]{32}$
groupByoptionalarray ofobject
1 properties
- fieldstringorAggregateAttributeFieldrequired
  2 variants
  One of the following:
  string
  AggregateAttributeField
  View AggregateAttributeField schema →
  2 properties
  keystringrequired
  maxLength: 256, minLength: 1
  scopeoptionalrecordorresource
  Default: "record"
groupLimitoptionalinteger
maximum: 50, minimum: 1
Default: 10
seriesoptionalboolean
false: totals only.

Default: true

Returns

200

The aggregations.

JSON

aggregationsarray ofobjectrequired
The aggregations, normalized, in request order.
bucketSecondsinteger | nullrequired
The bucket size used; null with series false.
groupByarray ofstringrequired
Each groupBy field's label in a group's key: the well-known name, or record. or resource..
groupsarray ofobjectrequired
4 properties
- keymap ofstringrequired
  groupBy label to value; an absent attribute is empty.
- keyTruncatedbooleanrequired
- totalsarray ofnumber | nullrequired
  One value per aggregation, in request order; null where there are no rows or no value parses.
- valuesarray ofarray<number | null>required
  One entry per bucket (starts).
groupsTruncatedbooleanrequired
percentilesunknownrequired
sourceobjectrequired
How the answer was built: rollup false is from the records themselves.
2 properties
- rollupbooleanrequired
- rawFromoptionalstring
  UTC, millisecond precision: 2026-10-02T10:20:00.000Z.
  
  format: date-time
startsarray ofstringrequired
Every bucket's start, epoch-aligned; the first and last may be partial.

format: date-time
visibleThroughobjectrequired
2 properties
- lanesarray ofobjectrequired
  3 properties
  datasetIdstringrequired
  format: uuid
  ingestedAtInstantornullrequired
  2 variants
  One of the following:
  Instant
  null
  laneintegerrequired
- tokenstringrequired
  Opaque: the accepted data this answer covers.
otheroptionalobject
Every group past groupLimit, added up. Present exactly when groupsTruncated.
2 properties
- totalsarray ofnumber | nullrequired
  One value per aggregation, in request order; null where there are no rows or no value parses.
- valuesarray ofarray<number | null>required

400

invalid_request (with issues), invalid_cursor, or the endpoint's own 400 codes.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

401

unauthenticated: no credential, or one that doesn't check out.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

403

access_denied: the caller's policies don't allow the action; forbidden_origin: a cookie-authenticated write from an origin that isn't allowed; spend_limit_reached.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

404

not_found: unknown, malformed, or in an organization the caller isn't in.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

409

quota_exceeded (an allocation quota, with quota), idempotency_conflict, idempotency_in_progress (with Retry-After), organization_deletion_pending, operation_in_progress, or the endpoint's own 409 codes.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

413

payload_too_large: the body is over the endpoint's limit (1 MiB unless it says otherwise).

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

422

query_too_expensive.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

429

too_many_requests, with Retry-After; or quota_exceeded (a rate, usage or concurrency quota, with quota), never with Retry-After.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

500

internal_error: a bug; the details are in the logs, under the request ID.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.

503

unavailable: a dependency the request needs is down. Retry after Retry-After.

JSON

errorobjectrequired
4 properties
- codestringrequired
  maxLength: 64, pattern: ^[a-z][a-z0-9_]*$
- messagestringrequired
  maxLength: 1024
- issuesoptionalarray ofobject
  invalid_request: one entry per problem, at a dotted path.
  
  2 properties
  messagestringrequired
  pathstringrequired
- quotaoptionalobject
  quota_exceeded: the quota that refused the request. Never with Retry-After.
  
  11 properties
  idstringrequired
  kindallocationorrateorusageorconcurrencyrequired
  limitintegerrequired
  minimum: 0
  scopeorganizationorprojectorresourcerequired
  inFlightoptionalinteger
  minimum: 0
  periodStartoptionalstring
  format: date-time
  regionoptionalstring
  resetsAtoptionalstring
  format: date-time
  scopeResourceNameoptionalstring
  usedoptionalinteger
  minimum: 0
  windowoptionalstring
  rate only: an ISO 8601 duration, PT1S to PT1H.