Skip to content
bucker

API reference

traces

3 operations. Shapes are sketches of the declared schemas, bounded in depth — the authoritative document is linked from the index.

GET/orgs/{orgSlug}/projects/{projectSlug}/traces/{traceId}

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/traces/{traceId}
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[]
  environments: string[]
  truncated: boolean
  roots: 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 https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/traces/{traceId} \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/traces/search

Requires bearerAuth

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/traces/search
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

Record<string, unknown>

Response 200

{
  result: "ok" | "truncated" | "queued_too_long"
  traces: {
    traceId: string
    startedAt: string | null
    durationMs: number | null
    spanCount: integer | null
    errorSpans: integer | null
    rootService: string | null
    rootOperation: string | null
    services: string[]
    release: string | null
    matched: {
      condition: "a" | "b" | "c"
      spans: integer
      spanIds: string[]
    }[]
    complete: boolean
    incompleteReasons: "sampled" | "orphan_spans" | "span_cap"[]
  }[]
  cursor: string | null
  evidence: {
    basis: "stored_sampled"
    tier: "hot"
    engine: "postgres_hot"
    scanned: integer
    scanCap: integer
    scanTruncated: boolean
    candidateTraces: integer
    candidateCap: integer
    candidatesTruncated: boolean
    tracesEvaluated: integer
    windowRequested: {
      from: string
      to: string
    }
    windowCovered: {
      from: string
      to: string
    }
    newestSpanAt: string | null
    complete: boolean
    sampledTraces: integer
    minSampleRate: number | null
    probesPerTrace: integer
    reachMinutes: integer
    budget: {
      state: string
      reason: string | null
      estimatedRows: number | null
      estimateBasis: string
      effectiveRows: number | null
      estimateNeeded: boolean
    }
    note: string
  }
  query: {
    digest: string
    spec: Record<string, unknown>
    window: {
      from: string
      to: string
      relative: boolean
    }
    compiled: {
      match: object
      detail: object | null
    }
  }
  baseline: {
    status: "not_available"
    reason: string
  } | null
  trust: {
    untrustedFields: {
      path: string
      class: 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}/traces/search \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/traces/{traceId}

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/traces/{traceId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
traceIdrequiredpathstringmin length 1, max length 64

Response 200

{
  traceId: string
  spanCount: integer
  storedSpans: integer
  startTime: string | null
  endTime: string | null
  durationMs: number
  services: string[]
  environments: string[]
  releases: string[]
  errorSpans: integer
  projects: {
    projectId: string
    slug: string
    spans: integer
  }[]
  orphanCount: integer
  complete: boolean
  incompleteReasons: "orphan_spans" | "span_cap" | "sampled" | "unreadable_projects" | "clock_skew" | "depth_limit"[]
  criticalPath: {
    durationMs: number
    spans: {
      spanId: string
      name: string
      serviceName: string | null
      statusCode: string
      offsetMs: number
      durationMs: number
      contributionMs: number
    }[]
  }
  flame: {
    spanId: string
    name: string
    serviceName: string | null
    statusCode: string
    selfTimeMs: number
    sharePct: number
  }[]
  errors: {
    spanId: string
    name: string
    serviceName: string | null
    statusMessage: string | null
  }[]
  links: {
    fromSpanId: string
    traceId: string
    spanId: string
    sameTrace: boolean
  }[]
  linksTotal: integer
  genAi: {
    callCount: integer
    calls: {
      spanId: string
      kind: "chat" | "embedding"
      model: string | null
      provider: string | null
      inputTokens: number
      outputTokens: number
      cacheReadTokens: number
      ttfcMs: number | null
      finishReason: string | null
      promptVersion: string | null
      durationMs: number
      microUsd: number
      priceSource: "global" | "org_contract" | "ingested" | "default" | null
      unpriced: boolean
      onCriticalPath: boolean
      issues: object[]
    }[]
    callsOmitted: integer
    costMicroUsd: number
    costLowMicroUsd: number
    unpricedCalls: integer
    priceSource: "global" | "org_contract" | "ingested" | "default" | "mixed" | null
    priceTableVersion: string | null
    inputTokens: number
    outputTokens: number
    cacheReadTokens: number
    modelMs: number
    modelSharePct: number
    toolMs: number
    toolSharePct: number
    criticalPathCalls: integer
  } | null
  unreadable: {
    spans: integer
    projects: integer
  }
  beyondCap: integer
  duplicateSpans: 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 https://api.bucker.io/orgs/{orgSlug}/traces/{traceId} \
  -H "authorization: Bearer $BUCKER_TOKEN"