cost
3 operations. Shapes are sketches of the declared schemas, bounded in depth — the authoritative document is linked from the index.
GET/orgs/{orgSlug}/cost/explain
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
kind | query | "window" | "release" | "source" | "pull_request" | default "window", one of "window" | "release" | "source" | "pull_request" |
aFrom | query | string | |
aTo | query | string | |
bFrom | query | string | |
bTo | query | string | |
a | query | string | min length 1, max length 200 |
b | query | string | min length 1, max length 200 |
from | query | string | |
to | query | string | |
projectId | query | string | min length 1, max length 64 |
Response 200
{
comparison: {
kind: "window" | "release" | "source"
a: string
b: string
}
currency: string
moneyRedacted: boolean
unitsOnly: boolean
lanes: {
a: {
rows: integer
cost: string | null
}
b: {
rows: integer
cost: string | null
}
delta: string | null
deltaPercent: number | null
lane: string
split: {
rate: string
volume: string
mix: string
} | null
}[]
totals: {
a: {
rows: integer
cost: string | null
}
b: {
rows: integer
cost: string | null
}
delta: string | null
deltaPercent: number | null
}
split: {
rate: string
volume: string
mix: string
} | null
decompositions: {
lane: string
unit: string
a: {
quantity: string
cost: string | null
}
b: {
quantity: string
cost: string | null
}
delta: string | null
split: {
rate: string
volume: string
mix: string
} | null
}[]
contributors: {
id: string
label: string
lane: string
unit: string
deltaQuantity: string
deltaCost: string | null
split: {
rate: string
volume: string
mix: string
} | null
}[]
changeEvents: {
id: string
kind: string
summary: string
occurredAt: string
service: string | null
environment: string | null
project: string
trust: string
window: "a" | "b"
}[]
scanned: integer
truncated: boolean
capThatBit: "scan_rows" | null
newestRecency: string | null
notes: string[]
ai?: {
available: false
reason: "pillar_off" | "not_covered" | "no_projects"
} | {
available: true
projects: integer
decomposition: {
outcomeUnit: "session" | "call"
baseline: object
current: object
excessMicroUsd: number
factors: object[]
checked: string[]
topFactor: string | null
share: number | null
verdict: "explained" | "inconclusive"
inconclusiveReason: string | null
corroboratingEventIds: string[]
rows: object
}
truncated: boolean
newestDay: string | null
}
untrustedFields: 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 https://api.bucker.io/orgs/{orgSlug}/cost/explain \
-H "authorization: Bearer $BUCKER_TOKEN"GET/orgs/{orgSlug}/cost/rows
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
from | query | string | |
to | query | string | |
projectId | query | string | min length 1, max length 64 |
lane | query | "estimated" | "billed" | one of "estimated" | "billed" |
basis | query | "ingested" | "org_contract" | "global" | "default" | "mixed" | "rate_card" | "billed" | "allocated" | … 1 more | one of "ingested" | "org_contract" | "global" | "default" | "mixed" | "rate_card" | "billed" | "allocated" | … 1 more |
versions | query | "current" | "all" | default "current", one of "current" | "all" |
limit | query | integer | default 100, min 1, max 500 |
cursor | query | string | min length 1, max length 512 |
Response 200
{
data: {
id: string
chargeDay: string
projectId: string | null
sourceId: string
chargePeriodStart: string
chargePeriodEnd: string
billingPeriodStart: string
billingPeriodEnd: string
serviceProviderName: string
hostProviderName: string
serviceName: string
serviceCategory: string
skuId: string
subAccountId: string
regionId: string
resourceKey: string | null
chargeCategory: string
chargeClass: string | null
billedCost: string | null
effectiveCost: string | null
listCost: string | null
contractedCost: string | null
billingCurrency: string
consumedQuantity: string
… 20 more
}[]
nextCursor: string | null
moneyRedacted: boolean
window: {
from: string
to: string
}
versions: "current" | "all"
untrustedFields: 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 https://api.bucker.io/orgs/{orgSlug}/cost/rows \
-H "authorization: Bearer $BUCKER_TOKEN"GET/orgs/{orgSlug}/cost/status
Requires bearerAuth
Parameters
| Name | In | Type | Notes |
|---|---|---|---|
orgSlugrequired | path | string | min length 1, max length 64 |
from | query | string | |
to | query | string | |
projectId | query | string | min length 1, max length 64 |
groupBy | query | "source" | "provider" | "service" | "project" | "release" | "feature" | "owner" | "principal" | … 1 more | default "source", one of "source" | "provider" | "service" | "project" | "release" | "feature" | "owner" | "principal" | … 1 more |
lane | query | "estimated" | "billed" | one of "estimated" | "billed" |
limit | query | integer | default 5, min 1, max 25 |
include | query | string | max length 200 |
anomalyKind | query | "cost_regression" | "provider_cap_hit" | one of "cost_regression" | "provider_cap_hit" |
unit | query | string | min length 1, max length 64 |
Response 200
{
window: {
from: string
to: string
}
currency: string
groupBy: "source" | "provider" | "service" | "project" | "release" | "feature" | "owner" | "principal" | … 6 more
moneyRedacted: boolean
scope: {
projectId: string | null
}
lanes: {
lane: string
rows: integer
effectiveCost: string | null
billedCost: string | null
listCost: string | null
contractedCost: string | null
}[]
groups: {
id: string
kind: "cost_group"
groupBy: "source" | "provider" | "service" | "project" | "release" | "feature" | "owner" | "principal" | … 6 more
key: string
label: string
unit: "cost"
currency: string
lane: string
basis: string
byLane: Record<string, string | null>
recency: string
completeness: {
complete: boolean
completeRows: integer
rows: integer
unpricedShareMax: number
}
effectiveCost: string | null
billedCost: string | null
listCost: string | null
contractedCost: string | null
share: number | null
rows: integer
owner: {
team: string | null
confidence: "high" | "low" | "none"
} | null
actions: {
action: string
class: string
humanOnly: boolean
performable: boolean
decision_preview: object | null
}[]
}[]
distribution: {
id: string
kind: "cost_distribution"
groupBy: "principal" | "delegator"
withheld: "fewer_than_5_subjects" | null
subjects: integer
p50: string | null
p90: string | null
topDecileShare: number | null
currency: string
} | null
sources: {
id: string
provider: string
lane: string
state: string
rows: integer
daysWithRows: integer
daysComplete: integer
lastProcessedAt: string | null
lastBillReceivedAt: string | null
typicalLagHours: number | null
lagHours: number | null
recency: string
}[]
groupsOmitted: integer
unit: {
status: "not_available"
card: string
reason: string
emptyReason?: "not_enough_data"
} | {
status: "available"
key: string
version: integer
label: string
definitionStatus: "certified"
currency: string
per: integer
window: {
kind: "day" | "week" | "month"
from: string
through: string
}
value: string | null
reason: string | null
n: integer | null
minDenominator: integer
lane: string
basis: string | null
numerator: {
cost: string | null
rows: integer
}
denominator: {
kind: string
basis: string
state: "ok" | "gated" | "unavailable"
note: string | null
}
freshness: {
newestRecency: string | null
denominatorWatermark: string | null
denominatorComplete: boolean | null
}
} | null
grouping: {
status: "not_available"
card: string
reason: string
emptyReason?: "not_enough_data"
} | null
blocks: Record<string, {
status: "not_available"
card: string
reason: string
emptyReason?: "not_enough_data"
} | {
status: "available"
}>
anomalies: {
id: string
kind: "cost_regression" | "provider_cap_hit"
shortId: string
title: string
project: string
status: string
firstSeen: string
lastSeen: string
occurrences: integer
providerCap: {
provider: string
scope: string
stopType: string
retryable: false
resetAt: string | null
} | null
owner: {
team: string | null
confidence: "high" | "low" | "none"
} | null
actions: {
action: string
class: string
humanOnly: boolean
performable: boolean
decision_preview: object | null
}[]
evidence?: {
day: string
onsetDay: string
basis: "weekday_median" | "short_history"
shortHistory: boolean
historyDays: integer
baselineDays: integer
expected: string | null
interval: object | null
actual: string | null
ratioBp: integer | null
rule: object
split: object
contributors: object[]
suspects: object[]
owner: object
} | null
}[] | null
scanned: integer
truncated: boolean
capThatBit: "scan_rows" | "groups" | null
newestRecency: string | null
untrustedFields: 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 https://api.bucker.io/orgs/{orgSlug}/cost/status \
-H "authorization: Bearer $BUCKER_TOKEN"