# Cohesivity — Account Observability `GET https://cohesivity.ai/api/observability` is the single endpoint that returns the complete observability picture for an entire Cohesivity account: the calling tenant, every sibling tenant on the same account, the shared wallet, every offering's usage, account-wide cost rollups, notifications, and derived advisories. The endpoint is front-door served (always at the latest shape regardless of any tenant's `runtime_profile`) and read-only. --- ## Auth Accepts EITHER: - `Authorization: Bearer ` from any **claimed** tenant on the account, OR - A Cohesivity sign-in session cookie (`coh_user_session`). Ephemeral tenants are rejected with `403 observability_requires_claim`; run the primary one-click claim handoff (`POST https://cohesivity.ai/api/claim/url` → share `approval_url` at `https://cohesivity.ai/c/` → poll `https://cohesivity.ai/api/wait`) before retrying. The `claim_url` in recovery errors is manual-key fallback only. Bad keys return `401`. Foreign tenants are never enumerated. The response includes `auth: { mode: "session" | "tenant_management_key", via_tenant_id }` and the same information mirrored on the `X-Cohesivity-Account-Auth` response header. --- ## Blast-radius statement > Once a tenant is claimed, its `coh_man_*` key authenticates account-scoped READ endpoints (`/api/observability`) and constructive billing actions (`POST /api/billing/topup`, `POST /api/billing/subscription`) for the entire account. `POST /api/billing/subscription/cancel` is a deliberate destructive-action exception and also accepts session OR owned claimed `coh_man_*`; any non-terminal Razorpay subscription on the account can be cancelled. Future destructive account actions still require an interactive Cohesivity sign-in session. Each sibling tenant has its own management key — a key from one tenant cannot delete or modify resources on another. --- ## Query parameters - `?tenant_id=` — focus one tenant in the response (still returns all-account context). - `?include=summary,tenants,buckets,cost,notifications,events,ledger,deploy_history,end_user_sessions,poller_health,webhook_history,recent_events` — default is `summary,tenants,buckets,cost,notifications`. Heavy slices are opt-in. `events` is the top-level SQL-backed usage-event page; when `tenants` is also included, the same event page is mirrored into each tenant row. - `?window=24h|7d|30d|90d` — time-bound rollups. Capped per plan (Free 7d, Plus 30d, Pro 90d). - `?since=` — delta poll for events / ledger / notifications. - `?cursor=`, `?limit=` — pagination, capped per plan. - `?empty_buckets=true` — opt-in to also return zero-usage buckets (default filters them out). --- ## Response shape (high-level) { "auth": { "mode": "tenant_management_key", "via_tenant_id": "swift-fox-sleeping" }, "generated_at": "2026-04-28T07:50:00.000Z", "request_id": "req_...", "account": { "user_id": 7, "email": "...", "name": "...", "plan": "plus", "enforcement_mode": "enforce", "status": "active", "subscription": { "plan", "status", "current_period_start", "current_period_end", "cancel_at_period_end", "short_url" }, "wallet": { "balance_cents", "reserved_cents", "available_cents", "monthly_grant_cents", "month_start", "month_end", "this_month_topup_cents", "this_month_spent_cents", "spent_by_tenant_this_month": [{ "tenant_id", "cost_cents", "is_self" }], "spent_by_service_this_month": [{ "service", "cost_cents" }] } }, "shared_buckets": [{ "service", "metric", "window", "limit", "used_account_total", "pct_account", "fluid_overflow_enabled", "paused", "by_tenant": [{ "tenant_id", "used", "pct_of_account_used", "is_self" }] }], "rate_limits_pressured": [ /* same shape, only when pct >= 50 */ ], "tenants_summary": { "total", "by_lifecycle", "by_status", "paused_count", "runtime_drift_count" }, "tenants": [{ "tenant_id", "is_self", "lifecycle", "status", "runtime": { "profile", "version", "is_latest_live" }, "claimed_at", "paused_at", "pause_reason", "resources": [ /* one entry per provisioned offering */ ], "usage": { "window", "event_count", "cost_cents", "by_service": [{ "service", "events", "cost_cents" }], "by_day": [{ "date", "events", "cost_cents" }] }, "current_month_buckets": [{ "service", "metric", "this_tenant_used", "account_total_used", "account_limit", "this_tenant_pct_of_account", "fluid_overflow" }], "pending_actions": [{ "action_type", "status", "next_attempt_at" }], "recent_events": { "items" } /* only present when include=events also runs */ }], "account_cost": { "this_month_cents", "last_month_cents", "by_service", "by_tenant", "by_day" }, "notifications": { "items": [{ "id", "ts", "code", "severity", "message", "tenant_id", "metadata" }], "next_cursor" }, "events": { "items": [{ "id", "ts", "tenant_id", "service", "operation", "source", "metrics", "cost_cents", "request_id" }], "next_cursor" }, "ledger": { "items", "next_cursor" }, "deploy_history": { "by_tenant": { "": [{ "deployment_id", "ts", "status" }, ...] } }, "end_user_sessions":{ "by_tenant": { "": { "active_count", "total_users" } } }, "poller_health": { "by_source": { "vercel_observability": { "last_bucket_end", "age_minutes" }, ... } }, "webhook_history": { "items": [{ "event_id", "event_type", "processed_at" }], "next_cursor" }, "recent_events": { "items": [{ "ts", "event", "tenant_id", "request_id", /* per-event projected fields */ }], "next_cursor" }, "advisories": [{ "code": "shared_bucket_pressure | rate_limit_pressure | fluid_low | fluid_exhausted | subscription_renewing_soon | subscription_will_cancel | runtime_drift | paused_tenant | enforce_advisory | monthly_grant_pending", "action", "target_url", /* code-specific fields */ }], "limits_for_this_response": { "plan", "window", "events_max", "ledger_max", "notifications_max", "tenants_enumerated_max", "recent_events_max", "rate_limit_per_minute" } } --- ## Recent events slice (`?include=recent_events`) Account-wide tail of customer-relevant events across all offerings, sourced from Axiom. Use it to answer "what just happened on my account, in time order" — auth events (login_started, authorize, login_failed, consent_denied, token_refreshed, logout), per-offering API requests with status + duration, webhook deliveries, and Vercel deploys. Cursor pagination follows the same shape as the other slices: `?since=` for delta polls, `?cursor=` to continue an in-progress page, `?limit=` clamped to the plan cap. If both `since` and `cursor` are passed, `cursor` wins. Two things to know: - **2-3 minute propagation lag.** Logs flow through Cloudflare Logpush before Axiom indexes them; do not expect events to appear in this slice within seconds of emission. - **Only customer-relevant event types are surfaced; internal worker logs are filtered server-side** by an explicit allowlist + per-event field projection. Stack traces, internal IDs, and upstream payloads cannot leak even if they appear in the underlying log line. --- ## Plan-aware caps | Cap | Free | Plus | Pro | | --- | --- | --- | --- | | `?window` max | 7d | 30d | 90d | | `events_max` per call | 50 | 200 | 1,000 | | `ledger_max` | 25 | 100 | 500 | | `notifications_max` | 25 | 100 | 500 | | `tenants_enumerated_max` | 50 | 200 | 1,000 | | `recent_events_max` per call | 50 | 200 | 500 | Caps are echoed on every response under `limits_for_this_response`. --- ## Quick examples ### Default account snapshot curl -s -H "Authorization: Bearer " \ https://cohesivity.ai/api/observability ### Full picture, last 30 days, all heavy slices curl -s -H "Authorization: Bearer " \ 'https://cohesivity.ai/api/observability?window=30d&include=summary,tenants,buckets,cost,notifications,events,ledger,deploy_history,end_user_sessions,poller_health,webhook_history,recent_events' ### Delta poll since timestamp curl -s -H "Authorization: Bearer " \ 'https://cohesivity.ai/api/observability?include=notifications,events,ledger&since=2026-04-27T00:00:00Z' --- ## Constructive billing actions (same auth) - `POST https://cohesivity.ai/api/billing/topup` — add fluid (claimed `coh_man_*` OR session) - `POST https://cohesivity.ai/api/billing/subscription` — create or upgrade subscription (claimed `coh_man_*` OR session) ## Destructive billing action - `POST https://cohesivity.ai/api/billing/subscription/cancel` — accepts a session OR owned claimed `coh_man_*`; cancels any non-terminal subscription on the account. --- ## Offerings coverage Every metered service surfaces through at least one of `resources[]`, `shared_buckets[]`, or `usage.by_service[]`. Pure-fluid services (OpenAI, AI Gateway, Deepgram, Exa) have no fixed bucket but still appear in `usage.by_service` and `wallet.spent_by_service_this_month` so agents see their cost without lookup. See https://cohesivity.ai/offerings for per-resource limits and usage shape.