CapyDB
Start free
CapyDB/ docs
ReferenceAPI

Observability

Live database metrics for a project.

All docs

Get live project metrics

GET
/v1/projects/{projectID}/observability

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/observability"
{  "observability": {    "active_queries": [      {        "duration_ms": 0,        "pid": 0,        "query": "string",        "state": "string",        "username": "string",        "wait_event": "string",        "wait_event_type": "string"      }    ],    "alerts": [      "string"    ],    "connection_count": 0,    "connection_limit": 0,    "connection_usage_percent": 0,    "database_size_bytes": 0,    "pg_stat_statements": true,    "slow_queries": [      {        "calls": 0,        "mean_time_ms": 0,        "query": "string",        "rows": 0,        "total_time_ms": 0,        "query_id": 0,        "shared_blks_hit": 0,        "shared_blks_read": 0,        "temp_blks_read": 0,        "temp_blks_written": 0,        "jit_time_ms": 0.1      }    ],    "storage_limit_bytes": 0,    "storage_usage_percent": 0  }}

Get project metrics history

GET
/v1/projects/{projectID}/observability/history

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

Query Parameters

hours?integer

Trailing window in hours, between 1 and 720 (default 24).

Range1 <= value <= 720
Default24

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/observability/history"
{  "samples": [    {      "active_queries": 0,      "avg_query_ms": 0,      "blocked_queries": 0,      "cache_hit_ratio": 0,      "connection_limit": 0,      "connections": 0,      "cpu_cores_used": 0,      "cpu_quota_cores": 0,      "dead_tuples": 0,      "deadlocks": 0,      "mem_limit_bytes": 0,      "mem_usage_bytes": 0,      "rollback_ratio": 0,      "rows_read_per_sec": 0,      "rows_written_per_sec": 0,      "sampled_at": "2019-08-24T14:15:22Z",      "slow_queries": 0,      "storage_bytes": 0,      "storage_limit_bytes": 0,      "temp_bytes": 0,      "tps": 0    }  ]}

Get project query statistics

GET
/v1/projects/{projectID}/observability/queries

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

Query Parameters

hours?integer

Trailing window in hours, between 1 and 168 (default 24).

Range1 <= value <= 168
Default24

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/observability/queries"
{  "queries": [    {      "query_hash": "string",      "calls": 0,      "mean_exec_ms": 0,      "query": "string",      "rows": 0,      "total_exec_ms": 0    }  ]}

List project alerts

GET
/v1/projects/{projectID}/alerts

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/alerts"
{  "alerts": [    {      "acknowledged_at": "2019-08-24T14:15:22Z",      "id": "string",      "kind": "storage",      "last_notified_at": "2019-08-24T14:15:22Z",      "limit_value": 0,      "observed_value": 0,      "project_id": "string",      "resolved_at": "2019-08-24T14:15:22Z",      "severity": "warning",      "triggered_at": "2019-08-24T14:15:22Z"    }  ]}

Acknowledge a project alert

POST
/v1/projects/{projectID}/alerts/{alertID}/acknowledge

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

alertID*string

Project alert identifier.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/projects/string/alerts/string/acknowledge"
{  "alert": {    "acknowledged_at": "2019-08-24T14:15:22Z",    "id": "string",    "kind": "storage",    "last_notified_at": "2019-08-24T14:15:22Z",    "limit_value": 0,    "observed_value": 0,    "project_id": "string",    "resolved_at": "2019-08-24T14:15:22Z",    "severity": "warning",    "triggered_at": "2019-08-24T14:15:22Z"  }}

Get one query's statistics history

GET
/v1/projects/{projectID}/observability/queries/{queryHash}

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

queryHash*string

The statement's identity hash from the top-queries listing (32-character hex digest).

Match^[0-9a-f]{32}$

Query Parameters

hours?integer

Trailing window in hours, between 1 and 168 (default 24).

Range1 <= value <= 168
Default24

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/observability/queries/string"
{  "query": {    "query_hash": "string",    "query": "string",    "window_calls": 0,    "window_total_exec_ms": 0,    "window_mean_exec_ms": 0,    "window_rows": 0,    "points": [      {        "captured_at": "2019-08-24T14:15:22Z",        "calls": 0,        "total_exec_ms": 0,        "rows": 0,        "mean_exec_ms": 0,        "calls_per_sec": 0      }    ]  }}

Get project database logs

GET
/v1/projects/{projectID}/logs

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

Query Parameters

hours?integer

Trailing window in hours (default 1). Up to 720 (30 days) on deployments with the shipped-log archive; 168 (7 days) otherwise - the API rejects windows beyond the deployment's cap. Windows older than 168 hours are served from the archive. Ignored when cursor is set.

Range1 <= value <= 720
Default1
cursor?string

Resume strictly after a previously returned entry's cursor (tail mode). Takes precedence over hours.

severity?string

Comma-separated severity filter (debug, log, info, notice, warning, error, fatal, panic, detail). Empty means all severities.

limit?integer

Maximum entries returned, between 1 and 500 (default 200). The newest entries are kept.

Range1 <= value <= 500
Default200

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/logs"
{  "logs": {    "entries": [      {        "timestamp": "2019-08-24T14:15:22Z",        "severity": "debug",        "message": "string",        "cursor": "string"      }    ],    "next_cursor": "string"  }}

Stream project database logs (SSE)

GET
/v1/projects/{projectID}/logs/stream

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

Query Parameters

hours?integer

Trailing window in hours, between 1 and 168 (default 1). Ignored when cursor is set.

Range1 <= value <= 168
Default1
cursor?string

Resume strictly after a previously returned entry's cursor (tail mode). Takes precedence over hours.

severity?string

Comma-separated severity filter (debug, log, info, notice, warning, error, fatal, panic, detail). Empty means all severities.

limit?integer

Maximum entries returned, between 1 and 500 (default 200). The newest entries are kept.

Range1 <= value <= 500
Default200

Response Body

text/event-stream

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/logs/stream"
"string"

Stream project lifecycle events (SSE)

GET
/v1/projects/{projectID}/events

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

Response Body

text/event-stream

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/events"
"string"

Get index suggestions for a project

GET
/v1/projects/{projectID}/advisor/indexes

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

Query Parameters

min_filter?integer

Minimum average number of rows a predicate must filter before it is considered (default 1000). Lower it on a quiet database.

Range1 <= value <= 10000000
Default1000
min_selectivity?integer

Minimum average selectivity percentage for a predicate to be considered (default 30).

Range1 <= value <= 100
Default30

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/advisor/indexes"
{  "advisor": {    "available": true,    "min_filter": 0,    "min_selectivity": 0,    "missing_extensions": [      "string"    ],    "reason": "string",    "cost_estimates_available": true,    "size_estimates_available": true,    "suggestions": [      {        "ddl": "string",        "estimated_cost_reduction_pct": 0.1,        "estimated_size_bytes": 0,        "index_method": "string",        "query_id": 0,        "table": "string"      }    ]  }}

List indexes that are not earning their cost

GET
/v1/projects/{projectID}/advisor/index-hygiene

Authorization

AuthorizationBearer <token>

Org or project-scoped API key, format capy_live_...; Clerk session tokens also accepted.

In: header

Path Parameters

projectID*string

Project id.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/projects/string/advisor/index-hygiene"
{  "hygiene": {    "available": true,    "reason": "string",    "observation_window_seconds": 0,    "stats_reset_at": "2019-08-24T14:15:22Z",    "min_index_size_bytes": 0,    "unused_indexes": [      {        "schema": "string",        "table": "string",        "index": "string",        "size_bytes": 0,        "index_scans": 0,        "definition": "string",        "drop_statement": "string"      }    ],    "redundant_indexes": [      {        "schema": "string",        "table": "string",        "index": "string",        "size_bytes": 0,        "covered_by": "string",        "definition": "string",        "drop_statement": "string"      }    ],    "reclaimable_bytes": 0  }}

Studio

SQL console and table data browser/editor.

Integrations

Vercel, Netlify and Cloudflare deployment integrations, auth-provider user sync (Clerk, Auth0, Better Auth), and their inbound webhooks.