Skip to content
bucker

API reference

replay

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

DELETE/orgs/{orgSlug}/projects/{projectSlug}/replay/{segmentId}

Requires bearerAuth

Parameters

Parameters for DELETE /orgs/{orgSlug}/projects/{projectSlug}/replay/{segmentId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
segmentIdrequiredpathstringmin length 1

Response 200

{
  segments: integer
  blobs: 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 DELETE https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/replay/{segmentId} \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/replay/{segmentId}

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/replay/{segmentId}
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
segmentIdrequiredpathstringmin length 1

Response 200

{
  segment: {
    id: string
    replayId: string
    segmentId: integer
    replayType: "buffer" | "session"
    issueId: string | null
    eventId: string | null
    startedAt: string
    endedAt: string
    durationMs: integer
    eventCount: integer
    url: string | null
    evicted: integer
    masked: boolean
    stoppedReason: string | null
    sizeBytes: integer
    hasTranscript: boolean
    consentBasis: string | null
    createdAt: string
  }
  format: {
    name: "bucker.replay.interaction"
    version: string
  }
  chapters: {
    startMs: integer
    endMs: integer
    title: {
      value: string
      trust: "trusted" | "code" | "untrusted" | "quarantined"
    }
    actionCount: integer
    errorCount: integer
    rageClickCount: integer
    deadClickCount: integer
  }[]
  recording: {
    schemaVersion: string
    replay_id: string
    segment_id: integer
    events: Record<string, unknown>[]
    redactions: 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}/projects/{projectSlug}/replay/{segmentId} \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/replay/{segmentId}/traces

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/replay/{segmentId}/traces
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
segmentIdrequiredpathstringmin length 1

Response 200

{
  segmentId: string
  traces: {
    traceId: string
    firstAtMs: integer
    requestCount: integer
    failed: boolean
    errors: {
      eventId: string
      issueId: string | null
      shortId: string | null
      title: string | null
      projectSlug: string
      timestampMs: 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}/projects/{projectSlug}/replay/{segmentId}/traces \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/replay/detectors

Requires bearerAuth

Change what the friction detectors report for this project through the governed operation engine: one detector's thresholds, one suppression to add (one selector on one route, up to 30 days), or one to cancel. The act (friction_threshold.update, friction_suppression.create or friction_suppression.cancel) is derived from what would change, never from the body. 200 when applied; 202 with an approval request when a person must decide, after which the same body with approvalRequestId applies the approved plan once.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/replay/detectors
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  detector?: string
  thresholds?: Record<string, integer>
  suppress?: {
    route: string
    selector: string
    days?: integer
  }
  cancel?: {
    route: string
    selector: string
  }
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "approval_required" | "inert_draft"
  operation: {
    id: string
    action: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
  }
  riskClass: string
  plan: Record<string, unknown>
  decision?: "ALLOW" | "APPROVED"
  versionAfter?: string
  receiptSigned?: boolean
  approvalRequestId?: string | null
  decisionUrl?: string
  refusal?: {
    code: string
    message: string
  } | null
  eligibleApprovers?: integer
  minApprovers?: integer
}

Response 202

{
  status: "applied" | "approval_required" | "inert_draft"
  operation: {
    id: string
    action: string
    state: string
    planDigest: string
    targetVersionBefore: string
    targetVersionAfter: string | null
    riskClass: string
  }
  riskClass: string
  plan: Record<string, unknown>
  decision?: "ALLOW" | "APPROVED"
  versionAfter?: string
  receiptSigned?: boolean
  approvalRequestId?: string | null
  decisionUrl?: string
  refusal?: {
    code: string
    message: string
  } | null
  eligibleApprovers?: integer
  minApprovers?: 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}/replay/detectors \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/replay/friction

Requires bearerAuth

What the friction detectors found in recorded replay sessions: per route sessions and friction rate, the top elements, each detector with its version, state and the thresholds in force, active suppressions with their ends, and the linked issues. Name a detector and thresholds (for example detector=friction_rage&min_sessions=3) to add the 14-day backtest of that candidate. Sessions are recorded sessions: the recorder samples.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/replay/friction
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
daysqueryintegerdefault 7, min 1, max 14
detectorquery"friction_rage" | "friction_dead_2500" | "friction_dead_7000" | "friction_error_click" | "friction_slow_click" | "friction_form_abandon" | "friction_quick_back"one of "friction_rage" | "friction_dead_2500" | "friction_dead_7000" | "friction_error_click" | "friction_slow_click" | "friction_form_abandon" | "friction_quick_back"
clicksqueryinteger
window_msqueryinteger
min_sessionsqueryinteger
response_msqueryinteger
interaction_msqueryinteger
min_fieldsqueryinteger

Response 200

{
  windowDays: integer
  routes: {
    route: string
    sessions: integer
    frictionSessions: integer
    frictionRate: number
  }[]
  other: {
    routes: integer
    sessions: integer
  } | null
  topElements: {
    kind: string
    route: string
    selector: string
    sessions: integer
  }[]
  detectors: {
    id: string
    kind: string
    version: integer
    state: string
    grandfathered: boolean
    precision: {
      value: number | null
      labelledN: integer
    }
    thresholds: Record<string, number>
    tunable: {
      key: string
      min: number
      max: number
      unit: string
    }[]
    overridden: string[]
  }[]
  suppressions: {
    route: string
    selector: string
    days: integer
    until: string | null
  }[]
  issues: {
    issueId: string
    shortId: string
    kind: string
    status: string
    eventCount: integer
    lastSeen: string
    route: string | null
    selector: string | null
  }[]
  newestObservationAt: string | null
  basis: {
    set: string
    source: string
    sampled: boolean
    cohortFloor: integer
    segmentsRead: integer
    segmentsTruncated: boolean
    observationsRead: integer
    observationsTruncated: boolean
    note: string
  }
  backtest?: {
    windowDays: integer
    observationsRead: integer
    truncated: boolean
    candidates: {
      detector: string
      candidate: object
      current: object
      proposed: object
      issuesNoLongerOpened: integer
      issuesNewlyOpened: integer
      effect: "fewer" | "more" | "same"
      derivedAct: 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}/projects/{projectSlug}/replay/friction \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/replay/receipts

Requires bearerAuth

The deletion receipts of this project’s recordings, newest first: the session id, why it left (retention, erasure, rule or manual), its size and the digest of the signed receipt in the organization’s receipt log. Counts and ids only, never content.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/replay/receipts
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
limitqueryintegerdefault 50, min 1, max 100
beforequerystringmax length 120

Response 200

{
  data: {
    replayId: string
    reason: "retention" | "erasure" | "rule" | "manual"
    bytes: integer
    receiptDigest: string
    deletedAt: string
  }[]
  nextCursor: string | null
}

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}/replay/receipts \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/replay/sessions/{id}/evidence

Requires bearerAuth

One moment of a recorded session joined to the backend: the requests around it with their traces, the backend errors and error spans on those traces and on the session id, the issues the session belongs to, the release and deploy, the flag variants it evaluated, the change events just before it, and the funnel step (not_available until its anchors exist). Pick the moment with atMs (recorder clock, epoch ms) or anchor (failed_request, friction, issue_link). Every string is the customer’s own data.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/replay/sessions/{id}/evidence
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
idrequiredpathstringmin length 1, max length 128
atMsqueryintegermin 0, max 10000000000000
anchorquery"failed_request" | "friction" | "issue_link"one of "failed_request" | "friction" | "issue_link"
windowMsqueryintegermin 0, max 30000

Response 200

{
  schema: "session_evidence_v1"
  sessionId: string
  moment: {
    atMs: integer | null
    offsetS: integer | null
    basis: "given" | "failed_request" | "friction" | "issue_link" | "none"
  }
  window: {
    fromMs: integer
    toMs: integer
  }
  requests: {
    atMs: integer
    offsetMs: integer | null
    method: string
    path: string
    status: integer | null
    durationMs: number
    failed: boolean
    traceId: string | null
    backendErrors: integer
  }[]
  backendErrors: {
    eventId: string
    issueId: string | null
    shortId: string | null
    title: string | null
    type: string | null
    projectSlug: string
    traceId: string | null
    atMs: integer
    via: "trace" | "session"
  }[]
  errorSpans: {
    traceId: string
    spanId: string
    name: string
    service: string | null
    projectSlug: string
    atMs: integer
  }[]
  issues: {
    issueId: string
    shortId: string
    title: string
    via: "segment" | "link" | "event"[]
    anchorMs: number | null
  }[]
  release: {
    version: string
    environment: string | null
    releasedAt: string | null
    deploy: {
      name: string | null
      deployedAt: string
      status: string
      rollback: boolean
    } | null
  } | null
  flags: {
    key: string
    variant: string
    version: string
  }[]
  changes: {
    kind: string
    summary: string
    occurredAt: string
    source: string | null
    trust: string
  }[]
  funnelStep: {
    status: "not_available"
    reason: string
  }
  more: {
    requests: integer
    backendErrors: integer
    errorSpans: integer
    issues: integer
    flags: integer
    changes: integer
  }
  recordingBasis: "recorded" | "partial" | "unavailable"
}

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}/replay/sessions/{id}/evidence \
  -H "authorization: Bearer $BUCKER_TOKEN"

POST/orgs/{orgSlug}/projects/{projectSlug}/replay/sessions/{sessionId}/lifecycle

Requires bearerAuth

Change one recorded session’s standing. quarantine hides it from every list, read and export at once; hold keeps it past the retention window citing an issue of the project or a certificate (at most 90 days, 50 holds a project, always asks a person); release_hold cancels a hold. restore lifts a quarantine and delete removes the recording with a receipt: both are an organization owner’s act and are refused to agents and delegated tokens. 200 when applied; 202 with an approval request when a person must decide, after which the same body with approvalRequestId applies the approved plan once.

Parameters

Parameters for POST /orgs/{orgSlug}/projects/{projectSlug}/replay/sessions/{sessionId}/lifecycle
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
sessionIdrequiredpathstringmin length 1, max length 64

Request body (required) · application/json

{
  act: "quarantine" | "restore" | "hold" | "release_hold" | "delete"
  finding?: "scrubber" | "injection_scanner"
  cite?: {
    kind: "issue" | "certificate"
    ref: string
  }
  days?: integer
  reason: string
  approvalRequestId?: string
}

Response 200

{
  status: "applied" | "approval_required" | "inert_draft"
  act: string
  replayId: string
  operationId: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionUrl: string | null
  receiptSigned: boolean | null
  segmentsDeleted: integer | null
}

Response 202

{
  status: "applied" | "approval_required" | "inert_draft"
  act: string
  replayId: string
  operationId: string | null
  riskClass: string | null
  approvalRequestId: string | null
  decisionUrl: string | null
  receiptSigned: boolean | null
  segmentsDeleted: integer | null
}

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}/replay/sessions/{sessionId}/lifecycle \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/replay/sessions/{sessionId}/summary

Requires bearerAuth

The checked summary of one recorded session: outcome, intent, up to five key moments and chapter labels, each citing an anchor the server verified against the stored event stream. Off for every project until an organization owner switches session summaries on; then it is computed once by the workers and cached. Without a verified summary the answer says why and carries the deterministic chapters. Model-written text is untrusted.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/replay/sessions/{sessionId}/summary
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
sessionIdrequiredpathstringmin length 1, max length 64

Response 200

{
  sessionId: string
  state: "not_available" | "pending" | "unavailable" | "verified" | "rejected"
  reason: string | null
  failedCheck: "schema" | "unknown_anchor" | "unshown_anchor" | "kind_mismatch" | "duplicate_moment" | "uncited_claim" | "unknown_chapter" | "outcome_unsupported" | … 5 more | null
  promptVersion: string
  modelId: string | null
  generatedAt: string | null
  summary: {
    schema: "session_summary_v1"
    output: {
      outcome: "completed" | "abandoned" | "errored" | "unknown"
      outcomeCites: string[]
      intent?: object
      moments: object[]
      chapterLabels: object[]
    }
    cited: {
      id: string
      kind: "error" | "friction" | "navigation" | "interaction" | "vital" | "backend"
      offsetMs: integer
    }[]
    facts: {
      actions: integer
      errors: integer
      rage: integer
      dead: integer
      failedRequests: integer
      consoleErrors: integer
      durationS: integer
      chapters: integer
    }
    anchorSpec: string
  } | null
  chapters: {
    index: integer
    route: string
    actions: integer
    errors: integer
    rage: integer
    dead: integer
    startOffsetMs: integer
  }[]
  modelOutput: true
}

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}/replay/sessions/{sessionId}/summary \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/replay/settings

Requires bearerAuth

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/replay/settings
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Response 200

{
  enforceMasking: boolean
  maskSelectors: string[]
  blockSelectors: string[]
  ignoreSelectors: string[]
  allowUnmask: boolean
  errorSampleRate: number | null
  sessionSampleRate: number | null
  allowNetworkDetails: boolean
  replayRetentionDays: integer | null
  version: integer
  rules: {
    id: string
    match: "any" | "all"
    url?: string
    event?: string
    flag?: {
      key: string
      variant?: string
    }
    rate: number
    minDurationMs?: integer
  }[]
  minDurationMs: integer | null
  enforceRules: boolean
  sessionModel: {
    enabled: boolean
  }
  updatedAt: string | null
}

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}/replay/settings \
  -H "authorization: Bearer $BUCKER_TOKEN"

PUT/orgs/{orgSlug}/projects/{projectSlug}/replay/settings

Requires bearerAuth

Parameters

Parameters for PUT /orgs/{orgSlug}/projects/{projectSlug}/replay/settings
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1

Request body (required) · application/json

{
  enforceMasking?: boolean
  maskSelectors?: string[]
  blockSelectors?: string[]
  ignoreSelectors?: string[]
  allowUnmask?: boolean
  errorSampleRate?: number | null
  sessionSampleRate?: number | null
  allowNetworkDetails?: boolean
  replayRetentionDays?: integer | null
  rules?: {
    id: string
    match?: "any" | "all"
    url?: string
    event?: string
    flag?: {
      key: string
      variant?: string
    }
    rate: number
    minDurationMs?: integer
  }[]
  minDurationMs?: integer | null
  enforceRules?: boolean
  version?: integer
}

Response 200

{
  enforceMasking: boolean
  maskSelectors: string[]
  blockSelectors: string[]
  ignoreSelectors: string[]
  allowUnmask: boolean
  errorSampleRate: number | null
  sessionSampleRate: number | null
  allowNetworkDetails: boolean
  replayRetentionDays: integer | null
  version: integer
  rules: {
    id: string
    match: "any" | "all"
    url?: string
    event?: string
    flag?: {
      key: string
      variant?: string
    }
    rate: number
    minDurationMs?: integer
  }[]
  minDurationMs: integer | null
  enforceRules: boolean
  sessionModel: {
    enabled: boolean
  }
  updatedAt: string | null
}

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 PUT https://api.bucker.io/orgs/{orgSlug}/projects/{projectSlug}/replay/settings \
  -H "authorization: Bearer $BUCKER_TOKEN" \
  -H 'content-type: application/json' \
  -d '{ … }'

GET/orgs/{orgSlug}/projects/{projectSlug}/replay/setup-health

Requires bearerAuth

Why replay, web vitals or heatmap data is missing for this project, over the last 7 days: checks that each answer pass, warn, fail or unknown with the counts and window behind them and one named fix, the replay configuration in force and its version, the stored segments' own fields and the SDK inventory. A check that cannot tell says unknown, never pass.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/replay/setup-health
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
includequery"preview"one of "preview"

Response 200

{
  windowDays: integer
  generatedAt: string
  cells: {
    id: string
    area: "replay" | "vitals" | "heatmap"
    state: "pass" | "warn" | "fail" | "unknown" | "not_applicable"
    counts: Record<string, number>
    window: {
      from: string
      to: string
    }
    basis: "server_observed" | "client_reported"
    reason: string | null
    fix: {
      kind: "tool" | "human_act"
      name: string
      text: string
      governed: boolean
    } | null
    pendingCard: string | null
    reasons?: {
      reason: string
      count: integer
    }[]
  }[]
  summary: {
    pass: integer
    warn: integer
    fail: integer
    unknown: integer
    not_applicable: integer
  }
  replayConfig: {
    version: string
    enforceMasking: boolean
    sessionSampleRate: number | null
    errorSampleRate: number | null
    allowNetworkDetails: boolean
    settingsVersion: integer
    enforceRules: boolean
    rules: integer
    minDurationMs: integer | null
  }
  quarantine: {
    total: integer
    byReason: Record<string, integer>
  }
  receipts: {
    total: integer
    byReason: Record<string, integer>
  }
  segments: {
    stored: integer
    unmasked: integer
    evictedEvents: integer
    stopped: {
      reason: string
      count: integer
    }[]
  }
  sdks: {
    name: string
    version: string
    family: "bucker" | "sentry" | "otel" | "unknown"
    envelopes: integer
    lastSeenAt: string
    hints: string[]
  }[]
  sdksOmitted: integer
  preview?: {
    status: "not_available"
    owner: string
    reason: 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}/projects/{projectSlug}/replay/setup-health \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/replay/vitals

Requires bearerAuth

Web vitals per route template: the p75 of LCP, INP, CLS, FCP and TTFB in the newest complete hour against the median of the seven days that ended a day ago, the sample count, the basis (sampled page views, never a share of traffic), the rating, and the open regression issue. Name backtest=true with candidate thresholds (for example mad_multiplier=4) to add what the last 14 days would have done under them. Route templates are the customer’s page text.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/replay/vitals
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
hoursqueryintegerdefault 24, min 1, max 168
routesqueryintegerdefault 5, min 1, max 25
routequerystringmin length 1, max length 200
vitalquery"LCP" | "INP" | "CLS" | "FCP" | "TTFB"one of "LCP" | "INP" | "CLS" | "FCP" | "TTFB"
backtestquery"true" | "false"default "false", one of "true" | "false"
sustained_hoursqueryinteger
mad_multiplierqueryinteger
min_samplesqueryinteger
poor_rise_percentqueryinteger

Response 200

{
  windowHours: integer
  routes: {
    route: string
    n: integer
    basis: "field_sampled" | "field_unsampled"
    vitals: {
      vital: "LCP" | "INP" | "CLS" | "FCP" | "TTFB"
      state: "regressed" | "ok" | "not_enough_data"
      p75: number | null
      baseline: number | null
      delta: number | null
      rating: "good" | "needs_improvement" | "poor" | null
      n: integer | null
      hour: string | null
      reason: "sustained_hours_missing" | "baseline_short" | "no_points" | null
      issue: object | null
    }[]
  }[]
  routesOmitted: integer
  regressions: integer
  detector: {
    id: string
    version: integer
    state: string
    thresholds: Record<string, number>
    overridden: string[]
    revision: integer
  }
  basis: {
    source: "pageload_spans"
    tier: "rollup"
    rollup: string
    sampled: true
    basis: "field_sampled" | "field_unsampled"
    rowsRead: integer
    truncated: boolean
    note: string
  }
  newestHourAt: string | null
  backtest?: {
    windowDays: integer
    rowsRead: integer
    truncated: boolean
    routes: integer
    current: {
      firingHours: integer
      issues: integer
    }
    proposed: {
      firingHours: integer
      issues: integer
    }
    issuesNoLongerOpened: integer
    issuesNewlyOpened: integer
    effect: "fewer" | "more" | "same"
    derivedAct: string
    candidate: Record<string, number>
  }
}

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}/replay/vitals \
  -H "authorization: Bearer $BUCKER_TOKEN"

GET/orgs/{orgSlug}/projects/{projectSlug}/replay/vitals/attribution

Requires bearerAuth

Why a route’s web vitals were slow: per route template the ranked findings of the deterministic ruleset (for example lcp_resource_late, inp_long_script, cls_unsized_media), each with the affected views it matched and its share of the affected views of that metric, over the last days. Counts and Bucker’s own rule names only: no element, resource, script or person. Needs the project’s analytics gate open and the web vitals pillar on. Route templates are the customer’s page text.

Parameters

Parameters for GET /orgs/{orgSlug}/projects/{projectSlug}/replay/vitals/attribution
NameInTypeNotes
orgSlugrequiredpathstringmin length 1
projectSlugrequiredpathstringmin length 1
daysqueryintegerdefault 7, min 1, max 30
routesqueryintegerdefault 5, min 1, max 25
routequerystringmin length 1, max length 200
metricquery"lcp" | "inp" | "cls"one of "lcp" | "inp" | "cls"

Response 200

{
  ruleset: string
  windowDays: integer
  rankedBy: "views" | "views_x_delta"
  routes: {
    route: string
    affectedViews: Record<string, integer>
    findings: {
      metric: "lcp" | "inp" | "cls"
      rule: string
      label: string
      views: integer
      share: number
      score: number
    }[]
  }[]
  routesOmitted: integer
  truncated: boolean
}

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}/replay/vitals/attribution \
  -H "authorization: Bearer $BUCKER_TOKEN"