explore
10 operations. Shapes are sketches of the declared schemas, bounded in depth — the authoritative document is linked from the index.
POST/orgs/{orgSlug}/projects/{projectSlug}/explore/aggregate
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
Request body (required) · application/json
{
dataset?: "spans" | "logs" | "events" | "metrics" | "survey_answers"
fn: "count" | "count_unique" | "sum" | "avg" | "min" | "max" | "p50" | "p75" | … 11 more
field?: string
groupBy?: string
filters?: {
key: string
op: "eq" | "neq" | "contains" | "not_contains" | "starts_with" | "gt" | "gte" | "lt" | … 4 more
value?: string
}[]
sameTrace?: {
dataset: "spans" | "logs" | "events" | "metrics" | "survey_answers"
filters?: {
key: string
op: "eq" | "neq" | "contains" | "not_contains" | "starts_with" | "gt" | "gte" | "lt" | … 4 more
value?: string
}[]
negate?: boolean
}
limit?: integer
intervalMinutes?: integer
hours?: integer
from?: unknown
to?: unknown
onLayouts?: "refuse" | "split"
}Response 200
{
dataset: "spans" | "logs" | "events" | "metrics" | "survey_answers"
fn: "count" | "count_unique" | "sum" | "avg" | "min" | "max" | "p50" | "p75" | … 11 more
field: string | null
groupBy: string | null
range: {
from: string
to: string
}
groups: {
group: string | null
value: number | null
count: integer
layout?: string
detail?: {
status: "ok" | "no_data" | "insufficient_observations" | "layouts_differ" | "unreadable_buckets"
basis: "buckets"
observations: number
interval: number | number | null[] | null
layouts: string[]
pointsMerged: integer
resetsDetected: integer
} | {
resetsDetected: integer
pointsMerged: integer
}
}[]
series: {
group: string | null
layout?: string
points: {
bucket: string
value: number | null
count: integer
}[]
}[]
scanned: integer
scanTruncated: boolean
groupCount: integer
groupsTruncated: boolean
limits: {
maxScanRows: integer
maxSeries: integer
maxGroupCardinality: integer
}
compiled: {
sql: string
params: string[]
}
sampling: {
sampledRows: integer
minRate: number | null
estimatedTotal: number
} | null
metric?: {
seriesBasis: "instance_key" | "no_instance_key"
resetsDetected: integer
instancesMerged: integer
}
warnings?: {
code: string
message: string
suggestedSpec?: Record<string, unknown>
}[]
}Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Request
curl -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/explore/aggregate \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/projects/{projectSlug}/explore/attributes
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
dataset | query | "spans" | "logs" | "events" | "metrics" | "survey_answers" | one of "spans" | "logs" | "events" | "metrics" | "survey_answers" |
from | query | unknown | |
to | query | unknown | |
hours | query | integer | min 1, max 720 |
Response 200
{
data: {
key: string
spans: integer
numeric: boolean
}[]
}Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Request
curl https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/explore/attributes \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/explore/rows
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
Request body (required) · application/json
{
from?: unknown
to?: unknown
hours?: integer
dataset?: "spans" | "logs" | "events" | "metrics" | "survey_answers"
filters?: {
key: string
op: "eq" | "neq" | "contains" | "not_contains" | "starts_with" | "gt" | "gte" | "lt" | … 4 more
value?: string
}[]
sameTrace?: {
dataset: "spans" | "logs" | "events" | "metrics" | "survey_answers"
filters?: {
key: string
op: "eq" | "neq" | "contains" | "not_contains" | "starts_with" | "gt" | "gte" | "lt" | … 4 more
value?: string
}[]
negate?: boolean
}
traceId?: string
columns?: string[]
cursor?: string
limit?: integer
}Response 200
{
dataset: "spans" | "logs" | "events" | "metrics" | "survey_answers"
columns: string[]
data: {
id: string
time: string
traceId: string | null
values: string | null[]
}[]
nextCursor: string | null
hasMore: boolean
}Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Request
curl -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/explore/rows \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/projects/{projectSlug}/explore/spans
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
from | query | unknown | |
to | query | unknown | |
hours | query | integer | min 1, max 720 |
traceId | query | string | min length 1, max length 64 |
filters | query | string | max length 4000 |
cursor | query | string | min length 1, max length 500 |
limit | query | integer | default 50, min 1, max 200 |
Response 200
{
data: {
id: string
traceId: string
spanId: string
parentSpanId: string | null
name: string
kind: string
startTime: string
endTime: string
durationMs: number
statusCode: string
statusMessage: string | null
environment: string
release: string | null
serviceName: string | null
attributes: Record<string, unknown>
}[]
nextCursor: string | null
hasMore: boolean
}Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Request
curl https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/explore/spans \
-H "authorization: Bearer $BUCKER_TOKEN"POST/orgs/{orgSlug}/projects/{projectSlug}/explore/spans/aggregate
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
Request body (required) · application/json
{
from?: unknown
to?: unknown
hours?: integer
fn: "count" | "count_unique" | "sum" | "avg" | "min" | "max" | "p50" | "p75" | … 11 more
field?: string
groupBy?: string
filters?: {
key: string
op: "eq" | "neq" | "contains" | "not_contains" | "starts_with" | "gt" | "gte" | "lt" | … 4 more
value?: string
}[]
limit?: integer
intervalMinutes?: integer
}Response 200
{
dataset: "spans" | "logs" | "events" | "metrics" | "survey_answers"
fn: "count" | "count_unique" | "sum" | "avg" | "min" | "max" | "p50" | "p75" | … 11 more
field: string | null
groupBy: string | null
range: {
from: string
to: string
}
groups: {
group: string | null
value: number | null
count: integer
layout?: string
detail?: {
status: "ok" | "no_data" | "insufficient_observations" | "layouts_differ" | "unreadable_buckets"
basis: "buckets"
observations: number
interval: number | number | null[] | null
layouts: string[]
pointsMerged: integer
resetsDetected: integer
} | {
resetsDetected: integer
pointsMerged: integer
}
}[]
series: {
group: string | null
layout?: string
points: {
bucket: string
value: number | null
count: integer
}[]
}[]
scanned: integer
scanTruncated: boolean
groupCount: integer
groupsTruncated: boolean
limits: {
maxScanRows: integer
maxSeries: integer
maxGroupCardinality: integer
}
compiled: {
sql: string
params: string[]
}
sampling: {
sampledRows: integer
minRate: number | null
estimatedTotal: number
} | null
metric?: {
seriesBasis: "instance_key" | "no_instance_key"
resetsDetected: integer
instancesMerged: integer
}
warnings?: {
code: string
message: string
suggestedSpec?: Record<string, unknown>
}[]
}Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Request
curl -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/explore/spans/aggregate \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'POST/orgs/{orgSlug}/projects/{projectSlug}/explore/spans/compare
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
Request body (required) · application/json
{
spike: {
from: unknown
to: unknown
}
baseline: {
from: unknown
to: unknown
}
filters?: {
key: string
op: "eq" | "neq" | "contains" | "not_contains" | "starts_with" | "gt" | "gte" | "lt" | … 4 more
value?: string
}[]
keys?: string[]
minSpikeCount?: integer
limit?: integer
}Response 200
{
spike: {
from: string
to: string
total: integer
}
baseline: {
from: string
to: string
total: integer
}
attributes: {
key: string
value: string
spikeCount: integer
baselineCount: integer
spikeShare: number
baselineShare: number
expectedCount: number
surplus: number
lift: number | null
contribution: number
}[]
truncated: boolean
pairsConsidered: integer
minSpikeCount: integer
disclaimer: string
}Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Request
curl -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/explore/spans/compare \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'POST/orgs/{orgSlug}/projects/{projectSlug}/explore/spec/preview
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
Request body (required) · application/json
{
spec: Record<string, unknown>
range?: {
from?: unknown
to?: unknown
hours?: integer
}
variables?: Record<string, string | number | string[]>
}Response 200
{
specVersion: integer
querySpecDigest: string
dataset: string
select: {
alias: string
fn: string
field: string | null
}[]
formulas: string[]
groupBy: string | null
intervalMinutes: integer | null
compiled: {
sql: string
params: string[]
}
resolvedRange: {
from: string
to: string
relative: boolean
}
tenant: {
projectCount: integer
predicateVerified: boolean
empty: boolean
}
restrictions: string[]
estimate: {
rows: number | null
bytes: number | null
basis: string
}
scan: {
engine: string
tier: string
joinRows: number | null
budgetRemaining: {
kind: "QUERY_SCAN"
governed: boolean
remaining: number | null
limit: number | null
} | null
queue: null
}
lint: {
code: "range_beyond_hot_window" | "scan_truncation_expected" | "high_cardinality_group" | "unindexed_attribute_filter" | "join_fanout" | "cross_tier_scan" | "cohort_floor_applies" | "budget_insufficient"
severity: "warn" | "info"
message: string
narrower: Record<string, unknown> | null
detail: Record<string, number | string | boolean | null>
}[]
budget: {
state: string
reason: string | null
estimateNeeded: boolean
}
canonical: {
canonical: boolean
noncanonical: string[]
}
cohortFloor: {
applied: boolean
min: integer | null
suppressedGroups: integer
}
}Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Request
curl -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/explore/spec/preview \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'POST/orgs/{orgSlug}/projects/{projectSlug}/explore/spec/run
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
Request body (required) · application/json
{
spec: Record<string, unknown>
range?: {
from?: unknown
to?: unknown
hours?: integer
}
variables?: Record<string, string | number | string[]>
cache?: boolean
}Response 200
{
specVersion: integer
result: "ok" | "no_data" | "not_enough_data" | "truncated" | "queued_too_long" | "tier_unavailable"
data: {
groups: {
group: string | null
values: object
count: integer
compare?: object
}[]
series: {
group: string | null
points: object[]
}[]
columns: string[]
}
truncated: boolean
omitted: integer | null
capThatBit: "scan_rows" | "page_limit" | null
cursor: string | null
scanned: integer
basis: {
tier: string
engine: string
samplingRate: number | null
sampling: {
sampledRows: integer
minRate: number | null
estimatedTotal: number
} | null
freshness: {
watermark: string | null
source: string
}
querySpecDigest: string
ruleSetVersion: string | null
}
trust: {
untrustedFields: {
path: string
class: string
}[]
}
compiled: {
sql: string
params: string[]
}
resolvedRange: {
from: string
to: string
relative: boolean
}
rollup: {
id: string
} | null
canonical: {
canonical: boolean
noncanonical: string[]
}
cohortFloor: {
applied: boolean
min: integer | null
suppressedGroups: integer
}
cache: {
hit: boolean
ttlSeconds: integer
key: string | null
}
budget: {
state: string
reason: string | null
estimatedRows: number | null
estimateBasis: string
estimateNeeded: boolean
}
route?: {
engine: string
tier: "hot" | "cold"
reason: string
lane: string
caps: {
hotWindowDays: integer
scanRows: integer
}
fallback: {
wanted: string
why: string
servedFrom: string | null
} | null
engines: {
target: string
usable: boolean
why: string | null
}[]
}
join?: {
name: string
keyKind: string
source: string
countIs: "distinct_keys" | "rows"
floorMin: integer | null
stored: {
matchRate: number | null
unmatchedShare: number | null
fanOutMax: number | null
sampleSize: number | null
validatedAt: string | null
rateHistory: object[]
}
observed: {
rows: number | null
unmatchedRows: number | null
unmatchedShare: number | null
keys: number | null
unmatchedKeys: number | null
unmatchedKeyShare: number | null
suppressed: boolean
}
note: string
}
queue?: {
handle: string
position: integer
expiresAt: string
pollIntervalMs: integer
}
}Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Request
curl -X POST https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/explore/spec/run \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'GET/orgs/{orgSlug}/projects/{projectSlug}/explore/traces/{traceId}/spans/{spanId}
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
traceIdrequired | path | string | min length 1, max length 64 |
spanIdrequired | path | string | min length 1, max length 64 |
Response 200
{
span: {
spanId: string
parentSpanId: string | null
traceId: string
name: string
kind: string
startTime: string
endTime: string
durationMs: number
statusCode: string
statusMessage: string | null
environment: string
release: string | null
serviceName: string | null
attributes: Record<string, unknown>
resource: Record<string, unknown>
events: Record<string, unknown>[]
}
logs: {
id: string
timestamp: string
severity: string
body: string
attributes: Record<string, unknown>
}[]
logsTruncated: boolean
errors: {
id: string
eventId: string
timestamp: string
level: string
message: string | null
exceptionType: string | null
exceptionValue: string | null
issue: {
id: string
shortId: string
title: string
status: string
} | null
}[] | null
errorsTruncated: boolean
errorsHidden: boolean
}Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Request
curl https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/explore/traces/{traceId}/spans/{spanId} \
-H "authorization: Bearer $BUCKER_TOKEN"GET/orgs/{orgSlug}/projects/{projectSlug}/explore/traces/{traceId}/waterfall
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min length 1 |
traceIdrequired | path | string | min length 1, max length 64 |
Response 200
{
traceId: string
spanCount: integer
orphanCount: integer
maxDepth: integer
startTime: string | null
endTime: string | null
durationMs: number
services: string[]
truncated: boolean
genAi?: {
callCount: integer
costMicroUsd: number
costLowMicroUsd: number
unpricedCalls: integer
modelMs: number
toolMs: number
} | null
rows: {
spanId: string
parentSpanId: string | null
name: string
kind: string
serviceName: string | null
statusCode: string
depth: integer
offsetMs: number
durationMs: number
offsetRatio: number
widthRatio: number
selfTimeMs: number
orphan: boolean
attributes: Record<string, unknown>
logCount: integer
errorCount: integer | null
genAi?: {
kind: "chat" | "embedding"
model: string | null
provider: string | null
inputTokens: number
outputTokens: number
cacheReadTokens: number
microUsd: number
priceSource: "global" | "org_contract" | "ingested" | "default" | null
unpriced: boolean
ttfcMs: number | null
finishReason: string | null
promptVersion: string | null
} | null
}[]
}Response 400 · `bad_request` — the path, query or body failed validation. `details` carries the Zod issues, one per offending field.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 401 · `unauthorized` — no credential, or one that is expired, revoked or not valid for this resource. `mfa_required` when the credential is good but a second factor is owed.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 403 · `forbidden` — the credential is valid and its scopes or this principal’s membership do not reach this resource. Scopes are re-intersected with live memberships on every request, so this can appear for a token that worked yesterday.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 404 · `not_found` — no such resource, OR one this principal cannot see. The two are deliberately one answer: a 403 would confirm the existence of something whose identifier is guessable.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 429 · `rate_limited` or `quota_exceeded` — over a ceiling. `Retry-After` says when to come back, and `x-ratelimit-limit` / `-remaining` / `-reset` describe the bucket.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Response 500 · `internal_error` — an unhandled failure on this side. The message is always generic; `requestId` is the part worth quoting.
{
error: {
code: "bad_request" | "conflict" | "forbidden" | "internal_error" | "mfa_required" | "not_found" | "payload_too_large" | "quota_exceeded" | … 6 more
message: string
details?: unknown
requestId?: string
}
}Request
curl https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/explore/traces/{traceId}/waterfall \
-H "authorization: Bearer $BUCKER_TOKEN"