# 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` and a `claim_url` to hand to the human. 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. Account-scoped destructive actions (`POST /api/billing/subscription/cancel`, future account deletion) 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` — default is `summary,tenants,buckets,cost,notifications`. Heavy slices are opt-in. - `?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", "next_cursor" } }], "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" }, "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" }, "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", "rate_limit_per_minute" } } --- ## Plan-aware caps | Cap | Free | Plus | Pro | | --- | --- | --- | --- | | `?window` max | 7d | 30d | 90d | | `events_max` per tenant | 50 | 200 | 500 | | `ledger_max` | 100 | 500 | 2,000 | | `notifications_max` | 50 | 200 | 500 | | `tenants_enumerated_max` | 25 | 100 | 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' ### 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 (session-only) - `POST https://cohesivity.ai/api/billing/subscription/cancel` — requires an interactive Cohesivity sign-in session; rejects `coh_man_*`. --- ## Offerings coverage Every metered service surfaces through at least one of `resources[]`, `shared_buckets[]`, or `usage.by_service[]`. Pure-fluid services (Gemini, 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.