Skip to content
bucker

API reference

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

Parameters for GET /orgs/{orgSlug}/cost/explain
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
kindquery"window" | "release" | "source" | "pull_request"default "window", one of "window" | "release" | "source" | "pull_request"
aFromquerystring
aToquerystring
bFromquerystring
bToquerystring
aquerystringmin length 1, max length 200
bquerystringmin length 1, max length 200
fromquerystring
toquerystring
projectIdquerystringmin 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

Parameters for GET /orgs/{orgSlug}/cost/rows
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
fromquerystring
toquerystring
projectIdquerystringmin length 1, max length 64
lanequery"estimated" | "billed"one of "estimated" | "billed"
basisquery"ingested" | "org_contract" | "global" | "default" | "mixed" | "rate_card" | "billed" | "allocated" | … 1 moreone of "ingested" | "org_contract" | "global" | "default" | "mixed" | "rate_card" | "billed" | "allocated" | … 1 more
versionsquery"current" | "all"default "current", one of "current" | "all"
limitqueryintegerdefault 100, min 1, max 500
cursorquerystringmin 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

Parameters for GET /orgs/{orgSlug}/cost/status
NameInTypeNotes
orgSlugrequiredpathstringmin length 1, max length 64
fromquerystring
toquerystring
projectIdquerystringmin length 1, max length 64
groupByquery"source" | "provider" | "service" | "project" | "release" | "feature" | "owner" | "principal" | … 1 moredefault "source", one of "source" | "provider" | "service" | "project" | "release" | "feature" | "owner" | "principal" | … 1 more
lanequery"estimated" | "billed"one of "estimated" | "billed"
limitqueryintegerdefault 5, min 1, max 25
includequerystringmax length 200
anomalyKindquery"cost_regression" | "provider_cap_hit"one of "cost_regression" | "provider_cap_hit"
unitquerystringmin 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"