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
| 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[]
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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
projectSlugrequired | path | string | min 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
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1 |
traceIdrequired | path | string | min 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"