levers
1 operation. Shapes are sketches of the declared schemas, bounded in depth — the authoritative document is linked from the index.
POST/orgs/{orgSlug}/projects/{projectSlug}/levers/{lever}/preview
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
projectSlugrequired | path | string | min length 1, max length 64 |
leverrequired | path | string | min length 1, max length 64 |
Request body (required) · application/json
{
plan: Record<string, unknown>
hours?: integer
}Response 200
{
lever: "span_sampling_rule" | "log_pipeline_rule" | "series_budget" | "cold_window" | "retention_lengthen" | "project_quota" | "metric_tag_rule" | "log_quota" | … 5 more
signal: "spans" | "logs" | "metrics" | "storage" | "quota"
direction: "reduce" | "widen" | "neutral"
plan: Record<string, unknown>
window: {
from: string
to: string
hours: number
}
verdict: "ok" | "refused"
refusals: {
code: "would_drop_floor_records" | "widens_quota" | "widens_series_budget" | "shortens_retention" | "plan_is_a_no_op" | "not_available"
message: string
narrower: Record<string, unknown> | null
}[]
stored: {
matched: integer
total: integer
sampleRows: integer
basis: "counted" | "extrapolated" | "capped"
estimatedOriginalMatched: number | null
}
effect: {
droppedRows: integer
keptRows: integer
droppedShareOfMatched: number
droppedShareOfTotal: number
floorKeptRows: integer
}
preSampling: {
requests: number
storedSpans: number
basis: "exact"
} | null
edgeDrops: {
outcome: string
reason: string | null
quantity: number
}[]
units: {
weight: number
savedUnits: number
savedUnitsPerDay: number
dollars: number
dollarsPerUnit: number
daysOfAllowanceGained: number | null
allowanceUnits: number | null
}
floor: {
recordsWouldDrop: integer
byReason: Record<string, integer>
crossBatchExposure: {
rows: integer
traces: integer
liveTraceCap: integer
liveLookbackMinutes: number
liveWindowSeconds: number
windowTracesTruncated: boolean
note: string
}
}
consumers: {
affected: {
kind: "alert_rule" | "saved_view" | "dashboard_widget" | "saved_query" | "rollup" | "detector"
id: string
name: string
droppedRowsMatched: integer
keptRowsMatched: integer
changedEvaluations: integer | null
note: string | null
}[]
unaffected: integer
hiddenPrivate: integer
evaluationsChanged: integer
}
approximations: string[]
detectionLoss?: {
status: "measured" | "not_enough_data" | "not_applicable" | "not_measured"
reason: string | null
holdout: {
rate: number
scannedRows: integer
scanTruncated: boolean
rows: integer
traces: integer
}
detectors: {
id: string
label: string
unit: "spans" | "traces" | "logs"
signalRows: integer
expectedRemovedRows: number
removedShare: number | null
minimumDetectableRate: number | null
upperBoundIfNoneRemoved: number | null
status: "measured" | "not_enough_data"
}[]
note: string
}
evidenceLoss?: {
status: "measured" | "not_enough_data" | "not_applicable" | "not_measured"
reason: string | null
windowDays: integer
incidentsConsidered: integer
itemsEvaluated: integer
itemsHeldByFloor: integer
itemsUnresolved: integer
blindIncidentCount: integer
blindIncidents: {
incidentId: string
shortId: string
items: object[]
}[]
truncated: boolean
notMeasured: {
source: string
reason: string
}[]
}
digest: string | null
validUntil: string | null
validityMinutes: 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}/levers/{lever}/preview \
-H "authorization: Bearer $BUCKER_TOKEN" \
-H 'content-type: application/json' \
-d '{ … }'