Skip to content
bucker

API reference

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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/explore/aggregate
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/explore/attributes
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
datasetquery"spans" | "logs" | "events" | "metrics" | "survey_answers"one of "spans" | "logs" | "events" | "metrics" | "survey_answers"
fromqueryunknown
toqueryunknown
hoursqueryintegermin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/explore/rows
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/explore/spans
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
fromqueryunknown
toqueryunknown
hoursqueryintegermin 1, max 720
traceIdquerystringmin length 1, max length 64
filtersquerystringmax length 4000
cursorquerystringmin length 1, max length 500
limitqueryintegerdefault 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/explore/spans/aggregate
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/explore/spans/compare
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/explore/spec/preview
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin 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

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/explore/spec/run
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/explore/traces/{traceId}/spans/{spanId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
traceIdrequiredpathstringmin length 1, max length 64
spanIdrequiredpathstringmin 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

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/explore/traces/{traceId}/waterfall
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
traceIdrequiredpathstringmin 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"