Get Metrics Refresh Status

Metrics storage and access

Use a registered metrics-capable database. Specify db_id when multiple database IDs are available; selecting table requires db_id. Configured authorization uses metrics:read for reads and metrics:write for refresh.

The effective user_id is fixed for scoped callers: JWT user isolation is opt-in, while non-admin service-account PAT callers self-scope. An unscoped caller can select a user. Current RemoteDb GET/refresh forwarding does not pass an explicit user filter; do not assume a local admin filter is forwarded to another AgentOS. Downstream credential-based scoping is separate.

Process-local status

Poll this endpoint after a background refresh. Refresh status and its overlap guard live in the router process, keyed by database ID. Another replica or a restarted process can report idle even if a different process refreshed the database. RemoteDb asks the remote AgentOS for its status.

GET/metrics/refresh/status

Get the status of the most recent metrics refresh for the target database. Returns 'running' while a refresh is in progress, then 'completed' or 'failed' with the finish timestamp — the state updates even when a refresh completes without writing new data. Returns 'idle' if no refresh has been triggered since this server process started. For remote databases the status is fetched from the remote AgentOS. Intended for polling after starting a background refresh via POST /metrics/refresh?background=true.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

db_id?|

Database ID to get the refresh status for

table?|

Table to get the refresh status for

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request GET 'https://example.com/metrics/refresh/status'
{  "status": "completed",  "started_at": "2025-08-12T08:01:47Z",  "finished_at": "2025-08-12T08:01:49Z"}